context-compression · diff
git:20260505.8e360ce to git:20260515.27306a3
48 added, 17 removed. Audit A to A.
---
name: context-compression
description: Use when conversation context is bloated, constraints are being forgotten, or a compact handoff is needed before continuing work.
---
# Context Compression
## When to use
- Use when context approaches limits or response quality degrades (due to the "lost in the middle" effect), typically after many turns of debugging or complex planning.
+ Use when context approaches limits or response quality degrades (repeated mistakes, forgotten constraints, lost-in-the-middle effects) — typically after many turns of debugging or complex planning.
## Requirements / Checks
- Active session contains long stack traces, large file dumps, or multiple failed iterations.
## Workflow
- 1. **Diagnose Bloat**: Identify redundant outputs, contradictory instructions (clash), and "lost-in-middle" constraint forgetting.
- 2. **Draft Summary**: Synthesize the *current* valid state of the code/plan.
- 3. **Extract Anti-patterns**: Note what failed and why (e.g., "Attempted X, failed due to Y").
- 4. **Generate Handoff**: Write a concise handoff artifact containing the goal, current state, anti-patterns, and exact next step.
- 5. **Restart**: Instruct the user to start a new chat session and attach the handoff artifact to continue.
+ 1. **Diagnose bloat** — identify: redundant outputs (same file read multiple times), contradictory instructions that accumulated over turns, constraint forgetting (earlier requirements no longer respected).
+
+ 2. **Draft summary** — synthesize the *current* valid state of the code or plan in 3–5 sentences.
+
+ 3. **Extract anti-patterns** — list what failed and why: `"Attempted X → failed because Y"`. These are critical to prevent the next session from looping on the same mistakes.
+
+ 4. **Generate handoff artifact** — write the following template to disk:
+
+ ```markdown
+ ## Goal
+ [One-sentence objective]
+
+ ## Current state
+ [What is working / what is in place right now]
+
+ ## Blocker / next step
+ [The exact next action to take]
+
+ ## Anti-patterns (do not repeat)
+ - Tried X → failed because Y
+ - Tried A → blocked by B
+
+ ## Key files
+ - `path/to/file.ts` — [what it does / why it matters]
+
+ ## Open risks
+ - [Anything uncertain or requiring verification]
+
+ ## Decisions made
+ - [Key tradeoffs and why alternatives were rejected]
+ ```
+
+ 5. **Restart** — tell the user to start a new chat session and attach the handoff file as the first message.
+
## Quality Probes
- Before trusting a compression, check it can answer:
- - Recall: exact commands, errors, versions, and decisions that still matter.
- - Artifact: files created, modified, inspected, and intentionally untouched.
- - Continuation: next action, current blocker, validation state, and open risks.
- - Decision: why key tradeoffs were chosen and what alternatives were rejected.
+ Before finalizing, verify the handoff can answer:
+ - **Recall**: exact commands, errors, versions, decisions that still matter.
+ - **Artifact**: files created, modified, inspected, intentionally untouched.
+ - **Continuation**: next action, current blocker, validation state, open risks.
+ - **Decision**: why key tradeoffs were chosen and what alternatives were rejected.
+
## Safety Constraints
- - Do NOT silently drop critical architectural constraints or user preferences during compaction.
- - Ensure the handoff document is written to disk before asking the user to restart.
+ - Do NOT silently drop critical architectural constraints or user preferences during compression.
+ - Write the handoff document to disk before asking the user to restart.
## Validation / Done Criteria
- - Handoff artifact is created and contains the necessary state to resume work immediately.
- - The user is explicitly told to restart the session.
- - Quality probes above can be answered from the compacted context without re-reading the full transcript.
+ - Handoff artifact exists on disk and is in the template format above.
+ - User is explicitly told to restart the session and attach the file.
+ - All four quality probes (recall, artifact, continuation, decision) can be answered from the artifact without re-reading the full transcript.
## Anti-loss Checklist
- [ ] Goal is clearly stated.
- - [ ] Current blocker/next step is identified.
+ - [ ] Current blocker / next step is identified.
- [ ] Failed approaches are documented to prevent looping.
- [ ] Relevant file paths are listed.
+ - [ ] Key decisions and their reasons are recorded.
## References
- `references/compression-quality-probes.md`