--- name: spec-driven-development description: Writes a specification with measurable acceptance criteria before code exists. Triggers - write a spec for this feature, we need a PRD before we start, what exactly are we building, define the scope, requirements doc. --- # Spec-Driven Development A spec is the shared, checkable statement of what will exist. Without one, "done" is decided after the fact by whoever is most tired. With one, the argument happens while it is still cheap — on paper. A spec is not a design document. It says *what* and *how we will know*; design decisions belong in `architecture-decisions`, sequencing in `planning-and-task-breakdown`. ## When to use - New feature, new subsystem, new integration - Any change to observable behavior of something people depend on - Experiments too — a spike gets a five-line spec with a deadline and a question it must answer **When not to use:** typo fixes, dependency bumps, refactors that preserve behavior exactly (those need tests, not a spec). ## Shape Store as `docs/specs/NNN-short-name.md`. ```markdown # Status: draft | approved | implemented | superseded by NNN Owner: · Date: · Related: ADR-NNN, spec-NNN ## 1. Problem Who cannot do what today, and the cost of that. ## 2. Outcome The capability that exists afterwards, in one sentence. ## 3. Users and scenarios For each actor, the concrete walkthrough. Include the unhappy paths. ## 4. Acceptance criteria Numbered, independently verifiable, each one testable as written. ## 5. Out of scope Deliberate exclusions, so scope creep has to argue with a document. ## 6. Interface impact Public API, schema, events, config, CLI — what changes for callers, and whether the change is backward compatible. ## 7. Data impact New/changed data, migration need, retention, personal data, reversibility. ## 8. Quality impact Which CONSTRAINTS.md dimensions this touches; new budgets it must meet. ## 9. Failure and degradation What happens when a dependency is down, slow, or returns garbage. What the user sees. What we log. ## 10. Risks and unknowns Risk → mitigation. Unknown → how we will resolve it (spike, sample, prototype). ## 11. Alternatives considered Options rejected and why. Absence of this section means the first idea won. ``` ## Writing acceptance criteria The single highest-leverage part. A criterion is well-formed when a test can be written from it without asking a question. | Weak | Strong | |---|---| | "Search should be fast" | "p95 search response ≤ 300 ms at 50 concurrent users with 1M rows" | | "Handles errors gracefully" | "On upstream 5xx, returns 503 with retry-after, logs one warning with correlation id, no partial write persists" | | "Users can export data" | "Export produces a CSV with columns A–F; rows match the filtered view exactly; 100k rows complete within 60 s; interrupted export leaves no file" | | "Should be secure" | "Only users with role X can call it; rejects requests without a valid token with 401; never logs the token" | Rules: one behavior per criterion; include the boundary ("at 1M rows", "when the token is expired"); name the observable result, not the implementation. ## Discipline 1. **Section 5 is mandatory.** An empty out-of-scope list means the boundary hasn't been thought about. 2. **Sections 7 and 9 cannot be skipped.** "No data impact" and "no degraded mode needed" are valid answers; blank is not. 3. **Two pages is the ceiling.** Longer means the work should be decomposed into several specs with their own criteria. 4. **Unresolved question → explicit assumption.** Write "Assumption:" with the consequence if wrong, and proceed. Never leave a blank to be filled by whoever implements it. 5. **Approval before code.** The spec is the thing being approved, not the implementation that follows. 6. **Superseding, not editing.** A shipped spec is a historical record. Changes after implementation go in a new spec that supersedes it. ## Exit checklist - [ ] Every acceptance criterion could be turned into a test as written - [ ] Out-of-scope list is non-empty - [ ] Interface and data impact stated, including "none" where true - [ ] Failure behavior described for each external dependency - [ ] At least one rejected alternative recorded with a reason - [ ] Assumptions listed with consequences - [ ] Reviewed and marked approved before implementation starts