specification-writing
Specification Writing
Follow writing-voice for prose sections. For ownership or flow explanations, lead with the useful model, ground it in the relevant boundary, and keep only the diagrams and prose implementation needs.
A specification gives an agent or maintainer the context they need to implement a feature autonomously. The goal is not to describe everything exhaustively. The goal is to show enough evidence that the direction is credible and give the implementer a concrete launch point.
A spec is in-flight scaffolding, not the durable record. It plans work and holds research while the work is underway. It is not authoritative and does not outlive the work. Durable decisions live in docs/adr/, shared vocabulary in docs/CONTEXT.md, current state in docs/reference/ and the code. When a load-bearing decision crystallizes while you are writing the spec, record it as a Proposed ADR in docs/adr/ right then and reference it from the spec; do not leave it buried in the spec to be "harvested" later. When the work lands, the ADR flips to Accepted and the spec is deleted (see spec-execution). Git and docs/spec-history.md keep the history.
Note: This guide uses
[PLACEHOLDER]markers for content you must fill in. Code blocks show templates; replace all bracketed content with your feature's details.
References
Load these on demand based on the spec's decision surface:
- If writing a spec with many trade-offs, migration cleanup, or "keep for consistency" decisions, read references/decision-hygiene.md.
- If writing a spec with architecture, API, lifecycle, or ownership changes, read ../pull-request/references/body-patterns.md for before/after examples and visual communication rhythm.