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

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:

# 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

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