Chapter 7: The Discovery Process
Phase 1: Extraction
Kickoff
There are a couple of components to the extraction phase of discovery: extracting client motives and goals, determining feasibility and risk, and coming to an agreement on what to build that fits within our three-pronged framework. Additionally, setting expectations and building a relationship around authority, expertise, and trust.
The first component that should be determined is understanding client motives and goals. This should typically be handled during the first or kickoff meeting with the client. Note that you may have to mandate clear power distribution amongst stakeholders before you can tackle this. Utilize the “why” methodology to derive business and personal goals and motives amongst stakeholders. Note that, like in the Uber example, many clients come in with a perceived solution to their goals, but it’s our job to determine what the best solution actually is. Expectation setting is key here as well, along with relationship handoff acknowledgment. Specifically, many times the client has built a relationship with sales staff and has already explained their goals, so it’s important to acknowledge this and give rationale for any redundancy. Let’s walk through a quick process on how to handle this first step in the engagement.
First, allow for the person with the existing relationship to introduce and vouch for you (typically sales). Then set expectations and goals for the call (having a presentation here is helpful to indicate preparedness and organization). Start with the goals first, at a macro level, and then move into the micro level. “The goal of the discovery process is to determine what to build that aligns with your goals, is feasible, and conforms to your budget and timeline expectations. Now in relation to this specific call, I would like to understand your goals in relation to this project and what the core problem you’re trying to solve is. I understand that you may have explained some of these things to our growth team, but it’s important for me to understand them directly. Let me know if you have any questions.” Then move to setting expectations. “That said, I would also like to lay some ground rules. First, it’s important that we designate a lead on your side for this project who owns this engagement. Not doing so will gravely impact the progression of this project. Next, it’s important to understand communication channels. We plan on holding weekly sync meetings and having async communication on Slack. Note that we typically respond to async messages within a day. It’s important that the lead of your project joins all sync meetings or notifies us at least a day before that we need to postpone the meeting. Lastly, I want to reiterate that the goal of this process is to determine what to build. This may be different from what your original idea is, but it’s our job to set you up for success, and we will be brutally honest about what our recommendations are. Any questions?” By doing this, you lay a solid foundation for both the relationship and the project progression.
Next, we move into identifying the client’s goals and motives. Note that what the client wants to build is oftentimes not the best path for what should be built to meet their goals within project constraints. Try to keep your line of questioning predicated around problems, not solutions. Do not ask “What do you want to build?” — say “Walk me through the problem you are trying to solve.” If the conversation starts trending toward solutions, utilize the “Why” methodology to bring it back to the problem level. Additionally, remember that it’s important to understand the personal level as well. With nuance, determine what personal problem is at play and determine what the personal goals are. Once you have a good understanding of the business and personal goals, we can move into identifying project constraints — namely, determining when the expected project completion is and what budget capacity is.
It’s still beneficial to understand what the client’s solution is as well. Assuming you get to a point where you have a clear picture of the problems and motives of the client as well as the constraints, open up the floor for their proposed solution or vision. Here is where you may find it helpful to understand industry-specific aspects of the project, investigate and understand the inspiration behind the client’s vision, and clock aspects of the project that the client would only know — for example, if they are an industry vet in an obscure vertical.
Kickoff Meeting Checklist
Before the Call:
During the Call — Structure:
During the Call — Extraction:
Closing the Call:
You should now have a good understanding of project constraints, goals, and client vision. We can set the agenda for the next phase — scope (“what”) determination. Reaffirm your understanding of the project landscape with the client by summarizing and allowing for clarification. Let them know that you may reach out to them with questions later on as well. Then, let the client know that you will be conducting research and providing them with a formal recommendation on what to build, with a target date in mind to complete your research. Do not prepare a recommendation unless you have a clear understanding of project goals, constraints, and vision.
Research
When conducting research, it’s important to keep in mind the dependencies of the project. First, we want to identify any holistic project blockers within the constraints of the project — technical impossibilities or expenses, regulatory constraints or expensive requirements, and so on. This should be the first wave of research: identifying what is a complete showstopper, and whether there’s any way to navigate around it. Typically, the client’s vision is a good place to start as a basis for research, especially if you are utilizing AI tools. Ideally, the client’s vision is completely feasible, solves their problem, and fits within project limitations, so it’s best to start there. If you’ve identified, based on experience, that something is already misaligned — for example, in the Uber scenario, where it’s very obvious that something doesn’t fit within our three-pronged framework — work from the closest next solution. In the Uber example, we know that recreating Uber is not possible, but what if we just created Uber for taxis in Houston? If you prompt AI to research the feasibility of Uber for taxis in Houston, the technical constraint of the gap in software that integrates with taxi fares would expose itself. Once this is identified, investigate making that software integration, and so on. Essentially, we want to find what is closest aligned to the client’s vision yet still feasible. The only situation where the client’s vision should be disregarded completely is if it doesn’t solve their core problem. This is rare, but it does happen, in which case you should formulate your own solution to the problem and follow the above process. It’s important to note that the usage of AI at this step should only be for information aggregation. Each claim that it makes should be audited by you. For example, if it says that there is a regulatory blocker, prompt it to give you the exact language of the blocker. Ensure that you audit any claim related to feasibility by AI.
In larger projects with mid-size and enterprise-level clients, this research phase is more nuanced and can require a lot of back and forth within the members of the organization. Functionally, what this does is increase the non-public and hard-to-access components of risk within the project that must be discovered. For example, let’s say that a client has a vision for integrating a payment processing system with an internally built accounting system. You cannot determine feasibility by only relying on public sources, and AI cannot holistically drive this process either. In order to properly diagnose feasibility of the integration, you must get access to the documentation of the internally built accounting system or its codebase. This may require you to reach out to the person who maintains the system within the organization, and they might be on vacation. The point is: it’s important to make sure that you are properly determining all potential impacts on project feasibility regardless of how hard they are to access.
Research Phase: Decision Flowchart
┌──────────────────────────────────────┐ │ │ │ Start with client's original vision │ │ │ └──────────────────┬───────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ │ │ Is it technically feasible? │ │ │ └───────────┬──────────────┬───────────┘ │ │ YES │ │ NO │ │ ▼ ▼ ┌──────────────────┐ ┌──────────────────────────────────────┐ │ │ │ │ │ Check against │ │ Can a modified version work? │ │ project │ │ (closest to client's vision) │ │ constraints │ │ │ │ │ └───────────┬──────────────┬───────────┘ └────────┬─────────┘ │ │ │ YES │ │ NO ▼ │ │ ┌──────────────────┐ ▼ ▼ │ │ ┌──────────────────┐ ┌──────────────────────────┐ │ Fits within │ │ Check against │ │ │ │ budget & │ │ constraints │ │ Does client's vision │ │ timeline? │ │ (loop back) │ │ solve their problem? │ │ │ │ │ │ │ └──┬───────────┬───┘ └──────────────────┘ └──────┬─────────┬────────┘ │ │ YES │ │ NO YES │ │ NO ▼ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ │ │ │ │ │ │ Iterate │ │ Formulate │ │ Proceed │ │ Remove non- │ │ closest │ │ your own │ │ to biz │ │ critical │ │ version │ │ solution │ │ research │ │ features │ │ │ │ │ │ │ │ until it fits │ └────────────┘ └────────────┘ └──────────┘ │ │ │ Still no? │ │ Return to │ │ problem only │ │ │ └──────────────────┘Research Checklist:
Once we have a solution that we know is possible to build, we need to cross-reference it with project constraints. Though every organization’s pricing and timeline model is different, we recommend, at Benmore, that to a conservative level, the project should comfortably be able to be completed within project constraints. If it cannot, we have to move to determining features that are not critical and remove them until we get to this position. In the case that the project is not feasible without removing core features, we need to take a step back and return to the problem alone and disregard the client’s vision.
One important thing to note is qualifying why we don’t just disregard the client’s vision altogether and solely focus on problem solving. There are a couple reasons for this, some obvious. The client wants their vision — the one they have had in their head — to come to life, so the further the deviation, the more pushback there will be and the more explanation is needed. There is also a level of project understanding that cannot be communicated in a kickoff, and this should not be trivialized. Fundamentally, especially in niche industries, it would be hard for a logistics veteran to comprehensively explain why they know that their vision would be best without transferring their 20 years of experience to us. It would also be hard for us to come to a solution that is better without having their vision as a starting point. Couple that with a self-funded client who is personally tied to their vision, and if they have been gaslit by AI tools to be emotionally tied to their vision, you’re looking at a rough hill to climb by recommending something completely different. This will be touched on further when it comes to preparing and presenting a recommendation.
Assuming that we have a solution in mind that fits the client’s vision, solves their problem, and fits within project constraints, we can now perform business outlook research. For startups, this is more predicated around industry trends and gaps, competitor analysis and landscape, and target audience. For SMBs and above, this is more predicated around business outcomes, cost reduction, enterprise value, and long-term adoption metrics. Lastly, looking at the solution, it’s important to get a feeling for what the success criteria should be. Until the solution is agreed upon, true success criteria cannot be derived, but it’s not a bad idea to note a couple ideas or examples. Assuming that there are no major red flags here, we can move into consolidating all of this and preparing it for the client. As a final check, ensure that the solution fits within the three-pronged framework:
Scope must conform to the client’s vision, motivations, and goals — everything in the scope must match or be directionally aligned with their end goals. Risk must conform to scope — all risk must be properly represented, and there should be no inherent business or technical risk so grave that it cannot be accommodated. These three pillars must all conform to the project’s time and budget constraints. If this model does not hold, the project will not work.
Recommendation and Agreement
When preparing and presenting a recommendation on what to build, we must keep in mind the distance between the client’s original vision and what our recommendation is. Any deviation from the original vision must be qualified by our research, and often a summary of our train of thought and how we arrived at the recommendation helps provide visibility and facilitates a client’s understanding of our process. This is the part of the project that typically receives the most pushback, as it’s essentially a reality check for many clients. Expect some level of surprise here and correlate your expectation with how far the recommendation deviates from the client’s original vision. Note that the further the recommendation is from the vision, the more rationale you will have to provide. If the vision has been completely discarded, you must provide rationale as to why and tie your explanation to solving the client’s problem.
Visuals are extremely effective at this stage. Being able to display a graphic that shows how your recommendation is directly aligned with the client’s problem and vision — with explanations as to the gaps — can accelerate understanding. It’s also helpful to visually show why their original vision is unfeasible. If there is not a feasibility issue with their vision but the project isn’t possible due to time or budget constraints, it’s effective to outline what the implications of building their entire vision would entail.
Essentially, the client has had this idea for a while. Likely they’ve been gaslit by AI and have invested time and emotions into it. If we are to propose a deviation from this, it must be communicated effectively and be extremely sound. This is just the nature of scoping in the modern era. Let’s discuss how to communicate the recommendation and handle pushback.
First, your recommendation is yours, backed by your experience, your expertise, and your effort. Stand on it. Present it as such. When going into build determination discussions, it’s still important to set expectations, preface any distance between the client’s original vision to ease surprise, and outline that your recommendation is just that — a recommendation. Lastly, outline that the goal of this phase is to come to an agreement on what to build and that this phase of the entire engagement is the most important. Explain that this is an interactive process and may take a couple sessions to complete, but everything in the project is downstream from this phase. Then move to present your recommendation using visuals with clear rationale of any gaps or deviations from the original vision, and clear outlines of how the recommendation either solves the client’s problem, achieves their goals, or puts them on the right track. We don’t want to overlook any problems or goals with our recommendation either. If there are personal goals at play — so long as they are not extremely personal — note and show how the recommendation addresses them as well.
Clients likely will push back and sometimes provide sound rationale as to why. This should be taken into consideration if it genuinely provides helpful insight. Most of the time, this is when a client has internal company or industry knowledge that you have not been exposed to yet. Again, this phase is interactive, so if needed you can always take this additional information into consideration and update your recommendation. It’s important to maintain the relationship here though. When accepting pushback, be clear and concise as to where aspects of the recommendation the additional context will affect, and note that you will take this into consideration in a future draft. Do not say that you did anything wrong, because you didn’t — new information was exposed to you that you did not have before. If you admit fault, the entire recommendation will be rendered worthless. The relationship will blow up and be reduced to an employee-employer one, and trust will be shattered. If pushback is not valuable — for example, “No, that doesn’t work with my timelines” — you can acknowledge the disconnect, but then stand on your recommendation and explain the implications of what would happen if the pushback was accepted. Again, make sure to keep the relationship in mind. This is not supposed to be a negotiation; this is supposed to be a peer-level discussion about finding solutions. Conduct the discussions in that manner. Specifically, imagine that you had your recommendations and visuals on a table in front of you and the client was sitting next to you as you discuss finding a solution that works. Do not engage in a situation where you would be sitting across from the client and essentially demanding conformity. You’re working on a puzzle together. “No, that piece can’t fit there because it’s a corner piece. Oh wow, you found some more pieces — let’s see where these can fit.” Don’t leave the table until the puzzle is complete.
Recommendation Presentation Checklist
Before the Meeting:
During the Meeting:
After Agreement:
┌──────────────────┐ ┌──────────────────┐ │ │ │ │ │ YOU │ Not a negotiation. │ CLIENT │ │ │ A collaborative puzzle. │ │ │ │ │ │ └────────┬─────────┘ └────────┬─────────┘ │ │ │ ┌──────────────────────┐ │ └───────────►│ │◄────────────┘ │ THE PUZZLE │ │ (what to build) │ │ │ └──────────────────────┘ "That piece can't fit there — it's a corner piece. Oh, you found more pieces! Let's see where they fit."
Once what to build is determined, we’re 95% of the way there. We just need to outline success criteria. You should have a decent grasp on what success criteria looks like, but it’s a similar interactive process. As a reminder, it’s important to set out objective success criteria that you can verify — approval is not success criteria. Most of the time the criteria is aligned with a secure, working solution. Assuming what to build and what success looks like is decided, the project is set up for success and we’re ready to steam ahead. However, let’s talk about some edge cases in this process.
Sometimes feasibility isn’t completely deterministic. We’ve seen this arise in situations where complex, non-public, third-party integrations are needed. You can assume that a needed third party will work, but there’s no way of knowing until you actually get into implementation. It’s also hard to estimate timeline implications for these situations. In these cases it’s best to be honest about the gap in your recommendation and outline what would happen in a worst-case scenario as well as alternatives — and estimate fair time and cost implications of this unknown gap. Do not accept directives from the client to “find out.” First, the time taken to do so would greatly slow down progress of the project. Second, the client is not in a position to order you around. And lastly, when it comes to integrations, public documentation will say it works, sales and heads of integrations/partnerships will say it works, but you never really know until you build the integration.
Another outlier in this process is when clients demand concrete rationale for cost and timelines. Like with many large-scale projects — not just in software — it’s near impossible to give explicit cost and timeline scopes. You can estimate to a degree of certainty, but the software development lifecycle is so complex that you, to a certain extent, have to take it weeks at a time, maybe months. When explaining this to clients, you can outline that yes, your cost and timeline estimates are just that — estimates — but you have prepared them in a conservative manner. You can pull examples of other software projects and where you’re deriving your estimates from, but most of the time an estimation methodology drives the point home. You should have some quantifiable estimation methodology to present for these estimations. Whether that is a points system, hour estimations, sprint cycles, or something else, coming with a system gives you grounding when explaining your estimates.
Lastly, an outlier that we have come across is a misalignment with the sales process or expectation setting. Clients will come in and essentially say, “Well no, I was promised I was going to get this, for this cost, and for this time.” In these situations, it’s helpful to have service agreements on standby, sales assets that were shown to the client, and transcripts from the kickoff phase to reinforce the purpose of this phase, what was agreed upon, and determine where the miscommunication happened.
Regardless, assuming the puzzle is completed and success is defined, the car is lined up and we can step on the gas. However, it is incredibly important to not move forward past this phase until it is complete — this is the most important step in the entire engagement. The what needs to be agreed upon and success needs to be defined.
Phase 2: Definition
This phase, in my opinion, is fundamentally about weaponizing AI. If we assume that implementation time is rapidly hurtling toward instant, we should spend time defining and preparing assets that encompass what needs to be built in the most effective way for AI to consume. However, the client still needs to be taken into account here, and human comprehension as well. We can’t just plan for AI — we must also prepare assets that are consumable for humans for project context. Previously, human consumption was the only thing that needed to be taken into account at this phase, but we have discovered that there is a fundamental difference between the two. Most clearly explained with the understanding that AI can consume 40 pages of documentation at once — context can essentially be transferred instantaneously. This is not the case with people. Additionally, especially in governance and larger organizations, reporting and project visibility for other people is still needed. Lastly, many industries are operating off traditional planning frameworks, so adhering to them is still essential to a certain extent. Preparing project definition assets for both parties is key here.
Phase 2 Definition Assets: Overview
┌──────────────────────────────────────────────────────────────────────────────┐ │ DEFINITION ASSETS │ │ │ ├──────────────────────┬────────────────────┬─────────────────────────────────┤ │ Asset │ Primary Audience │ Purpose │ ├──────────────────────┼────────────────────┼─────────────────────────────────┤ │ │ │ │ │ User Flows │ Client + AI │ Visual app structure & nav │ │ │ │ │ ├──────────────────────┼────────────────────┼─────────────────────────────────┤ │ │ │ │ │ MVP Feature List │ Client │ Scope lock & agreement doc │ │ │ │ │ ├──────────────────────┼────────────────────┼─────────────────────────────────┤ │ │ │ │ │ Tech Requirements │ Client + AI │ Technical specs & constraints │ │ │ │ │ ├──────────────────────┼────────────────────┼─────────────────────────────────┤ │ │ │ │ │ External Systems │ AI │ Third-party integration map │ │ │ │ │ ├──────────────────────┼────────────────────┼─────────────────────────────────┤ │ │ │ │ │ Database Schema │ AI │ Data structure foundation │ │ │ │ │ ├──────────────────────┼────────────────────┼─────────────────────────────────┤ │ │ │ │ │ Brand Kit │ Client + AI │ Design principles & aesthetics │ │ │ │ │ ├──────────────────────┼────────────────────┼─────────────────────────────────┤ │ │ │ │ │ SPEC TREE │ AI (primary) │ Hierarchical source of truth │ │ ★ Most Important │ │ for AI implementation │ │ │ │ │ └──────────────────────┴────────────────────┴─────────────────────────────────┘
However, transparently, as a new methodology for definition assets that works specifically for AI-driven development is adopted, I see the compression of this phase over time, as a quick transition into implementation is likely best — especially if success criteria is defined. In short, the system will be built first based on a rough understanding of what should be built and success criteria, and then defined and revised afterwards. For example: “Build Uber and then define the security, data processes, features, etc. of the system that you built… Okay, that system doesn’t adhere to the data processing that we need — change it to match XYZ.”
At Benmore, most of the below assets are derivative of the transcriptions and assets from the extraction phase and are rapidly created. With that in mind, let’s get into the assets that we find most valuable, who they are for, and what their function is.
User Flows
Consumable by both people and AI, these flows are incredibly important for visually outlining the expected screens of the application and the ways in which users are meant to interact with the application as a whole. It’s important to get client feedback on these flows, as project flow is somewhat subjective. Where we see these flows being valuable to the project as a whole differs for both AI and the client.
The client gets to visually see the structure of their application and provide feedback before implementation. They can see screen connection points, the types of users in their application and their journey, and the workflows within the application as well. For AI, this document is also extremely valuable as an initial anchor point and roadmap of sorts. Giving AI features to implement without the high-level connections of the system is akin to, again, driving in a winter storm. This is essentially the AI’s roadmap when it comes to implementation and how the application works together from a high-level view. Additionally, utilizing this as the first development outcome for AI sets up a bounded canvas of sorts for future development. Specifically, a core issue with AI development is that it tends to over-scope and add in extra screens and features. By giving AI the first directive of just setting up the macro project structure, you can create bounds for AI to operate in. This would be carried out as follows at a high level:
Okay AI development engine of choice, attached are the user flows for an application. Please set up the codebase and the screens for the application that match this user flow. Don’t worry about design or complex functionality — simply ensure that navigation between these screens is functional and all user flows are represented. At each screen, textually include the purpose of the screen and its connection points to other screens, as well as what users can access the workflow.
Setting up this base layer grounds and bounds future development within a project structure.
MVP Feature List
Mainly meant as a scope lock document for clients, this document clearly outlines the needed features for the build. Within this document, each feature is documented, prioritized, and associated user stories are logged as well. Additionally, in this document is the previously defined success criteria and how they relate to each feature. What is not included in the project should also be documented here — and is very important for scope management during implementation. Assumptions, especially in the case of unknown feasibility, are documented here as well, along with a high-level outline of timelines and milestones. Lastly, project constraints are also documented here. As you can see, this feature list is more of a documentation of the agreement on what to build, formalized for reference later.
However, the core purpose of this document is actually to lay the foundation for the Spec Tree, which heavily impacts AI implementation.
Technical Requirements
This document is, to us, more focused on pure technical requirements and constraints of the project. Equally important for AI and clients, here is where we do a deeper dive into the technical specifics. Typically this document includes the following components: functional requirements, or the specific behaviors, features, and capabilities the system must have — these describe what the system does, such as “the system shall allow users to reset their password via email.” Non-functional requirements: constraints on how the system performs, including performance benchmarks (response times, throughput), scalability expectations, availability/uptime targets, security requirements, and accessibility standards. System architecture and design constraints: technology stack preferences, integration points with other systems, APIs, database requirements, and any mandated platforms or frameworks. Data requirements: what data the system handles, storage needs, data formats, migration plans, retention policies, and backup/recovery expectations. User roles and permissions: who uses the system and what level of access each role has. Assumptions and dependencies: things assumed to be true (e.g., users will have modern browsers) and external systems or teams the project depends on. Acceptance criteria: how you’ll know the requirements have been met, often expressed as testable conditions. Glossary and definitions: clarification of domain-specific terms to keep everyone aligned.
Clients can understand the technical expectations of the project, developers can consume the project context, and AI can use this as a map for requirement consistency and adherence.
External System Integrations
This document is actually mainly for AI. It’s helpful for clients to see, but one area where agentic coding runs into issues is when integrating with external or sparsely documented systems. In this document we outline each external provider, what the purpose of the integration is, and where it impacts the application as a whole. Additionally, we outline any documentation that we have on the third-party systems or assumptions that we are making. This proves to be very effective in saving context and preventing rogue runs during AI-driven implementation. Essentially, this is our opportunity to hydrate project context with some of the things that AI would have a hard time finding itself or was not trained on.
Database Schema
This is mainly for AI. Post-launch, structural database changes can be a real headache, and defining the structure of the database before coding is just helpful to preserve project context. Also, proper database architecture is key when it comes to the scalability of systems — so nailing it down from the beginning is important. Databases are just harder to enact changes on, so starting from solid foundations is key.
Brand Kit
For AI and clients, this asset defines design principles and styles to follow in development. Client feedback is heavily encouraged at this step, as it is very subjective. There are some standard principles to follow, but standardizing brand, look, feel, and aesthetic of the project is the purpose here.
Tree Spec
By and large the most important asset in project definition, rarely exposed to clients, it acts as the source of truth for AI. If user flows are the roadmap and the MVP feature list is the agreement on what to build, the Tree Spec is the actual construction blueprint — it tells AI exactly how to build it, in what order, and within what constraints.
The methodology for laying out a proper Tree Spec is rapidly changing, but the core concept is consistent: it is a hierarchical specification document that AI agents follow when developing the project. Think of it as a tree that branches from broad to specific, where each level adds detail and each branch inherits the rules of its parent.
At the top of the tree is a high-level overview of the project: project vision, tech stack, architecture decisions, security requirements, user flows, brand kit — essentially a distilled summary of every document we’ve created up to this point. This top level acts as a constitution of sorts. Everything below it must comply with what’s defined here. If the constitution says “we use Supabase for auth and Postgres for data,” then no feature spec further down the tree should be spinning up a custom auth system or reaching for MongoDB. This is where non-negotiable decisions live.
The next level down breaks the project into its core feature groups. These map closely to what’s defined in the MVP Feature List, but here they are structured specifically for AI consumption. Each feature group contains its own specification — what the feature does, what screens it touches, what data it reads and writes, what external systems it integrates with, and what the acceptance criteria looks like. This is where the user stories from the MVP Feature List get translated into something more technically precise. Where the MVP doc might say “users can manage their subscription,” the Tree Spec says “the subscription management feature allows authenticated users to view their current plan, upgrade or downgrade via Stripe’s billing portal, and receive confirmation via email through SendGrid.”
Below the feature specs sit the implementation plans. This is where we get into the how. Data models, API endpoint structures, component hierarchies, state management patterns, and dependency mappings all live here. These plans are informed by the Technical Requirements and Database Schema documents, pulling in the constraints and architectural decisions that were already agreed upon. The implementation plan for a given feature should be detailed enough that an AI agent could pick it up and begin building without needing to ask clarifying questions — that’s the bar.
At the bottom of the tree are the individual tasks. These are atomic, testable units of work. Instead of “build the payment system,” a task reads more like “create the webhook handler for Stripe’s invoice.payment_succeeded event that updates the user’s subscription status in the database.” Each task is small enough to implement and verify in isolation, which is critical for AI development. Smaller, well-defined tasks produce significantly better AI output than broad, ambiguous ones. This is where the real implementation happens, one task at a time.
The Spec Tree: Hierarchical Architecture
┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ PROJECT CONSTITUTION │ │ │ │ Vision · Tech Stack · Architecture · Security · User Flows │ │ Brand Kit · Non-negotiable decisions │ │ │ │ "If the constitution says Supabase for auth, nothing │ │ below spins up a custom auth system." │ │ │ └──────────────────────────────────┬──────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ │ │ FEATURE GROUP A │ │ FEATURE GROUP B │ │ FEATURE GROUP C │ │ │ │ │ │ │ │ What it does │ │ What it does │ │ What it does │ │ Screens touched │ │ Screens touched │ │ Screens touched │ │ Data read/write │ │ Data read/write │ │ Data read/write │ │ Integrations │ │ Integrations │ │ Integrations │ │ Acceptance criteria │ │ Acceptance criteria │ │ Acceptance criteria │ │ │ │ │ │ │ └──────────┬───────────┘ └──────────┬───────────┘ └──────────┬───────────┘ │ │ │ ┌────┴─────┐ ┌─────┴────┐ ┌───────┴────┐ ▼ ▼ ▼ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ │ │ │ │ │ │ │ │ IMPL PLAN │ │ IMPL PLAN │ │ IMPL PLAN │ │ IMPL PLAN │ │ IMPL PLAN │ │ │ │ │ │ │ │ │ │ │ │ Models │ │ APIs │ │ Components│ │ State │ │ Data │ │ │ │ │ │ │ │ │ │ │ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ │ │ │ │ │ │ │ │ TASK │ │ TASK │ │ TASK │ │ TASK │ │ TASK │ │ │ │ │ │ │ │ │ │ │ │ Atomic, │ │ Atomic, │ │ Atomic, │ │ Atomic, │ │ Atomic, │ │ testable │ │ testable │ │ testable │ │ testable │ │ testable │ │ units │ │ units │ │ units │ │ units │ │ units │ │ │ │ │ │ │ │ │ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘ INHERITANCE: Each task knows WHY it exists, WHAT feature it serves, and WHAT project rules it must respect.
What makes the Tree Spec particularly powerful is the inheritance model. Every task inherits context from the implementation plan above it, which inherits from the feature spec above that, which inherits from the project constitution at the top. An AI agent working on a specific task doesn’t just know about that task — it knows why that task exists, what feature it serves, and what project-wide rules it needs to respect. This layered context is what separates structured AI development from vibe coding.
There is also a feedback component to the Tree Spec that is easy to overlook. As implementation surfaces issues — unexpected edge cases, model-specific quirks, integration complications — those learnings should flow back up the tree. If the AI consistently struggles with a particular pattern or a third-party API behaves differently than documented, that gets captured and the relevant specs get updated. The Tree Spec is a living document, not a static one. It evolves as the project evolves, and keeping it current is what keeps AI aligned over the course of a build.
One thing worth noting: the Tree Spec is not a client-facing document. It is dense, technical, and frankly not very interesting to anyone who isn’t building the thing. Clients care about the what and the why — those conversations happen in the user flows and the MVP feature list. The Tree Spec is purely operational. It exists to make AI implementation predictable, consistent, and grounded in the decisions that were already made during the planning phase.
The specifics of how to structure and maintain a Tree Spec are still being figured out across the industry. Tooling is emerging, formats are being debated, and best practices are shifting rapidly. But the underlying principle is stable: give AI a structured, hierarchical source of truth and it will build better software. The Tree Spec is how we do that.
As mentioned, I believe that in the future, the Tree Spec will be the only definition needed for implementation. Any other assets needed can be created reactively to the developed project, as well as any revisions. Regardless, we’ve discussed what happens when discovery goes according to plan. Let’s talk about what to do when it doesn’t.