# Context Compaction

> Use when a long-running session accumulates exploration noise, dead ends, or verbose tool output and response quality is degrading -- guides when and how to compress context to stay in the smart zone

- Skill: `jsarif/context-compaction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jsarif/context-compaction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsarif/context-compaction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: JSarif (https://skillmd.com/u/jsarif)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jsarif/context-compaction

---


# Context Compaction

## Overview

Output quality depends on what's in the context window. First ~40% = **smart zone** (high signal). Last ~60% = **dumb zone** (noise-filled, degraded).

**Announce at start:** "I'm using the context-compaction skill to [compact/hand off/summarize]."

## When to Use

**Degradation symptoms (any = compact NOW):**
- Forgetting earlier constraints/decisions
- Repeating searches or file reads already done
- Referencing non-existent functions (confusing similar names)
- Proposing already-abandoned approaches
- Uncertain what you've modified vs. what remains

**Phase transitions (ALWAYS compact at these):**
- Research to planning
- Planning to implementation
- Implementation to review/testing

You MUST proactively flag degradation to the user. Do NOT power through. Compaction is not overhead; it keeps output quality high.

## Compact In Place vs. Start Fresh

```dot
digraph compact_decision {
    "Context noisy?" [shape=diamond];
    "Switching phases?" [shape=diamond];
    "Milestone handoff (fresh session)" [shape=box];
    "Anchored summarization (same session)" [shape=box];
    "Keep working" [shape=box];

    "Context noisy?" -> "Switching phases?" [label="yes"];
    "Context noisy?" -> "Keep working" [label="no symptoms"];
    "Switching phases?" -> "Milestone handoff (fresh session)" [label="yes"];
    "Switching phases?" -> "Anchored summarization (same session)" [label="no"];
}
```

## Technique 1: Anchored Iterative Summarization

For compacting **within** a session. Write summary using template below, present to user ("Here's my compacted context. Anything wrong?"), continue from the summary. **Only summarize the new span** since last compaction.

## Technique 2: Milestone-Based Handoff

For **phase transitions** (research to plan, plan to implement). End session, start fresh.

1. Write handoff artifact using template below
2. Save to file (e.g., `docs/handoff-YYYY-MM-DD-<topic>.md`)
3. Tell user: "I recommend starting a fresh session with this handoff document."

## The Compaction Template

For BOTH in-place and handoff. ALWAYS include Intent, Current State, Decisions Made, and What Failed:

```markdown
# Session Summary

## Intent
What we're trying to do and why (stays stable across compactions)

## Current State
- Milestone 1: COMPLETE
- Milestone 2: IN PROGRESS -- [specific status]

## Key Files
- `path/to/file.ts:34-78` -- what this section does

## Decisions Made
- Chose X because Y
- NOT doing Z because of constraint W

## What Failed
- Tried approach A -- failed because [reason]

## Next Steps
- [ ] Specific next action with file path
```

Use this template consistently. Do not invent a new structure each time.

## Quick Reference

| Signal | Action |
|---|---|
| Forgetting earlier decisions | Compact in place |
| Repeating searches/reads | Compact in place |
| Phase transition (e.g. research to plan) | Milestone handoff (fresh session) |
| 80%+ done but context degraded | Compact in place, then finish |
| Proposing already-abandoned approaches | STOP, compact immediately |

## Common Mistakes

**Pushing through because "almost done."** Dumb-zone output on the last task is most likely to be wrong. Compact first.

**"Compacting" by re-reading files.** Re-reading adds noise. Compaction CREATES a summary that REPLACES noise.

**Skipping phase-transition handoffs.** Research to planning is ALWAYS a handoff point. Start fresh.

**Regenerating the full summary.** Only compress the new span. Full rewrites compound drift.

## Integration

- **researching** -- produces compressed research docs (a form of handoff)
- **executing-plans** -- benefits from clean context via handoff
- **dispatching-parallel-agents** -- fresh context per sub-agent