SDD Process Skill

This skill provides the methodology, interview framework, and document templates for Spec Driven Development (SDD).

When to Use This Skill

Use the SDD methodology when:

• Starting a new project - Establish clear requirements before coding
• Defining features - Document what needs to be built and why
• Aligning stakeholders - Create shared understanding of goals
• Preparing for AI-assisted development - Generate specs optimized for AI coding agents
• Documenting technical decisions - Capture architecture and design choices

SDD Document Types

Product Requirements Document (PRD)

• Focuses on what and why
• Defines problem, goals, requirements, and success metrics
• Written for stakeholders and developers
• Primary artifact for most projects

Technical Specification (Tech Spec)

• Focuses on how at a system level
• Defines architecture, data models, APIs, technology choices
• Written for developers and AI coding agents
• Generated when technical complexity warrants it

Design Specification (Design Spec)

• Focuses on how at a user experience level
• Defines user flows, components, interactions, accessibility
• Written for designers and frontend developers
• Generated when project has UI/UX components

Interview-Driven Approach

SDD uses a conversational interview to gather requirements. This approach:

1. Adapts to context - Questions vary based on project type and complexity
2. Builds understanding - Natural conversation reveals nuances
3. Validates assumptions - Clarifying questions catch misunderstandings
4. Respects time - Detail level is configurable

Interview Phases

1. Foundation - Project name, type, relationship to existing systems
2. Problem - What's being solved and for whom
3. Requirements - Functional and non-functional needs
4. Technical - Architecture and implementation considerations
5. Design - User experience and interface needs (if applicable)
6. Generation - Document creation based on collected information

Detail Levels

Level	Description	Best For
High-level	Overview and key decisions	Early exploration, quick alignment
Mid-level	Detailed requirements with guidance	Most projects
In-depth	Comprehensive, implementation-ready	Complex projects, AI agents

Document Output

Documents are generated in specs/<project-name>/ with:

• YAML frontmatter for metadata (project name, version, timestamps, related docs)
• Markdown content following consistent templates
• Cross-references between related documents

Output Structure

specs/
└── my-project/
    ├── prd.md
    ├── tech-spec.md      # if technical complexity warrants
    └── design-spec.md    # if UI/UX components exist

Interview Framework

See references/interview-framework.md for:

• Complete question categories
• Question sequencing guidelines
• Natural conversation principles
• Completion checklist

Document Templates

See reference files for detailed templates:

• references/prd-template.md - PRD structure and guidelines
• references/tech-spec-template.md - Tech Spec structure and guidelines
• references/design-spec-template.md - Design Spec structure and guidelines

Best Practices

For Effective Interviews

1. Start broad, get specific - Let context emerge naturally
2. Validate understanding - Summarize and confirm key points
3. Probe red flags - Vague goals, unclear scope, conflicting requirements
4. Respect scope - Note but defer tangential topics
5. Adapt to user - Some need more guidance, others less

For Quality Documents

1. Be specific - Vague requirements lead to vague implementations
2. Include acceptance criteria - Make requirements testable
3. Document decisions - Explain why, not just what
4. Consider AI agents - Write for machine readability
5. Link related items - Cross-reference between documents

For AI-Optimized Specs

Documents generated by SDD are optimized for AI coding agents:

• Clear structure - Consistent formatting aids parsing
• Explicit requirements - No ambiguity in what needs to be built
• Testable criteria - AI can verify implementation correctness
• Context provided - Background information explains decisions
• Modular breakdown - Requirements can be implemented independently

State Management

Interview state is saved to .claude/sdd-manager.state.json:

{
  "current_project": "project-name",
  "interview_phase": "requirements",
  "collected_data": {
    "project_name": "...",
    "project_type": "...",
    "problem_statement": "...",
    ...
  },
  "documents_to_generate": ["prd", "tech-spec"],
  "last_updated": "2024-01-15T10:30:00Z"
}

This enables:

• Session resume - Continue interrupted interviews
• Progress tracking - Know what's been covered
• Data preservation - Don't lose gathered information