Planning File Hygiene

#How Drift Happens

Planning files accumulate lies over time. Not intentional lies — just the gap between what was planned and what actually happened.

A plan says “create X” but X was never created. STATE.md says “Phase 2 complete” but two requirements are unverified. ROADMAP.md says “Plans: TBD” but three plans exist. Each small drift makes future planning less reliable.

The compounding problem: GSD agents read planning files as ground truth. If STATE.md says you’re at Phase 3 when you’re actually at Phase 2, the planner writes Phase 3 plans with incorrect assumptions. Those plans execute against the wrong baseline and produce subtly broken results.

Drift is silent until it causes a failure. Prevention is cheaper than recovery.

#The Files That Matter Most

• STATE.md — the current truth about where you are. Must be updated after every plan execution. If it’s wrong, every agent that reads it starts from a false premise.
• ROADMAP.md — the phase plan. Requirements must be updated when completed. An unchecked requirement is an unverified assumption.
• SUMMARY.md (per plan) — the permanent record of what was built and why. Immutable once committed — don’t edit it after the fact.
• VERIFICATION.md — the gap between what was planned and what was built. This is the honest accounting. A gap in VERIFICATION.md is not a failure; it’s information.

#Keeping STATE.md Honest

Three rules that prevent most drift:

1. Update stopped_at and last_activity after every session. If you close the session without updating, the next session starts with stale context.
2. Mark phases complete only when verification passes. “I think it works” is not verification. Run the verify command.
3. Never mark a requirement complete without running /gsd:verify-work.

$ /gsd:verify-work N

/gsd:verify-work N checks all requirements for phase N against what was actually built. It produces a VERIFICATION.md with a gap analysis. Gaps don’t fail the build — they surface honest information about what needs follow-up.

#Preventing Drift

Practical habits that keep planning files honest:

• Run /gsd:resume-work at the start of every session — it re-reads STATE.md and alerts you to inconsistencies between what’s recorded and what’s on disk
• Never hand-edit SUMMARY.md files — they’re written by the executor, not you. Manual edits create contradictions between the file’s content and the git history.
• If you spot drift, fix STATE.md first, then re-run /gsd:verify-work to reconcile the rest of the planning files

The cost of letting drift accumulate is a planning session that produces bad plans. The cost of maintaining hygiene is a few extra minutes after each session. The math is obvious.