Welcome to Unit 5! You've learned to evaluate specifications in Units 1-4. Now you'll learn the actual Spec-Driven Development workflow: collaborating with AI to generate specifications.

The Traditional Mistake:

Many developers think SDD means "write detailed specifications by hand before coding." That's the old way - and it's why specification-driven approaches failed historically. They were too time-consuming.

The SDD Reality with AI:

In modern SDD with Claude Code:

• Humans provide requirements and intent (structured prompts)
• AI generates formal specifications using templates
• Humans review for quality and business correctness
• AI refines based on feedback
• Humans approve when spec meets quality threshold

Your Role in the Partnership:

You are NOT a specification writer. You are a specification architect:

• Define WHAT you want (business intent)
• Review AI-generated specs critically
• Catch domain knowledge AI doesn't have
• Guide refinement through targeted feedback
• Approve when quality threshold met (≥75/100)

AI's Role:

Claude Code is your specification generator:

• Systematically covers all template sections
• Considers edge cases you might forget
• Maintains consistent format
• Generates complete technical plans
• But needs your domain expertise to validate

Humans define WHAT and WHY. AI generates HOW.

This division leverages each party's strengths:

• Humans excel at understanding business needs, domain constraints, and user value
• AI excels at systematic documentation, comprehensive coverage, and consistent formatting

With AI assistance, specification creation becomes faster than jumping straight to code while producing better outcomes.

Here's the typical workflow when building features with AI assistance:

1. Human provides structured requirements - Context, requirements, user perspective, constraints
2. AI generates comprehensive specification - Follows template, covers all sections
3. Human reviews critically - Validates business logic, checks domain accuracy, scores on 5 dimensions
4. AI refines based on feedback - Addresses specific issues, adds missing details
5. Human approves final spec - Confirms ≥75/100 score, verifies readiness
6. AI generates tests and implementation - Creates tests and code matching specification
7. Human validates against business needs - Runs tests, checks behavior

This workflow transforms specification from a bottleneck into an accelerator.

When you want to add a feature to TaskMaster, you start by giving Claude Code requirements in a structured prompt.

Essential Prompt Structure:

Three critical sections for quality:

• ANALYZE EXISTING CODE - AI extracts patterns from your codebase
• EXAMPLE REFERENCE - AI matches your existing spec quality/style
• CONSTRAINTS - Guards against implementation details and vague language

Impact on iterations:

Score specifications out of 100 across five dimensions:

1. Clarity (0-25) - Terms defined, no ambiguity (❌ "Valid format" → ✅ "Regex: ^[a-z0-9-]{1,30}$")
2. Completeness (0-25) - All template sections present, no [TBD] markers
3. Testability (0-20) - Given/When/Then format, concrete examples with real data
4. Consistency (0-20) - Follows CLAUDE.md, matches existing API patterns
5. Appropriate Abstraction (0-10) - WHAT not HOW, no database/code details

Calibrating Your Scores:

Use these ranges to score consistently:

Clarity (0-25):

• 20-25: All terms defined precisely with formats/patterns. Zero ambiguous language.
• 15-19: Most terms defined, 1-2 need precision (e.g., "reasonable limit" vs "10 max")
• 10-14: Multiple vague terms, but core concepts understandable
• 0-9: Ambiguity prevents understanding requirements

Completeness (0-25):

• 20-25: All template sections present with substance. No [TBD] or "will be determined"
• 15-19: All sections present, but 1-2 are thin (single sentence where paragraph needed)
• 10-14: Missing 1 section OR multiple sections are stubs
• 0-9: Multiple sections missing or mostly empty

Testability (0-20):

• 16-20: All scenarios in Given/When/Then. Examples use real formats (UUID4, ISO-8601)
• 12-15: Structured scenarios but some examples use placeholders ("some-id", "timestamp")
• 8-11: Scenarios present but lack concrete structure or realistic data
• 0-7: No structured scenarios, or only narrative descriptions

Consistency (0-20):

• 16-20: Matches all CLAUDE.md conventions (naming, error formats, response structure)
• 12-15: Follows most conventions, 1-2 minor deviations
• 8-11: Multiple inconsistencies with existing API patterns

10-Minute Triage: All sections present? Obvious vague terms? Matches conventions? Examples realistic?

30-Minute Deep Review: Score each dimension, identify specific issues

5-Minute Revision Check: Feedback addressed? Score ≥75?

Give specific feedback:

• ✅ "Line 42: Replace 'valid format' with regex: ^[a-z0-9-]{1,30}$"
• ❌ "Make it clearer"

1. Prepare prompt (5 min): Identify related code/specs, gather requirements
2. Generate (2 min): Provide enhanced prompt to Claude
3. Review and score (10-30 min): Evaluate on 5 dimensions
4. Refine (5-10 min/iteration): Specific feedback, re-score
5. Approve (≥75 score): Proceed to implementation

Result: 10-15 minutes to approved spec vs. 20-25 minutes with informal prompts.