SDD Planning Skill

When to Use

Activate this skill when:

• User invokes /plan command
• User requests implementation planning for a feature
• User asks "how should we implement this?"
• Specification is complete and ready for technical design
• Need to generate data models, contracts, and test scenarios

Trigger Keywords: plan, implementation plan, technical design, how to implement, architecture, design, /plan

Prerequisites: Feature specification must exist (typically from /specify command)

Procedure

Step 1: Setup and Initialization

Run setup script to get feature paths:

.specify/scripts/bash/setup-plan.sh --json

Parse JSON output to extract:

• FEATURE_SPEC: Path to feature specification
• IMPL_PLAN: Path to implementation plan (plan.md)
• SPECS_DIR: Directory for all feature artifacts
• BRANCH: Current feature branch name

IMPORTANT: All file paths must be absolute (from repository root)

Step 2: Analyze Specification

Read and understand the feature specification:

Read: $FEATURE_SPEC

Extract key information:

• Feature requirements and user stories
• Functional and non-functional requirements
• Success criteria and acceptance criteria
• Technical constraints and dependencies
• Domain context

Step 3: Review Constitutional Requirements

Read the constitution to ensure compliance:

Read: .specify/memory/constitution.md

Focus on core principles:

• Principle I: Library-First Architecture - Feature must start as standalone library
• Principle II: Test-First Development - Tests written before implementation
• Principle III: Contract-First Design - Define contracts before code
• Principle IX: Dependency Management - All dependencies declared

Step 4: Execute Plan Template

Load the plan template:

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

The plan template is self-executing - follow its 9-step Execution Flow:

Phase 0: Research & Analysis

• Technical research for feature requirements
• Technology evaluation and selection
• Architecture patterns identification
• Risk assessment
• Generate: $SPECS_DIR/research.md

Phase 1: Design Artifacts

• Data model definition (entities, relationships, schemas)
  • Generate: $SPECS_DIR/data-model.md
• API contract definition (endpoints, request/response schemas)
  • Generate: $SPECS_DIR/contracts/*.md (one file per endpoint/contract)
• Test scenario definition (from user stories)
  • Generate: $SPECS_DIR/quickstart.md

Phase 2: Execution Planning

• Implementation roadmap
• Task breakdown with dependencies
• Note: tasks.md generation is deferred to /tasks command

Incorporate user-provided details:

• Add any additional context from command arguments to Technical Context section
• User may provide implementation preferences, technology choices, constraints

Update Progress Tracking as you complete each phase:

• Mark phases as complete
• Note any errors or blockers
• Track generated artifacts

Step 5: Verify Execution

Check that all phases completed successfully:

• Phase 0: research.md exists and is comprehensive
• Phase 1: data-model.md exists with entities defined
• Phase 1: contracts/ directory exists with contract files
• Phase 1: quickstart.md exists with test scenarios
• Phase 2: Implementation approach documented in plan.md
• Progress Tracking shows all phases complete
• No ERROR states in execution

Step 6: Validate Implementation Plan

Run plan validation:

.specify/scripts/bash/validate-plan.sh --file $IMPL_PLAN

Validation checks (16 total):

Constitutional Compliance (3 checks):

• Library-First: Plan mentions library/package/module
• Test-First: Plan mentions testing/TDD
• Contract-First: Plan mentions contracts/API/interfaces

Artifact Existence (4 checks):

• research.md exists
• data-model.md exists
• contracts/ directory exists
• quickstart.md exists

Plan Content Quality (9 checks):

• Has overview section
• Has architecture section
• Has implementation phases
• Has testing strategy
• Has dependencies section
• Has risks section
• Has timeline section
• Has technical stack
• Has deployment strategy

Report validation results:

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

Step 7: Domain Detection

Run domain detection on plan:

.specify/scripts/bash/detect-phase-domain.sh --file $IMPL_PLAN

Confirm domain alignment:

• Compare detected domains with specification domains
• Identify any NEW domains that emerged during planning
• Report any discrepancies

Capture suggested agents:

• Specialist agents needed for implementation
• Delegation strategy (single-agent vs multi-agent)

Step 8: Report Completion

Provide comprehensive summary:

✅ Implementation Plan Generated

Branch: [branch-name]
Plan File: [path-to-plan.md]

Generated Artifacts:
- research.md: [Technical research and decisions]
- data-model.md: [Entities and schemas]
- contracts/: [X contract files]
- quickstart.md: [Test scenarios]

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

Domains Detected: [list]
Suggested Agents: [list]
Delegation Strategy: [single-agent/multi-agent]

Constitutional Compliance:
✅ Library-First Architecture
✅ Test-First Development
✅ Contract-First Design

Next Step: Run /tasks to generate implementation task list

Constitutional Compliance

Principle I: Library-First Architecture

• Ensure plan describes feature as standalone library
• Library has clear public API
• Library is reusable and testable independently
• Document library structure in research.md

Principle II: Test-First Development

• quickstart.md must include test scenarios BEFORE implementation
• Testing strategy documented in plan
• Each contract has corresponding test scenario
• Test scenarios cover happy path, error cases, edge cases

Principle III: Contract-First Design

• All contracts defined in contracts/ directory BEFORE implementation
• Each endpoint/interface documented with:
  • Request schema
  • Response schema
  • Error cases
  • Examples
• Contracts drive implementation

Principle VIII: Documentation Synchronization

• All artifacts generated together
• Plan references all artifacts
• Artifacts cross-reference each other
• Documentation complete before implementation starts

Principle IX: Dependency Management

• All dependencies listed in research.md
• Dependency rationale documented
• Version constraints specified
• Licenses verified

Examples

Example 1: REST API Feature Planning

User Request: "/plan Add pagination, filtering, and sorting to user list API"

Skill Execution:

1. Run setup-plan.sh → get paths for current feature branch
2. Read specification → understand user list API requirements
3. Read constitution → verify Library-First, Test-First, Contract-First
4. Execute plan template:
   • Phase 0: Research pagination patterns, filtering syntax, sorting algorithms
   • Phase 1:
     • data-model.md: PaginatedResponse, FilterCriteria, SortOrder entities
     • contracts/get-users-paginated.md: GET /api/users with query params
     • quickstart.md: Test scenarios for pagination, filtering, sorting
   • Phase 2: Implementation approach documented
5. Verify all artifacts generated
6. Run validation → 16/16 checks passing
7. Run domain detection → backend, database domains
8. Report completion with suggested agents: backend-architect, database-specialist

Generated Artifacts:

specs/001-user-list-api/
├── spec.md (from /specify)
├── plan.md (implementation plan)
├── research.md (pagination patterns, filtering)
├── data-model.md (PaginatedResponse, FilterCriteria, SortOrder)
├── contracts/
│   └── get-users-paginated.md (GET /api/users contract)
└── quickstart.md (test scenarios)

Example 2: React Component Planning

User Request: "/plan Implement user profile card component with avatar, name, bio"

Skill Execution:

1. Setup paths
2. Read specification → understand component requirements
3. Read constitution
4. Execute plan template:
   • Phase 0: Research React component patterns, styling approach, accessibility
   • Phase 1:
     • data-model.md: UserProfile interface, Avatar interface
     • contracts/profile-card-component.md: Component props, events, slots
     • quickstart.md: Component test scenarios (rendering, interactions, edge cases)
   • Phase 2: Implementation approach (component structure, state management)
5. Verify artifacts
6. Run validation → 15/16 passing (missing deployment for component)
7. Run domain detection → frontend domain
8. Report completion with suggested agent: frontend-specialist

Agent Collaboration

backend-architect

When to delegate: Multi-service architecture, complex backend systems

What they handle: Backend system design, API architecture, service patterns

frontend-specialist

When to delegate: UI components, user interactions, client-side logic

What they handle: Component design, state management, UI patterns

database-specialist

When to delegate: Complex data models, query optimization, schema design

What they handle: Database schema, relationships, indexing, query patterns

task-orchestrator

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

What they handle: Coordinating multiple specialists during implementation

Validation

Verify the skill executed correctly:

• setup-plan.sh executed and paths extracted
• Feature specification read and analyzed
• Constitution reviewed and applied
• Plan template executed through all phases
• research.md generated and comprehensive
• data-model.md generated with entities
• contracts/ directory has contract files
• quickstart.md generated with test scenarios
• Plan validation executed and reported
• Domain detection executed and reported
• Suggested agents reported to user
• User notified about next step (/tasks)

Troubleshooting

Issue: setup-plan.sh fails with "No specification found"

Cause: Feature specification doesn't exist or is in wrong location

Solution:

• Verify spec.md exists in current branch's specs/ directory
• Run /specify first to create specification
• Check branch name matches specs directory name

Issue: Validation score low (<12/16)

Cause: Plan missing required sections or artifacts not generated

Solution:

• Review validation output for specific failures
• Check that all Phase 0 and Phase 1 artifacts exist
• Ensure plan.md includes all required sections
• Re-run plan template phases that failed

Issue: No contracts generated

Cause: Feature doesn't define external interfaces or API contracts unclear

Solution:

• Review specification for API endpoints or component interfaces
• If truly no external contracts, document internal interfaces
• Create at least one contract showing module public API
• Update plan to clarify contract boundaries

Issue: Domain detection shows different domains than specification

Cause: Planning revealed additional technical requirements

Solution:

• This is expected - planning adds technical detail
• Report discrepancy to user
• Suggest updating specification if domains significantly changed
• Proceed with planning if domains are additive (e.g., added database to frontend feature)

Notes

• Planning phase is critical - quality here affects all downstream work
• Plan template is self-executing - trust its process
• All three artifacts (research, data-model, contracts) must exist before tasks
• Contracts define "what" to build, plan defines "how" to build
• quickstart.md test scenarios drive TDD implementation
• Use absolute paths to avoid path resolution issues
• Domain detection may reveal domains not apparent in specification
• Multi-domain features benefit from task-orchestrator coordination

Related Skills

• sdd-specification: Previous step (creates specification)
• sdd-tasks: Next step (generates task list from plan)
• constitutional-compliance: Validates constitutional principle adherence
• api-contract-design: Deep-dive into contract definition (Priority 3)