HaruhikoMotokawa SDD Conventions
Spec File Location
All specification documents live in docs/specs/. Naming convention: {feature-slug}.md (kebab-case).
Status prefix in the filename or frontmatter:
---
status: draft | review-requested | approved | in-implementation | implemented
---
Required Sections
Every spec must include all of the following:
- Overview — 1-2 sentences, no jargon, answers "what and why"
- Goals — bullet list of measurable outcomes
- Non-Goals — explicit scope boundaries (not just "everything else")
- User Stories — "As a [role], I want [action] so that [benefit]"
- Acceptance Criteria — testable, Given/When/Then format
- Technical Design — data model changes, API/interface changes, affected components
- Open Questions — unresolved items that could block implementation
- Implementation Checklist — actionable tasks by area (backend, frontend, tests, docs)
Acceptance Criteria Format
Use Given/When/Then exclusively:
- Given [initial state or precondition],
When [user action or system event],
Then [observable, verifiable outcome]
Invalid — "The system should handle errors gracefully" Valid — "Given a network timeout occurs during payment processing, When the user submits the payment form, Then an error message 'Payment failed. Please try again.' is shown and no charge is made"
Each criterion must be verifiable by an automated test or an explicit manual test step.
Spec Lifecycle
draft → review-requested → approved → in-implementation → implemented
- draft: being written, not ready for review
- review-requested: ready for technical and product review
- approved: all issues resolved, implementation may begin
- in-implementation: actively being built
- implemented: feature shipped, spec archived
Rules
- Implementation must NOT begin before a spec reaches
approved - All open questions must be resolved before moving to
approved - Acceptance criteria must be testable — if it cannot be verified, rewrite it
- Breaking an approved spec requires re-approval
Useful Commands
/sdd-spec <feature-name>— create a new spec/sdd-review [spec-file]— review a spec for approval readiness/sdd-init— set up SDD structure in a new project