strategic-context-compaction · diff
git:20260503.fc9231f to git:20260606.c168b1f
63 added, 34 removed. Audit A to A.
---
name: strategic-context-compaction
- description: Compact context at logical phase boundaries — after research, after planning, after debugging — rather than mid-task. Preserves useful state while clearing noise.
+ 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.
---
- # Strategic Context Compaction
+ ## Purpose
- Compact at logical boundaries to preserve high-value context while clearing noise. Arbitrary or mid-task compaction loses critical state.
+ 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 Compact
+ ## When to Use
- | 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 |
+ - 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
- ## Before Compacting
+ ## Inputs
- Save anything you cannot reconstruct cheaply:
- - 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
+ - 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
- ## What Survives Compaction
+ ## Workflow
- | 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 |
+ 1. **Decide whether to compact by transition.** Use the boundary table; default to NOT compacting mid-work.
- ## Compaction Discipline
+ | 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 |
- - Do not compact to "clean up" during active multi-file implementation
- - Do compact when starting a conceptually distinct task in the same session
- - Use a summary prompt with `/compact`: `/compact — now implementing auth middleware per plan`
- - After compaction, re-read the task list or plan file to restore intent
+ 2. **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
+ 3. **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 |
+
+ 4. **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 + plugin skill) are the most common waste
+ - 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.