Context Hygiene for Long Sessions

Context is lossy: it gets compacted, summarized, and eventually dropped. Files are not. The single most effective habit for long tasks is treating the context window as a working cache and the filesystem as the source of truth. Everything else here follows from that.

1. Keep a state file

For any multi-phase task, maintain one markdown file (in the scratchpad directory, or the repo if the user wants it tracked) with:

• Goal — the user's actual request, quoted or closely paraphrased
• Decisions made, with the why — one line each
• Current step and what "done" looks like for it
• Next steps — concrete enough that a cold reader could continue
• Open questions / surprises — anything learned that contradicted expectations
• Key anchors — important file:line locations so they needn't be re-found

Update it at phase boundaries, before risky operations, and whenever something surprising happens. Thirty seconds of writing buys immunity to compaction.

2. Decisions outlive transcripts

Record why choices were made, not just what happened. "Chose polling over websockets — the server doesn't support push and the user wants zero new dependencies" is one line, and it prevents the two classic failures of a future context: silently contradicting the decision, or burning twenty minutes re-deriving it.

3. The plot-loss failure mode

After compaction, the danger is not amnesia — it's confident continuation of a subtly wrong version of the task. Summaries compress away nuance: the constraint mentioned once, the approach that was explicitly rejected, the exact scope boundary. So after any compaction or when resuming a session:

1. Re-read the state file.
2. Re-read the user's original request if available.
3. Reconcile: does what you're about to do still match both? Only then act.

If there is no state file after compaction, treat every recalled specific — paths, symbol names, decisions — as unverified until checked against the repo.

4. Don't hold what you can re-derive

Reading a 3000-line file into context to use 40 lines of it is how windows die early. Read the ranges you need; note the anchor (file:line) in the state file instead of keeping the text in your head. Prefer search over full-file reads, and delegate broad sweeps to subagents so the dumps land in their context, not yours.

5. Checkpoint at green states

Whenever the work reaches a verified-good state — tests pass, the feature demonstrably works — make it recoverable. If the user has authorized commits, commit with a clear message. If not, note the green state in the state file ("all tests green as of step 3, before starting the refactor") and consider git stash or a WIP branch if allowed. A known-good point converts later disasters from archaeology into a reset. Hours of uncommitted, unrecorded work is an outage waiting for a crash.

6. Trust degrades with distance

The further back something was established, the less you should trust your memory of it. Beliefs formed early in a long session — "this file exports X", "the tests live in Y" — deserve re-verification before you edit based on them. The repo moved; your memory didn't.