Quick fixes AG-W005
The plan file stopped being true
Shared methods · A shared method; linked tool guides explain the exact steps.
This page covers tools outside your selection. You can still read it. Find matching guides
A written plan is only an asset while it matches reality. Code moves, the spec sits still, and an agent will happily follow the stale version.
My plan file no longer matches the code? Here's the quick fix ↓ — the why sits right below it.
Quick fix: The plan file stopped being true
Instead of Keep implementing against a PLAN.md written three sessions and two direction-changes ago.
Try At each work-block boundary: update the plan to what is now true, or delete it. A dated one-line changelog inside the file ("2026-09-06: dropped the queue, we poll now") costs seconds and keeps it alive.
Why this works
Putting the plan in a file is the highest-consensus habit in agent work, and it creates a second source of truth that only stays truthful with maintenance. The failure is quiet: you adjust course in conversation, the file keeps the old course, and the next session (or the next agent, or the next colleague) reads the file. An agent is the worst-hit reader, because it follows the stale spec diligently. The entire spec-driven tooling wave hit this wall — drift became the top complaint, and reconciliation commands were bolted on in response. Tooling can compare; only you can decide which side is right.
When this applies
The plan file's last edit predates a decision you remember making, or an agent just did something correct-per-the-file that you know is wrong.
Template
End-of-block ritual, thirty seconds:
Read PLAN.md against what we actually did. Update anything now false, date the change, and list what remains genuinely open. If the plan is finished or abandoned, say so — I'll delete it.
Go deeper
The plan-file workflow this protects: plan first and large refactors, where the plan outlives many sessions and drift costs the most. The same maintenance rule applies to CLAUDE.md: every stale line misleads every future session, which is why "delete lines that stop being true" is in the file-keeping discipline itself.
Improve next
- The agent passed the check by changing the check
Green checks only count if the checks themselves went unedited.
- Stop re-explaining your project
Consider keeping reusable project context.
Something wrong with this page?
Say what you expected and what you got. That is usually the shortest route to a correction, and it goes on the public issue tracker so the fix is visible.