/context-compression

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 (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).

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:

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