1
# Context Compaction
2
3
## Compact on a threshold, not on an error
4
5
Trigger at `compact_at` percent of the window (default 70), or at a natural seam:
6
a subtask finished, a phase changed, a test suite went green. Compacting at 95% is
7
already too late, the degradation happened in the last 25%.
8
9
## What always survives
10
11
In priority order. If you can only keep one thing, keep the first.
12
13
1. **The goal**, in the user's own words. Not your paraphrase of it, which drifts.
14
2. **Decisions and their reasons.** "Chose Postgres over SQLite because the deploy
15
   target is multi-instance." A decision without its reason gets re-litigated.
16
3. **Constraints discovered the hard way.** The API that rate-limits at 10/s, the test
17
   that only passes with the flag, the file that must not be touched.
18
4. **Current state.** What is done, what is in progress, what is untouched.
19
5. **Open questions**, and what would answer each.
20
21
## What does not survive
22
23
- Full file contents. Keep the path and one line on what it does. Re-read on demand.
24
- Tool output you already extracted the answer from.
25
- Failed approaches, except one line naming the approach and why it failed. That line
26
  is what stops you trying it again.
27
- Your own reasoning. Keep conclusions.
28
- Anything you would not write down if a colleague were taking over.
29
30
## The test for a good checkpoint
31
32
Someone who has never seen the transcript reads only your checkpoint and continues
33
the work correctly. If they would have to ask a question you already know the answer
34
to, that answer belongs in the checkpoint.
35
36
Write it in `templates/checkpoint.md` format, to a real file. A checkpoint that lives
37
only in context does not survive the thing it exists to survive.
38
39
## Resuming
40
41
On resume, read the checkpoint before doing anything else, then verify the state it
42
claims rather than trusting it. Files change between sessions. Confirm the three or
43
four facts the next step depends on, cheaply, then continue.
44
45
If verification contradicts the checkpoint, the world wins. Note the discrepancy and
46
update the checkpoint before proceeding.
47
48
## What breaks and how to notice
49
50
- **Goal drift.** You are now solving a subproblem, well, that nobody asked for.
51
  Re-read the goal line at every compaction.
52
- **Decision amnesia.** You reconsider a settled choice. If the checkpoint had the
53
  reason, this does not happen.
54
- **Re-reading loops.** You read the same file for the third time. Its summary line
55
  was too thin. Fix the line, not the loop.
56