/dev-specs - Lean Implementation Specifications

Skill Awareness: See skills/_registry.md for all available skills.

• Before: Ensure /debrief completed (BRD exists)
• Auto: Runs /dev-scout if tech-context.md missing
• During: Calls /dev-arch for patterns
• Reads: _quality-attributes.md (Specification Level)
• After: Use /dev-coding for implementation

Generate lean, requirements-focused specs from BRD use cases. Focuses on WHAT to build, not HOW.

When to Use

• After /debrief created BRD use cases
• Before starting implementation
• When onboarding engineers to a feature

Usage

/dev-specs auth                              # Generate specs for auth feature
/dev-specs auth UC-AUTH-001                  # Single use case only
/dev-specs billing --api=swagger.json        # With API spec file
/dev-specs payments --schema=schema.prisma   # With DB schema

Core Rule: WHAT, Not HOW

Specs define requirements and constraints, not implementation details.

Include:

• Requirements (testable, bulleted)
• Technical constraints (stack, location, patterns)
• Acceptance criteria (testable outcomes)
• File checklist (where to work)

Exclude:

• Pseudocode (gets stale)
• Detailed implementation (discovered during coding)
• Code examples (reference existing patterns instead)

Prerequisites

1. plans/brd/ exists with use cases
2. plans/features/{feature}/ exists
3. plans/brd/tech-context.md exists (auto-runs scout if missing)

Output Structure

plans/features/{feature}/
├── codebase-context.md          # From /dev-scout
└── specs/
    ├── README.md                # Index, implementation order
    ├── shared/                  # Shared across UCs
    │   ├── data-model.md
    │   ├── patterns.md
    │   └── security.md
    └── UC-XXX-001-slug.md       # Lean spec per UC (~150 lines)

Expected Outcome

Lean specs (~150 lines per UC) that define WHAT to build, not HOW.

Output structure:

plans/features/{feature}/
├── codebase-context.md          # From /dev-scout
└── specs/
    ├── README.md                # Index, implementation order
    ├── shared/                  # Shared across UCs
    │   ├── data-model.md
    │   ├── patterns.md
    │   └── security.md
    └── UC-XXX-001-slug.md       # Lean spec per UC

Each UC spec includes:

• Requirements - WHAT to achieve (testable outcomes)
• Acceptance Criteria - HOW to verify it works
• Technical Constraints - Stack patterns to use (reference tech-context.md)
• Work Area - General location (e.g., "auth feature area", NOT specific files)
• API Contract - If external interface
• Dependencies - What must exist first

Each UC spec does NOT include:

• ❌ Specific file names to create/modify
• ❌ DO/DON'T implementation lists
• ❌ Pseudocode or step-by-step instructions
• ❌ "How to code" details

Engineer figures out: File names, implementation approach, code structure

Success Criteria

• Engineer knows WHAT to build
• Engineer knows WHERE to build it (file checklist)
• Engineer can verify success (acceptance criteria)
• Specs reference existing patterns, don't rewrite them
• Stack-aware (uses tech-context.md patterns)
• ~150 lines per UC spec max

Prerequisites

Auto-checked and resolved:

1. plans/brd/ exists with use cases
2. plans/features/{feature}/ exists
3. plans/brd/tech-context.md exists (auto-runs project scout if missing)
4. plans/features/{feature}/codebase-context.md exists (auto-runs feature scout if missing)

Context Sources

Read these to understand HOW:

• tech-context.md - Project patterns (API, data, structure)
• codebase-context.md - Feature-specific implementation
• architecture.md - Architecture decisions (call /dev-arch if missing)
• _quality-attributes.md - Specification Level checklist

Read these to understand WHAT:

• plans/brd/use-cases/{feature}/*.md - Business requirements
• plans/docs-graph.json - Dependencies between UCs

Scope Inference

Analyze UC to determine what's needed (don't ask user):

From UC content, infer:

• UI needed? → UC mentions forms, pages, views, user sees/clicks/enters
• API needed? → UC mentions data operations, persistence, validation
• Both? → Full-stack (most common)
• Testing level → From _quality-attributes.md or project standards

Example:

• UC: "User can login via email/password form" → Full-stack (form + API + validation)
• UC: "System sends daily report email" → Backend only (cron job + email service)
• UC: "User sees loading spinner during API calls" → Frontend only (UI state)

Only ask user for additional context if helpful:

• API specs (Swagger, OpenAPI) if integrating external API
• Design files (Figma) if complex UI
• DB schema if existing database

Impact Analysis

For each UC, identify:

• What's new? (files to create)
• What changes? (files to modify)
• What's shared? (reusable across UCs →

...