SDD Specification Authoring
Writing formal, machine-readable specifications that drive AI-assisted implementation. This skill owns the Specify phase of the SDD pipeline and its output is the prerequisite for all downstream SDD work.
SDD Pipeline Position
INCEPTION → [SPECIFY] → PLAN → TASKS → IMPLEMENT → VERIFY
↑
You are here
The specification is the single source of truth. Every downstream artifact — task plan, architecture, implementation, tests — derives from and traces back to this document. Ambiguity in the spec propagates as defects in every subsequent phase.
Artifact-Pyramid Output: SPEC.md
The specification documents produced by this skill follow the artifact-pyramid structure:
| Layer |
Content |
File |
| L1 |
Executive Summary — one-paragraph scope statement, key stakeholders, overall success criteria |
00-index.md (entry point) |
| L2 |
Per-dimension specification — user stories, Gherkin scenarios, edge cases, NFRs, out-of-scope, data contracts |
Individual *.spec.md files |
| L3 |
Detailed per-story dossiers — full acceptance criteria, interface definitions, data schemas, examples |
dossiers/ directory |
| SOURCES |
Navigation index linking each L2 dimension to its L3 sources |
Footer of each file |
Loading Guidance
| Reference |
When to load |
File |
| Spec Quality Gates |
Before delivering any SPEC.md — validates completeness against 7 quality dimensions |
references/spec-quality-gates.md |
| Gherkin Patterns |
Writing executable scenarios — Given/When/Then structure for specific patterns |
references/gherkin-patterns.md |
| Acceptance Criteria Design |
Crafting ACs that pass the "no-surprises" test — edge case enumeration, boundary conditions |
references/acceptance-criteria-design.md |
| Template |
When to use |
File |
| SPEC.md |
Producing a specification document from scratch |
templates/SPEC.md |
| Script |
When to run |
File |
spec-quality-check.sh |
After authoring a SPEC.md — validates all required sections exist |
scripts/spec-quality-check.sh |
Trigger Conditions
Invoke this skill when:
- A new feature, component, or system needs a formal specification before implementation begins
- An existing specification needs refinement or gap analysis
- A vague requirement (ticket, conversation, email) needs to be translated into a structured SDD-ready spec
- The input is a research report, competitive analysis, or user interview transcript that needs distillation into engineering requirements
Output Contract
Every SPEC.md MUST include:
- Problem statement — what problem this solves and why it matters
- Scope boundary — explicit in-scope and out-of-scope
- User stories — prioritized, with links to acceptance criteria
- Acceptance criteria — per-story, framed as Given/When/Then or bulleted pass/fail conditions
- Edge cases — explicit enumeration of boundary conditions, error states, invalid inputs
- Non-functional requirements — performance, security, observability, compliance, accessibility
- Data contracts / interfaces — schemas, APIs, events (can be stubs that get refined in later phases)
The spec is NOT complete until a automated quality check passes (run spec-quality-check.sh).
SDD Philosophy
Specifications in SDD serve a different purpose than traditional requirements documents. They are not communication artifacts for humans that happen to be read by an AI. They are executable inputs to a code generation pipeline that happen to be readable by humans.
This distinction drives everything about how specs are written:
- Precision over clarity. A spec that is technically precise but dense is better than a spec that reads well but leaves ambiguity. The AI cannot ask for clarification when it encounters a vague phrase — it implements one interpretation at random.
- Completeness over brevity. Every missing acceptance criterion is a missing feature, not a question the implementer will ask. The cost of specifying an edge case up front is minutes. The cost of discovering it in production is hours or days.
- Testability over descriptiveness. An acceptance criterion that cannot be verified (passed or failed) by a deterministic check is not an acceptance criterion — it is a hope. Every AC must produce a binary verdict.
Framework Awareness
This skill is methodology-agnostic at the framework level but follows SDD principles common to all major frameworks:
- GitHub Spec Kit — Four-phase Specify→Plan→Tasks→Implement. The spec produced here fulfills Phase 1 (Specify).
- GSD — Uses PROJECT.md and REQUIREMENTS.md as spec layer. SPEC.md maps to these artifacts.
- BMAD — Role-based specification chain (BA → PRD → Architecture). SPEC.md here aligns with the PRD and Architecture layers.
- Taskmaster AI — PRD-driven. SPEC.md is the structured PRD that Taskmaster parses into task graphs.
- Native Claude Code — CLAUDE.md + spec files. SPEC.md is consumed alongside CLAUDE.md by the implementation agent.
1---2name: sdd-authoring3description: Specification authoring for AI-native SDD — writes formal specifications in structured formats (Gherkin, user stories, acceptance criteria), enforces spec quality gates, and produces artifact-pyramid-compliant SPEC.md outputs. Trigger when specifications or requirements documents need to be authored from scratch or refined.4license: MIT5---67# SDD Specification Authoring89Writing formal, machine-readable specifications that drive AI-assisted implementation. This skill owns the **Specify** phase of the SDD pipeline and its output is the prerequisite for all downstream SDD work.1011## SDD Pipeline Position1213```14INCEPTION → [SPECIFY] → PLAN → TASKS → IMPLEMENT → VERIFY15 ↑16 You are here17```1819The specification is the single source of truth. Every downstream artifact — task plan, architecture, implementation, tests — derives from and traces back to this document. Ambiguity in the spec propagates as defects in every subsequent phase.2021## Artifact-Pyramid Output: SPEC.md2223The specification documents produced by this skill follow the artifact-pyramid structure:2425| Layer | Content | File |26|-------|---------|------|27| L1 | Executive Summary — one-paragraph scope statement, key stakeholders, overall success criteria | `00-index.md` (entry point) |28| L2 | Per-dimension specification — user stories, Gherkin scenarios, edge cases, NFRs, out-of-scope, data contracts | Individual `*.spec.md` files |29| L3 | Detailed per-story dossiers — full acceptance criteria, interface definitions, data schemas, examples | `dossiers/` directory |30| SOURCES | Navigation index linking each L2 dimension to its L3 sources | Footer of each file |3132## Loading Guidance3334| Reference | When to load | File |35|-----------|-------------|------|36| Spec Quality Gates | Before delivering any SPEC.md — validates completeness against 7 quality dimensions | `references/spec-quality-gates.md` |37| Gherkin Patterns | Writing executable scenarios — Given/When/Then structure for specific patterns | `references/gherkin-patterns.md` |38| Acceptance Criteria Design | Crafting ACs that pass the "no-surprises" test — edge case enumeration, boundary conditions | `references/acceptance-criteria-design.md` |3940| Template | When to use | File |41|----------|-------------|------|42| SPEC.md | Producing a specification document from scratch | `templates/SPEC.md` |4344| Script | When to run | File |45|--------|-------------|------|46| `spec-quality-check.sh` | After authoring a SPEC.md — validates all required sections exist | `scripts/spec-quality-check.sh` |4748## Trigger Conditions4950Invoke this skill when:51- A new feature, component, or system needs a formal specification before implementation begins52- An existing specification needs refinement or gap analysis53- A vague requirement (ticket, conversation, email) needs to be translated into a structured SDD-ready spec54- The input is a research report, competitive analysis, or user interview transcript that needs distillation into engineering requirements5556## Output Contract5758Every SPEC.md MUST include:59601. **Problem statement** — what problem this solves and why it matters612. **Scope boundary** — explicit in-scope and out-of-scope623. **User stories** — prioritized, with links to acceptance criteria634. **Acceptance criteria** — per-story, framed as Given/When/Then or bulleted pass/fail conditions645. **Edge cases** — explicit enumeration of boundary conditions, error states, invalid inputs656. **Non-functional requirements** — performance, security, observability, compliance, accessibility667. **Data contracts / interfaces** — schemas, APIs, events (can be stubs that get refined in later phases)6768The spec is NOT complete until a automated quality check passes (run `spec-quality-check.sh`).6970## SDD Philosophy7172Specifications in SDD serve a different purpose than traditional requirements documents. They are not communication artifacts for humans that happen to be read by an AI. They are **executable inputs to a code generation pipeline** that happen to be readable by humans.7374This distinction drives everything about how specs are written:7576- **Precision over clarity.** A spec that is technically precise but dense is better than a spec that reads well but leaves ambiguity. The AI cannot ask for clarification when it encounters a vague phrase — it implements one interpretation at random.77- **Completeness over brevity.** Every missing acceptance criterion is a missing feature, not a question the implementer will ask. The cost of specifying an edge case up front is minutes. The cost of discovering it in production is hours or days.78- **Testability over descriptiveness.** An acceptance criterion that cannot be verified (passed or failed) by a deterministic check is not an acceptance criterion — it is a hope. Every AC must produce a binary verdict.7980## Framework Awareness8182This skill is methodology-agnostic at the framework level but follows SDD principles common to all major frameworks:8384- **GitHub Spec Kit** — Four-phase Specify→Plan→Tasks→Implement. The spec produced here fulfills Phase 1 (Specify).85- **GSD** — Uses PROJECT.md and REQUIREMENTS.md as spec layer. SPEC.md maps to these artifacts.86- **BMAD** — Role-based specification chain (BA → PRD → Architecture). SPEC.md here aligns with the PRD and Architecture layers.87- **Taskmaster AI** — PRD-driven. SPEC.md is the structured PRD that Taskmaster parses into task graphs.88- **Native Claude Code** — CLAUDE.md + spec files. SPEC.md is consumed alongside CLAUDE.md by the implementation agent.
magnus919