Context Compression

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:

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

```

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yeaight7
• Source: yeaight7/agent-powerups
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.