The Three-Phase Spec Framework
Published May 22, 2026 · Last updated May 22, 2026 · 3 min read
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, often 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.