speclisted

# Writing a Spec A spec captures **what** a feature does and **why**, before deciding **how**. ## Bar The bar a spec must clear: **a fresh agent given only this spec (no source code) should be able to either reimplement the feature OR test the system for conformance.** That means every requirement must be unambiguous. Where the feature has persistent state, the data model is documented. Where it exposes a contract (HTTP/WS/Go interface), the contract is documented. Where it has a multi-step lifecycle, the state machine is documented. If reading the spec leaves an implementer guessing, the spec is incomplete. ## Gate: is this actually a feature? Before doing anything else, check that the topic is feature-shaped. A spec is appropriate ONLY when **all** of these are true: - It describes a **product-feature surface** — a capability a user (human or office agent) can invoke. - The "What" section can be written as observable behaviors the feature must support, not as a problem statement or a fix. - The artifact will be a **living document** that evolves with the feature, not a one-shot record of a decision or incident. If any of these are false, STOP and route to the right artifact: | Situation | Use this instead | |---|---| | Bug fix, incident postmortem | `/fix` — plus an ADR via `/record decision` if the fix encoded a new convention. No spec. | | Architecture or convention decision | `/record decision` — produces an ADR under `docs/decisions/`. No spec. | | Refactor tha