planning-with-fileslisted

# Planning with Files Use this pattern for any task where you can't complete everything in one pass: long refactors, migrations, multi-feature buildouts, research tasks, or anything with more than ~5 tool calls. File-based state survives context resets and gives you (and the user) a running record of what's been done. Place planning files in `docs/operational/` if the harness is linked, or in a `.planning/` directory at the project root — whichever exists. --- ## Files to create at the start ### `task_plan.md` Written **before** any implementation. Contains: ```markdown # Task: <short title> ## Goal One sentence: what does "done" look like? ## Scope What's in and what's explicitly out. ## Steps 1. Step one (estimate: small/medium/large) 2. Step two 3. ... ## Open questions - Question 1 (unblocks: step 3) ## Success criteria - [ ] Criterion A - [ ] Criterion B ``` ### `findings.md` Appended to **as you work**. Never edited retroactively. ```markdown # Findings ## <ISO timestamp> **Context:** What you were investigating. **Finding:** What you learned. **Impact:** Does it change the plan? If yes, add a note to task_plan.md. ``` ### `progress.md` Updated **after each step completes**: ```markdown # Progress ## Completed - [x] Step 1 — <one-line summary> (commit: <sha>) ## In progress - [ ] Step 2 — started <timestamp> ## Blocked - Step 3 — waiting on: <reason> ## Next action <Exact next thing to do when resuming> ``` --- ## Workflow ``` 1. Read existing