SDD Specification Skill

When to Use

Activate this skill when:

• User invokes /specify command
• User requests creation of a feature specification
• User asks to "document requirements" or "write a spec"
• Starting a new feature from scratch
• Need to formalize requirements for a feature

Trigger Keywords: specification, spec, requirements, feature description, document requirements, /specify

Procedure

Step 1: Branch Management

Ask user about branch preference:

"Would you like to create a new feature branch, or work on the current branch?"

If new branch requested:

• Run: .specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"
• Script will handle branch creation with user approval (Principle VI)
• Script returns JSON with branch, spec_file, and feature_number

If current branch:

• Use current branch name
• Create spec file at: specs/[current-branch]/spec.md
• Ensure specs/[current-branch]/ directory exists

Step 2: Load Template

Read the specification template:

Read: .specify/templates/spec-template.md

Template sections to preserve:

• Title (# Feature Name)
• Overview
• User Stories
• Functional Requirements
• Acceptance Criteria
• Technical Considerations
• Dependencies
• Risks
• Success Metrics

Step 3: Write Specification

Fill the template with details from user's feature description:

• Replace all placeholders with concrete information
• Maintain section structure and order
• Use clear, measurable acceptance criteria
• Include user stories in "As a [role], I want [capability], so that [benefit]" format
• Document technical considerations and dependencies

Write to spec file:

Write: specs/[branch-name]/spec.md

Step 4: Domain Detection

Run domain detection to identify which agents/domains are involved:

.specify/scripts/bash/detect-phase-domain.sh --file specs/[branch-name]/spec.md

Capture output:

• Detected domains (frontend, backend, database, etc.)
• Suggested agents (specialist agents to involve)
• Delegation strategy (single-agent vs multi-agent)

Report to user:

Detected domains: [list]
Suggested agents: [list]
Delegation strategy: [single-agent or multi-agent]

Step 5: Validate Specification

Run specification validation:

.specify/scripts/bash/validate-spec.sh --file specs/[branch-name]/spec.md

Validation checks (4 required, 5 recommended, 1 optional):

• Required: Title, Requirements, Acceptance Criteria, User Stories
• Recommended: Overview, Technical Considerations, Dependencies, Risks, Success Metrics
• Optional: Timeline

Report validation results:

• Overall score (X/10 checks passing)
• Readiness status (ready/needs-improvement)
• Specific recommendations for improvement

Step 6: Report Completion

Provide comprehensive summary:

✅ Feature Specification Created

Branch: [branch-name]
Spec File: specs/[branch-name]/spec.md
Feature Number: [###] (if new branch)

Domains Detected: [list]
Suggested Agents: [list]

Validation Score: X/10
Status: [ready/needs-improvement]

Next Step: Run /plan to generate implementation plan

Constitutional Compliance

Principle VI: Git Operation Approval

• NEVER create branches without explicit user approval
• Ask user if they want a new branch
• If yes, run create-new-feature.sh which handles approval
• Script will request approval before branch creation

Principle VIII: Documentation Synchronization

• Specification is primary documentation artifact
• Must include all required sections per template
• Specification drives planning and implementation
• Keep specification in sync with feature evolution

Principle X: Agent Delegation Protocol

• Domain detection identifies which agents are needed
• Report suggested agents for implementation phase
• If multi-domain feature, note that task-orchestrator should coordinate

Examples

Example 1: New User Authentication Feature

User Request: "/specify User authentication with email and password"

Skill Execution:

1. Ask: "Would you like to create a new feature branch, or work on the current branch?"
2. User chooses new branch
3. Run: .specify/scripts/bash/create-new-feature.sh --json "User authentication with email and password"
4. Script creates branch: 001-user-authentication
5. Load template from .specify/templates/spec-template.md
6. Write specification with:
   • Title: "User Authentication"
   • User stories: "As a new user, I want to register with email/password..."
   • Requirements: Authentication endpoints, password hashing, session management
   • Acceptance criteria: User can register, login, logout
7. Run domain detection → detects: backend, database, security
8. Run validation → 9/10 checks passing (missing timeline)
9. Report completion with suggested agents: backend-architect, database-specialist, security-specialist

Expected Output:

✅ Feature Specification Created

Branch: 001-user-authentication
Spec File: specs/001-user-authentication/spec.md
Feature Number: 001

Domains Detected: backend, database, security
Suggested Agents: backend-architect, database-specialist, security-specialist
Delegation Strategy: multi-agent (recommend task-orchestrator)

Validation Score: 9/10
Status: ready

Recommendations:
- Consider adding implementation timeline

Next Step: Run /plan to generate implementation plan

Example 2: Update Existing Specification

User Request: "/specify Add OAuth support to existing authentication"

Skill Execution:

1. Ask about branch (user chooses current branch: 001-user-authentication)
2. Read existing spec: specs/001-user-authentication/spec.md
3. Update specification to add OAuth sections
4. Run domain detection → detects: backend, integration, security
5. Run validation → 10/10 checks passing
6. Report completion with updated suggested agents

Agent Collaboration

specification-agent

When to delegate: For creating user stories, acceptance criteria, functional requirements from business needs

What they handle: Translating business requirements into technical specifications using SDD methodology

task-orchestrator

When to delegate: When multi-domain feature detected (3+ domains)

What they handle: Coordinating multiple specialized agents during implementation

Domain Specialists

When to notify: Report suggested agents based on domain detection

What they handle: Implementation of specification in their domain

Validation

Verify the skill executed correctly:

• Specification file created at correct path
• All required sections present in specification
• Domain detection executed and reported
• Validation executed and reported
• Suggested agents reported to user
• Validation score indicates readiness
• User notified about next step (/plan)

Troubleshooting

Issue: Branch creation fails

Cause: User denied git approval or branch already exists

Solution:

• If user denied: Ask if they want to use current branch instead
• If branch exists: Ask if they want to update existing spec or create different branch name

Issue: Validation score low (<7/10)

Cause: Specification missing recommended sections

Solution:

• Review validation output for specific missing sections
• Ask user for additional information
• Update specification with missing sections
• Re-run validation

Issue: No domains detected

Cause: Specification too vague or generic

Solution:

• Review specification for technical details
• Ask user clarifying questions about implementation
• Add technical considerations section with specific technologies
• Re-run domain detection

Notes

• Specification is the foundation of SDD workflow (Spec → Plan → Tasks)
• High-quality specifications lead to better plans and tasks
• Domain detection early enables proactive agent coordination
• Validation ensures specifications are actionable
• All specifications must follow template structure for consistency
• Template located at: .specify/templates/spec-template.md

Related Skills

• sdd-planning: Next step after specification (generates implementation plan)
• domain-detection: Standalone domain detection for existing files
• specification-agent: Agent that can be delegated specification work