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: one falsifiable list, with anything only you can settle under a ### human sub-heading. | The implementer, and you. (Unattended — experimental — this one list refines into three altitudes; next chapters.) |
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. Frontmatter itself is just four keys — identity, not governance (slug, type, decider, created); the routing envelope — blast_radius, size, loop_budget — is experimental, legal on any spec but only meaningful once it declaresbuild: unattended.
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.