planning-with-fileslisted

# 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: ```markdown # 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 a