name: strategic-context-compaction
description: Use when deciding whether to compact agent context -- the window is filling up, you are about to switch from one phase to another (research, planning, implementation, debugging), a failed approach left dead-end reasoning, or a previous mid-task compaction lost critical state.
Purpose
Compact at logical boundaries to preserve high-value context while clearing noise. Arbitrary or mid-task compaction loses critical state -- file paths, variable names, partial reasoning -- that is expensive to reconstruct.
When to Use
- The context window is filling and you are at a phase boundary (research, planning, implementation, debugging)
- A failed approach left dead-end reasoning that pollutes the next attempt
- You are starting a conceptually distinct task in the same session
- A prior mid-task compaction dropped state you then had to rebuild
- The current session state and which phase transition is approaching
- Knowledge of what is already saved durably (task list, files, git, memory) versus only in conversation
Workflow
- Decide whether to compact by transition. Use the boundary table; default to NOT compacting mid-work.
| Transition | Compact? | Reason |
|---|
| Research -- Planning | Yes | Research context is bulky; the plan is the distilled output |
| Planning -- Implementation | Yes | Plan is saved in tasks/files; context is free to reset |
| Implementation -- Testing | Maybe | Keep if tests reference recent code; compact if switching focus area |
| Debugging -- Next feature | Yes | Debug traces pollute unrelated work |
| Mid-implementation | No | Losing file paths, variable names, partial state is costly |
| After a failed approach | Yes | Clear dead-end reasoning before trying a new approach |
- Save anything you cannot reconstruct cheaply before compacting.
- Write the plan to a task list or file before compacting after research
- Commit or stash work-in-progress code before compacting after debugging
- Note key file paths in the next prompt if they will be needed again
- Know what survives versus what is lost. Anything in the Lost column must be persisted in step 2 first.
| Survives | Lost |
|---|
| CLAUDE.md / AGENTS.md instructions | Intermediate reasoning |
| Task list (TodoWrite) | File contents read in session |
| Files on disk | Tool call history |
| Git state | Verbally stated preferences |
| Memory files | Multi-step conversation context |
- Compact with an intent-carrying summary prompt, then restore.
- Do not compact to "clean up" during active multi-file implementation
- Pass forward intent, e.g.
/compact -- now implementing auth middleware per plan - After compaction, re-read the task list or plan file to restore intent
Output
- A compaction decision (do it now / wait until the next boundary) with the reason
- A pre-compaction save of any non-reconstructible state (plan file, commit/stash, noted paths)
- A summary prompt that carries intent into the cleared context
Token Awareness
- Each loaded skill adds 1-5K tokens to context; load skills on demand, not at session start
- CLAUDE.md / AGENTS.md are always loaded -- keep them lean
- Duplicate instructions (root config plus plugin skill) are the most common waste
Verification
- [ ] The chosen action matches the transition table -- no compaction during active multi-file implementation
- [ ] Everything in the Lost column that is still needed was persisted (file, commit/stash, or next prompt) before compacting
- [ ] The compact prompt carries forward intent rather than clearing blindly
- [ ] After compaction, the task list or plan file was re-read to restore intent
Failure Modes
- Mid-task compaction — compacting during active multi-file work and losing paths, variable names, and partial state that must then be rebuilt.
- Compacting before saving — clearing context while the plan, WIP code, or key paths live only in conversation and not on disk or in tasks.
- Blind compaction — using
/compact with no intent summary, so the cleared session has no direction and re-derives the goal. - Skipping the restore step — not re-reading the task list or plan after compaction, then drifting from the original intent.