Writing Implementation Plans from Specifications

Overview

Generate detailed implementation plans derived FROM specifications, not from scratch.

The spec is the source of truth. The plan translates spec requirements into concrete, actionable implementation tasks.

Key Difference from Standard Writing-Plans:

• Input is SPEC (not blank slate)
• Plan MUST cover all spec requirements
• Plan validates against spec for completeness
• Tasks reference spec sections explicitly

When to Use

Use this skill when:

• Spec exists and is validated
• Ready to create implementation plan
• Called by sdd:implement workflow
• Need to break spec into tasks

Don't use this skill when:

• No spec exists → Create spec first
• Plan already exists → Review/update existing plan
• Just clarifying approach → Use brainstorming

Prerequisites

• Spec exists and is complete
• Spec validated for soundness
• No blocking open questions in spec
• Ready to start implementation

The Process

1. Read and Parse Specification

Load the spec:

cat specs/features/[feature-name].md

Extract all elements:

• Functional requirements (what to build)
• Non-functional requirements (how it should perform)
• Success criteria (how to verify)
• Error handling (what can go wrong)
• Edge cases (boundary conditions)
• Dependencies (what's needed)
• Constraints (limitations)

Create requirements checklist:

• Number each requirement
• Reference spec section
• Mark coverage status

2. Understand Project Context

Check existing codebase:

# Find related files
rg "[relevant-terms]"

# Check architecture
ls -la src/

# Review dependencies
cat package.json  # or requirements.txt, go.mod, etc.

Identify:

• Where new code should live
• Existing patterns to follow
• Components to reuse
• Integration points

3. Design Implementation Strategy

For each functional requirement, determine:

Approach:

• How will this be implemented?
• What components are needed?
• What patterns apply?

Files:

• What files to create?
• What files to modify?
• Full file paths

Dependencies:

• What needs to exist first?
• What can be done in parallel?
• What's the critical path?

Testing:

• How will this be tested?
• What test files needed?
• What edge cases to cover?

4. Create Implementation Plan

Use this structure:

# Implementation Plan: [Feature Name]

**Source Spec:** specs/features/[feature-name].md
**Date:** YYYY-MM-DD
**Estimated Effort:** [time estimate if relevant]

## Overview

[Brief summary of what we're implementing and why]

## Requirements Coverage

### Functional Requirement 1: [Quote from spec]
**Spec Reference:** specs/features/[feature].md#[section]

**Implementation Approach:**
[How we'll implement this requirement]

**Tasks:**
- [ ] [Specific actionable task]
- [ ] [Another task]

**Files to Create/Modify:**
- `path/to/file.ext` - [What changes]

**Tests:**
- [ ] [Test case for this requirement]

---

### Functional Requirement 2: [Quote from spec]
[Repeat structure]

---

[Continue for ALL functional requirements]

## Non-Functional Requirements

[For each non-functional requirement from spec]

### [Requirement Name]: [Quote from spec]
**Spec Reference:** specs/features/[feature].md#[section]

**Implementation:**
[How we'll achieve this]

**Validation:**
[How we'll measure/verify this]

## Error Handling Implementation

[For each error case in spec]

### Error: [From spec]
**Spec Reference:** specs/features/[feature].md#error-handling

**Implementation:**

[Code approach or pseudocode]

**Test Cases:**
- [ ] [Test for this error case]

## Edge Cases Implementation

[For each edge case in spec]

### Edge Case: [From spec]
**Expected Behavior:** [From spec]

**Implementation:**
[How we'll handle this]

**Test:**
- [ ] [Test for edge case]

## Dependencies

**Required Before Implementation:**
- [ ] [Dependency 1 from spec]
- [ ] [Dependency 2 from spec]

**Integration Points:**
- [Component/service 1]: [How we integrate]
- [Component/service 2]: [How we integrate]

## Implementation Order

**Phase 1: Foundation**
1. [Task]
2. [Task]

**Phase 2: Core Functionality**
1. [Task]
2. [Task]

**Phase 3: Error Handling**
1. [Task]
2. [Task]

**Phase 4: Edge Cases & Polish**
1. [Task]
2. [Task]

## Test Strategy

**Unit Tests:**
- [ ] [Component/function to test]
- [ ] [Another component/function]

**Integration Tests:**
- [ ] [Integration scenario]
- [ ] [Another scenario]

**Spec Compliance Tests:**
- [ ] [Verify requirement 1]
- [ ] [Verify requirement 2]

## Files to Create

- `path/to/new/file1.ext` - [Purpose]
- `path/to/new/file2.ext` - [Purpose]

## Files to Modify

- `path/to/existing/file1.ext` - [What changes]
- `path/to/existing/file2.ext` - [What changes]

## Success Criteria

[From spec, repeated here for reference]
- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Spec Validation Checklist

**All requirements covered:**
- [ ] All functional requirements have tasks
- [ ] All non-functional requirements addressed
- [ ] All error cases have implementation approach
- [ ] All edge cases have handling strategy
- [ ] All dependencies identified
- [ ] All success criteria have verification plan

**Plan completeness:**
- [ ] All tasks are specific and actionable
- [ ] All file paths are complete (not "TBD")
- [ ] All requirements reference spec sections
- [ ] Test strategy covers all requirements
- [ ] Implementation order is logical

## Notes

[Any additional context, decisions, or considerations]

5. Validate Plan Against Spec

Completeness check:

For each requirement in spec:

• Plan has implementation approach
• Plan has specific tasks
• Plan has test coverage
• Plan references spec section

Coverage matrix:

Requirement 1 → Tasks [1,2,3], Tests [A,B]     ✓
Requirement 2 → Tasks [4,5], Tests [C,D]       ✓
Requirement 3 → Tasks [6], Tests [E,F,G]       ✓
...

If any requirement uncovered: Add tasks before proceeding.

6. Review for Implementability

Check that plan:

• Has concrete file paths (not "somewhere")
• Has specific tasks (not vague "implement X")
• Has realistic order (dependencies respected)
• Has test coverage (every requirement tested)

Red flags:

• "Figure out how to..."
• "Implement [vague concept]"
• "TBD"
• Missing file paths
• No test strategy

7. Save and Commit Plan

Save plan:

# Location
docs/plans/[date]-[feature]-implementation.md

Commit plan:

git add docs/plans/[date]-[feature]-implementation.md
git commit -m "Add implementation plan for [feature]

Generated from spec: specs/features/[feature].md

Coverage:
- [N] functional requirements
- [N] error cases
- [N] edge cases

Estimated [N] tasks

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>"

Checklist

Use TodoWrite to track:

• Read and parse specification completely
• Extract all requirements, errors, edge cases
• Understand project context and codebase
• Design implementation strategy
• Create implementation plan with all sections
• Validate plan coverage against spec (100%)
• Review plan for implementability
• Ensure all file paths are complete
• Ensure all tasks are specific and actionable
• Save plan to docs/plans/
• Commit plan to git

Example

[Called from sdd:implement]

You: Generating implementation plan from spec...

Reading spec: specs/features/user-profile-api.md

Extracting requirements:
- Functional: 6 requirements
- Non-functional: 3 requirements
- Error cases: 4
- Edge cases: 3
- Dependencies: 2

Understanding project context...
- Existing API routes in: src/api/
- Validation middleware in: src/middleware/
- User service in: src/services/user.ts
- Tests in: tests/api/

Creating implementation plan...

# Implementation Plan: User Profile Update API

**Source Spec:** specs/features/user-profile-api.md
**Date:** 2025-11-10

## Overview

Implement REST API endpoint for authenticated users to update their profiles.
Includes validation, error handling, and partial update support.

## Requirements Coverage

### Functional Requirement 1: PUT endpoint accepts requests
**Spec Reference:** specs/features/user-profile-api.md#functional-requirements

**Implementation Approach:**
Create Express route handler at PUT /api/users/:id/profile using
existing route structure in src/api/users/

**Tasks:**
- [ ] Create route file at src/api/users/profile.ts
- [ ] Register route in src/api/users/index.ts
- [ ] Add route handler function

**Files to Create/Modify:**
- `src/api/users/profile.ts` - New route handler
- `src/api/users/index.ts` - Register route

**Tests:**
- [ ] Test route responds to PUT requests
- [ ] Test route path is /api/users/:id/profile

---

### Functional Requirement 2: Validate request body
**Spec Reference:** specs/features/user-profile-api.md#functional-requirements

**Implementation Approach:**
Create validation middleware using existing validation pattern.
Validate: name (2-50 chars), bio (max 500), avatar_url (URL format).

**Tasks:**
- [ ] Create validation schema in src/middleware/validation/profile.ts
- [ ] Add validation middleware to route
- [ ] Return 422 on validation errors

**Files to Create/Modify:**
- `src/middleware/validation/profile.ts` - Validation schema
- `src/api/users/profile.ts` - Apply middleware

**Tests:**
- [ ] Test name length validation (too short)
- [ ] Test name length validation (too long)
- [ ] Test bio length validation
- [ ] Test avatar_url format validation

[... continues for all requirements ...]

## Spec Validation Checklist

**All requirements covered:**
- [x] All 6 functional requirements have tasks
- [x] All 3 non-functional requirements addressed
- [x] All 4 error cases have implementation
- [x] All 3 edge cases handled
- [x] All 2 dependencies identified
- [x] All 5 success criteria have verification

Plan validated against spec ✓
Coverage: 100%

Saving plan to: docs/plans/2025-11-10-user-profile-api-implementation.md

Plan created ✓
Committed to git ✓

Plan has 24 tasks across 4 phases.
Ready to implement with TDD?

Quality Standards

Every plan MUST have:

• Complete file paths (no "TBD")
• Specific tasks (not vague)
• Test coverage (every requirement)
• Error handling (every error case)
• Edge case coverage (every edge case)
• Spec references (every requirement linked)

Every task MUST be:

• Actionable (clear what to do)
• Testable (can verify completion)
• Atomic (one clear outcome)
• Ordered (dependencies respected)

Common Pitfalls

Avoid:

• Creating plan before spec exists
• Missing spec requirements in plan
• Vague tasks ("implement feature")
• Missing file paths
• No test strategy
• Skipping error cases
• Ignoring edge cases

Instead:

• Always start from spec
• Cover 100% of spec requirements
• Make tasks concrete and specific
• Provide complete file paths
• Test every requirement
• Handle every error case
• Cover every edge case

Remember

The plan is a bridge from spec to code.

• Spec says WHAT
• Plan says HOW and WHERE and WHEN
• Code implements the plan

A good plan makes implementation smooth. A poor plan causes confusion and rework.

Validate against spec before proceeding. 100% coverage is non-negotiable.