The Three-Phase Spec Framework
Published May 22, 2026 · Last updated September 24, 2026 · 3 min read
Autobuild agents write exactly what you describe. That makes the spec the product: a vague spec produces a vague feature. The three-phase framework splits spec writing into product, UX, and technical phases, each answering one question before the next begins.
The three phases
Every Autobuild spec moves through three sequential phases, each producing a distinct artifact that feeds the next.
Phase 1: Product Spec answers: what outcome are you creating for users? It is a decision document, not a feature list. It defines the user problem, the desired behavior change, testable success criteria, scope boundaries, and any decisions you've already locked. Without a product spec, the agent optimizes for code correctness instead of user outcomes.
Phase 2: UX Spec answers: what does this look and feel like for the user? It bridges product intent and technical implementation by making the experience concrete before any code is written. Without a UX spec, the agent invents an interface based on what's easiest to build, which is rarely what's best for the user.
Phase 3: Technical Spec answers: how exactly do you build this in the current codebase? It cites actual files, services, schemas, and interface contracts, not assumptions. Without a technical spec, the agent explores the codebase at build time and makes architecture decisions you never approved.
How the phases connect
The three phases form a pipeline where each output feeds the next.
-
The product spec's success criteria become the technical spec's verification criteria
-
The UX spec's state inventory becomes the technical spec's edge-case coverage
-
The product spec's scope boundaries become the technical spec's "what not to build" section
When you skip a phase, the downstream phases have to guess. The agent fills the gap, sometimes well and sometimes not, and the mismatches show up in code review.
When to skip phases
Not every change needs all three phases. The investment scales with the risk and complexity of the work.
| Change type | Phases needed |
|---|---|
| New feature (UI-facing) | All 3: Product → UX → Technical |
| New feature (API or backend only) | Product + Technical (skip UX) |
| Bug fix (complex, needs root cause analysis) | Light Technical Spec (bug description, root cause, proposed fix) |
| Bug fix (simple, cause is known) | Just describe it (no formal spec needed) |
| Refactor | Technical Spec only (current state → target architecture) |
| Config or UI polish (visual change) | UX + Light Technical (show the target state, reference components) |
| Config or UI polish (non-visual) | Just describe it (no formal spec needed) |
The rule of thumb: if you'd be surprised by the agent's implementation choices, you need more spec. If the implementation is obvious from the request, write less.