planning-with-files

Planning with Files

The IMPLEMENTATION-PROMPT Pattern

Large tasks need a written plan before code. The plan lives as a file so it can be reviewed, versioned, and referenced across sessions.

File naming: IMPLEMENTATION-PROMPT-{FEATURE}.md in the project root or docs/ directory.

Structure:

# Implementation: {Feature Name}

## Goal
One sentence. What does success look like?

## Context
What exists today. What needs to change. Links to relevant spec sections.

## Plan

### Phase 1: {Name}
- Step 1: {specific action}
  - Verify: {how to confirm it worked}
- Step 2: {specific action}
  - Verify: {how to confirm it worked}

### Phase 2: {Name}
...

## Edge Cases
- {case}: {how to handle}

## Out of Scope
- {thing we're explicitly NOT doing}

Breaking Large Tasks into Phases

Each phase should be:

• Independently testable
• Committable on its own
• Small enough for one session (or one focused block within a session)

Signs a phase is too big:

• More than 5-7 steps
• Touches more than 3-4 files substantially
• You can't describe the verification in one sentence

Signs a phase is too small:

• It's just one line change
• The verification is "it compiles"
• It doesn't move the feature forward meaningfully

The Plan-Review Workflow

Before implementing, send the plan through the plan-reviewer agent:

1. Write the IMPLEMENTATION-PROMPT file
2. Use /review-plan to trigger review
3. The plan-reviewer (Opus) acts as a staff engineer:
   • Flags ambiguity
   • Identifies missing verification steps
   • Checks SPEC.md alignment
   • Questions unrealistic scope
   • Points out edge cases
4. Address ALL feedback before proceeding
5. Update the plan file with revisions

Don't skip review for non-trivial work. The 5 minutes spent reviewing saves hours of rework.

Progressive Implementation

Execute one phase at a time:

1. Read the plan
2. Implement the phase
3. Run verification for that phase
4. Commit
5. Update PROGRESS.md
6. Move to next phase

If a phase reveals the plan was wrong, STOP. Update the plan first. Don't improvise your way through a broken plan.