Context
Why this exists now. The constraint, the regulation, the benchmark evidence, the DEC that demanded it. What breaks or stays impossible if we skip it. No solution language here.Scope (normative)
What this delivery includes, as a list a reviewer can check off. Be specific enough that “done” is not a judgement call.Non-scope (normative)
What this deliberately does not include, and where it goes instead (another FS, a phase, an open question). This section prevents more rework than any other — write it properly.Behaviour (normative)
The rules, in the order they apply. State the invariants that must always hold and the failure modes explicitly. Say what is FORBIDDEN, not only what is allowed.Data (normative)
Tables touched or created, their key invariants, parametric catalogs and theiris_system seeds,
partitioning, retention. Reference standards/data.md rather than restating it — record only
what is specific to this feature.
API (normative)
Each endpoint with its single permission{module}.{resource}.{action}, its API class
(Runtime or Management), its p95 budget, and whether Idempotency-Key is required.
Empty section if the feature exposes no endpoint — say so rather than deleting the heading.
Events (normative)
Domain events emitted and consumed, in{context}.{entity}.{verb_past} form. Note which are
available as outgoing webhooks and whether the payload carries PII.
Acceptance criteria (normative)
Numbered, each one mechanically verifiable. Include the latency budgets as numbers. Include at least one negative test — the thing that must not happen.Execution
Fill this in when the feature ships in a single slice, and skip the TS entirely. Which archetype is followed, which files change, what order. If the feature needs more than one slice, delete this section and open a task spec instead — name it here.Open questions
Things genuinely undecided, each with who decides and by when. A spec can reachreview with
open questions; it cannot reach approved with any that affect a normative section.