Writing Plans

Create implementation plans from approved specs. The output is consumed by executing-plans or subagent-driven-development.

Process

Step 1: Read the Spec

• Read the approved spec in docs/specs/
• Identify: requirements, architecture changes, success criteria
• Note any open questions before planning

Step 2: Break Down Into Phases

Each phase must be:

• Independently deliverable — it can be merged on its own
• Incrementally testable — tests can verify it at the end of the phase
• Scope-bounded — clear start and end

Phase structure:

• Phase 1: Minimum viable (smallest slice with value)
• Phase 2: Core experience (complete happy path)
• Phase 3: Edge cases (error handling, polish)
• Phase 4: Optimization (performance, monitoring) — if needed

Step 3: Write Each Step

Each step must include:

• File: exact path
• Action: specific change to make
• Why: rationale
• Dependencies: which steps must precede this
• Risk: Low / Medium / High

Step 4: Add Testing Strategy

For each phase, specify:

• Unit tests: which functions/components
• Integration tests: which flows
• E2E tests: which user journeys

Step 5: Write Plan File

Save to docs/plans/YYYY-MM-DD-<feature>.md

# Implementation Plan: [Feature Name]

## Overview
[2-3 sentences]

## Requirements
- [Requirement 1]

## Architecture Changes
- [file path]: [description]

## Implementation Steps

### Phase 1: [Name] — Minimum Viable
1. **[Step]** (File: path/to/file.ts)
   - Action: ...
   - Why: ...
   - Dependencies: None
   - Risk: Low

## Testing Strategy
- Unit: [files]
- Integration: [flows]
- E2E: [journeys]

## Success Criteria
- [ ] Criterion 1

Step 6: Confirm Plan with Human

Present the plan and confirm before execution begins.

Quality Checks

• Every step has an exact file path
• Every step has a specific action
• Phases are independently mergeable
• Testing strategy covers all new code paths
• No step is larger than 50 lines of code