Plan Files Are the Source of Truth
Chat history is disposable. The plan file is durable. Every multi-step session writes its evidence into a markdown file that any future session can resume from cold — no handover notes, no "remember to" messages. Resets become cheap.
The problem
Multi-phase work in a Claude Code chat eventually compacts. Once compaction kicks in, what the assistant "remembers" gets lossy in non-obvious ways. You think Claude knows where you left off. It doesn't. The next answer is built on a partial picture, and you don't notice until the answer is wrong.
The naive fix is to write detailed handover notes between sessions. That doesn't work either — the notes drift, they get forgotten, and they describe state that the actual code already contradicts.
The decision
Don't trust chat history for state. Push every load-bearing piece of state into a markdown plan file:
- Every step is a checkbox:
[ ]not started,[x]done,[⏸]blocked. - Every completed step has a
Result:line capturing evidence — commit SHA, log line, screenshot reference, "verified" + date. - Every blocked step gets a dated comment: why blocked, when to revisit, who's blocking.
- Every scope change is a dated comment on the relevant row, not a silent edit.
Then enforce the invariant: a fresh session must be able to resume from the plan file alone. No secondary handover doc. No "remember to" messages to future-Claude. No state living in the chat that isn't also in the plan file.
If you find yourself wanting to write a handover note, that's a signal the plan file is missing a dated comment. Add it there instead.
Why this matters
The downstream effect is that resets become cheap. Long sessions degrade in quality before you notice. Once you trust the plan file, you can detect a clean phase boundary — decision committed, plan up to date, no uncommitted code — and start a fresh chat with zero context loss. The next session opens the plan file and picks up exactly where the last one left off.
This unlocks the bigger move: parallel sessions. If the plan file is the source of truth, multiple Claude sessions can collaborate on the same plan, each claiming rows, each writing evidence, each handing off via the file rather than via shared chat memory. That's the basis for team mode in co-op mode.
What this rejects
- "Remember to..." messages. The chat won't remember.
- Handover docs that summarize the plan file. Two sources of truth means neither is. Either the doc is redundant or the doc disagrees — both are bad.
- Long-running sessions with implicit state. If you've done 20 steps and the only record is the chat, you've already lost.
- Optimistic checkbox flips. Mark
[x]only with evidence. "I think this is done" doesn't count.
What I'd revisit
The plan-file format is currently markdown. That's portable and human-readable, but it's not enforceable — nothing stops a session from writing a malformed row. A schema-validated YAML format would be more rigorous, less inviting. The trade-off is friction: markdown is what people already write, so they'll actually do it. YAML costs adoption. Sticking with markdown.
The reset checkpoint is currently judgment-based ("does this feel like a clean boundary?"). It could be more programmatic — count tokens used, count files read, count steps done since last reset, fire when a threshold trips. Not building that yet because human judgment is good enough at N=1, but it's the obvious next move.