Plan

Implementation Planning

Quick Reference

Decision Tree

How big is this change?
├── 1-2 files, well-defined → Just do it (no plan needed)
├── 3-5 files, clear scope → Lightweight plan in conversation
├── 5+ files or architectural → Full written plan
├── Requirements unclear → Interview first
└── Feasibility unknown → Prototype first

When to Plan Formally

• Architectural changes (new auth system, database migration)
• Multi-service changes (frontend + backend + database)
• Changes where ordering matters (migrations before code)
• When you need team alignment before coding
• Unfamiliar codebases -- planning forces understanding first

What a Plan Should Contain

1. Scope -- what's changing and what's not
2. Steps -- numbered, ordered by dependency
3. Files -- specific files to create or modify per step
4. Verification -- how to test each step
5. Risks -- what could go wrong, rollback strategy

Plan Template

## Plan: [Feature Name]

### Scope
- Adding: [new capabilities]
- Modifying: [existing files/behavior]
- Not touching: [explicitly out of scope]

### Steps

1. **[Step name]**
   - Create/modify: `path/to/file.ts`
   - Details: [what specifically to do]
   - Verify: [how to confirm this step works]

2. **[Step name]**
   - Depends on: Step 1
   - Create/modify: `path/to/file.ts`
   - Verify: [test command or check]

### Risks
- [Risk]: [Mitigation]

Executing Plans

1. Execute one step at a time
2. Verify after each step (run tests, check build)
3. Don't skip ahead -- dependencies matter
4. If a step fails, fix before proceeding
5. Update the plan if reality diverges from it

Interview-Then-Execute

When requirements are unclear, have the agent interview you before coding.

Pattern

1. "I need [vague feature]. Interview me to understand the requirements."
2. Agent asks 5-10 targeted clarifying questions
3. You answer, refining scope and constraints
4. Agent produces a plan based on answers
5. Review, adjust, then execute in a fresh session

Why Separate Sessions

• Planning session fills context with requirements discussion
• Execution session gets clean context with only the finalized plan
• Produces better code than doing both in one session

Prototype Over Spec

For exploratory work where requirements are uncertain, build instead of specifying.

Pattern

Instead of: Write a 10-page PRD → review → implement → discover it's wrong
Do:         Build rough prototype → iterate 5-10 times → extract spec from what works

When to Prototype

• New product ideas (you don't know what you want yet)
• UI/UX exploration (seeing beats describing)
• API design (try using it before specifying it)
• Algorithm selection (benchmark, don't theorize)

When NOT to Prototype

• Well-defined bug fixes (just fix it)
• API contracts between teams (spec first)
• Database migrations (plan carefully, prototyping is dangerous)
• Security-critical code (spec and review first)

Plan Review

Before executing a non-trivial plan, consider second-opinion review.

Self-Review Checklist

• Are steps in correct dependency order?
• Does each step have clear verification?
• Are there any missing steps?
• Is scope creep controlled (not adding extras)?
• Can each step be independently tested?

Second Opinion Pattern

1. Write the plan
2. Start a fresh session
3. "Review this plan as a staff engineer. What's missing, what could go wrong?"
4. Incorporate feedback
5. Execute in yet another session (clean context)

Anti-Patterns