Context Compression

When to use

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 (same file read multiple times), contradictory instructions that accumulated over turns, constraint forgetting (earlier requirements no longer respected).

1. Draft summary — synthesize the current valid state of the code or plan in 3–5 sentences.

1. 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.

1. Generate handoff artifact — write the following template to disk:

   ## 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]

1. Restart — tell the user to start a new chat session and attach the handoff file as the first message.

Quality Probes

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 compression.
• Write the handoff document to disk before asking the user to restart.

Validation / Done Criteria

• 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.
• [ ] 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