sdd-authoring

name	sdd-authoring
description	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.
version	1.0.0
author	Hermes Agent community
license	MIT
metadata	{"hermes":{"tags":["sdd","specifications","gherkin","requirements","bdd","acceptance-criteria"],"related_skills":["sdd-work-decomposition","sdd-verification","sdd-review"]}}

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:

1. Problem statement — what problem this solves and why it matters
2. Scope boundary — explicit in-scope and out-of-scope
3. User stories — prioritized, with links to acceptance criteria
4. Acceptance criteria — per-story, framed as Given/When/Then or bulleted pass/fail conditions
5. Edge cases — explicit enumeration of boundary conditions, error states, invalid inputs
6. Non-functional requirements — performance, security, observability, compliance, accessibility
7. 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.