Anatomy of a spec
A spec is a folder, and its sections aren't a template to fill — each one exists because a specific actor needs it. This is the center of the whole methodology, so it's worth walking section by section and naming who each part is for.
| Section | What it holds | Who it's for |
|---|---|---|
| Intent | What the feature is and why — the product outcome in plain language. | The PO, and anyone later asking "why does this exist?" |
| Goal | The one checkable outcome that means done. | The implementer — its target — and the reviewer, who judges against it. |
| Non-goals | What this deliberately won't do. | The implementer — the fence that stops it gold-plating the unasked. |
| Behavior | Numbered, observable statements of what it does. | The implementer (what to build) and the reviewer (what to check against). |
| Business rules | Must / should / may constraints. | The implementer and reviewer — the hard limits. |
| Assumptions | What it takes as given about systems it doesn't control — and what to do at a contradiction. | The implementer — where to escalate fast instead of hacking around a seam. |
| Acceptance checks | How done is certified, at three altitudes (next chapters). | All three: the implementer (provable), the reviewer (judgeable), you (tasteable). |
Two more files travel in the folder. relations.md tells the implementer
what this feature depends on and what's coming — so it builds with the rest of the system
in view. implementation.md (optional) is the build-scratch: the detailed,
line-level how (and any suggested UI approach) — kept for the builder, but never
graduated, because mechanics rot. And the frontmatter carries routing and governance — blast_radius,
size, loop_budget — which set how hard the build runs and when
it calls you back.
The discipline is one line: the spec carries the feature's delta, nothing
universal. Detailed mechanics go to implementation.md; baseline hygiene
("tests pass, lint clean") belongs to the codebase's standards, not the spec; and
acceptance proves the goal, never restates the floor. That's what keeps a spec
specific without becoming a manual.
Reference: spec body sections, frontmatter fields, the spec folder.