compaction-handoff · git:20260621.b3fcda3 · 2026-06-21 · sha256 1b19203ae45869dd
compaction-handoff git:20260621.b3fcda3A
Immutable. This exact content never changes and is served at /api/v1/blob/1b19203ae45869dd.
--- name: compaction-handoff description: >- Execute a structured handoff right before a context compaction so no state is lost — persist durable facts to memory, take an atomic git snapshot (clean tree + open-PR check), and emit a fixed-field resume anchor (current state / verified / what's left / next action) plus a suggested custom /compact summary line. Use when the user says "컴팩션 준비해줘", "컴팩션하고 이어서 진행할 수 있게 준비해줘", "핸드오프 준비해줘", or in English "prepare for compaction", "get ready to compact and continue", "hand off before /compact", "checkpoint before compacting". Also fire proactively when context is nearing the window limit and an auto-compact is imminent. --- # Compaction Handoff Protocol A context window is about to be summarized and reinitialized. The model is stateless, so **only what you write out survives** — the new window starts from a lossy summary, not the live history. This skill runs the handoff deliberately so the resumed session can pick up without re-deriving lost state. > Sibling skill `strategic-compact` decides **WHEN** to compact (phase boundaries, token pressure). > This skill is the **HOW**: it executes the handoff at that moment. Run `strategic-compact`'s > decision first if you're unsure whether to compact at all; run this when the answer is "yes". ## When to use The user works in Korean and triggers this repeatedly. Treat any of these as a fire signal: - **"컴팩션 준비해줘"** / **"컴팩션하고 이어서 진행할 수 있게 준비해줘"** / **"핸드오프 준비해줘"** - English equivalents: "prepare for compaction", "get ready to compact and continue", "hand off". - **Proactively, before the cliff.** Don't wait for auto-compact at 100%. Auto-compaction fires near the window limit; a common practice is to trigger the handoff earlier (around ~80% of the window) so there's still budget to write a clean anchor — a rushed handoff at the cliff is exactly where load-bearing context gets dropped. Why proactive matters: auto-compact optimizes for *generic* continuity, not for THIS task's load-bearing facts (an open PR, a chosen-but-unwritten decision). If you skip the handoff because the task "looks finished," you risk silent information loss — the resumed agent assumes work shipped that did not. ## The model: three legs of a checkpoint Treat the handoff as a deliberate checkpoint, not a passive summary. Three legs, each grounded in an established practice: 1. **Persist durable facts to external memory** *(before compacting, never after)*. The window will be wiped; structured note-taking exists precisely because the summary alone can't be trusted to carry everything. Route load-bearing *decisions* to ADRs (`docs/decisions/`) so the *why* survives every future compaction, not just this one. 2. **Take an atomic, reconstructible snapshot** — git clean (or a `savepoint` commit) plus an **open-PR check**. A dirty/half-committed tree is a corrupt checkpoint; an open PR is itself critical state that belongs in "what's left." This is the Checkpoint **Atomicity** and **State Completeness** principles applied to the working tree. 3. **Emit a fixed-field resume anchor** — current state / verified / what's left / next action — framed *working backwards* from the next concrete step so a freshly-compacted agent re-orients instantly instead of replaying history forward. ### Preserve-list, not a prose blob Use an explicit preserve-list rather than a free-form paragraph (Anthropic's stated preserve/discard split): | Preserve (high-value) | Discard (low-value) | |---|---| | Architectural decisions + their *why* (link ADR) | Redundant tool outputs, raw logs | | Unresolved bugs / blockers | Intermediate reasoning already acted on | | Processed-vs-remaining boundary | File contents you can re-read from disk | | Open PRs / unpushed branches | Tool-call counts and history | | Verified-vs-merely-claimed evidence | Restated CLAUDE.md / rules (already loaded) | ## Workflow Run these in order. Each writes durable state *before* the window is touched. **1. Memory — persist durable facts.** Update the auto-memory (`MEMORY.md`) and any session-summary entry with the preserve-list items. For a load-bearing decision (architecture, dependency, data model, breaking change), write or update an ADR in `docs/decisions/` — this is the one place "the why behind the constraint" survives lossy compaction. Don't rely on the `/compact` summary to carry a decision; it strips provenance. **2. Git — atomic snapshot + open-PR check.** Make the working tree reflect a consistent state. The `gh pr list` step is **not optional** — it is the git-policy **Session Cleanup** gate, which is mandatory before any `/clear` or `/compact`. Run it every handoff: ```bash git status --short # is the tree clean? # IF tree is dirty AND the work is worth keeping: git add -A && git commit -m "chore: savepoint before compaction handoff" gh pr list --state open # list open PRs — each open PR is what's-left state to surface, not necessarily an anomaly git branch --show-current # note unpushed branch state ``` This folds the git-policy **Session Cleanup** gate into the handoff. An open PR is not a loose end to hide — surface it in the anchor's "what's left" with its number, CI status, and mergeability, and let the user decide (no auto-merge). **3. Resume anchor — four fixed fields.** Emit the anchor. Keep "verified" distinct from "done": *done* is a claim, *verified* encodes the evidence (test PASS output, exit 0, a merged PR). The resumed agent re-trusts only what's verified. Make **next action** mandatory and singular — it's the entry point the resumed session executes first, so the anchor is self-serve (Recovery Automation), not a note to re-interpret. **4. Suggested /compact line.** Hand the user a one-line custom summary to pass to `/compact` (e.g. `/compact Resume: finish ADR-022 flag removal; PR #160 merged, branches drift test failing`). This is a pointer to the durable anchor, not a replacement for it. ## Handoff report format Present a compact status table, then the anchor: ``` | Check | Result | Status | |----------------|-----------------------------------------|--------| | Memory | MEMORY.md + ADR-022 updated | ✓ | | Git | tree clean, savepoint a1b2c3d | ✓ | | Open PRs | gh pr list → 0 open | ✓ | | Files | resume anchor written, plan SSOT synced | ✓ | ``` ## Worked example **Input** (user, at ~78% context): > 컴팩션하고 이어서 진행할 수 있게 준비해줘 **Output:** Handoff checks: | Check | Result | Status | |----------|-------------------------------------------------|--------| | Memory | MEMORY.md code-quality-cycle entry refreshed | ✓ | | Git | tree clean (no savepoint needed) | ✓ | | Open PRs | `gh pr list` → **1 open: #165** CI pass, mergeable | ⚠ surfaced | | Files | resume anchor below; persona-feedback SSOT synced | ✓ | **Resume anchor** - **Current state:** Persona P0 fixes in progress on branch `fix/persona-p0`. 2 of 4 fixes landed. - **Verified:** `npm run ci` exit 0 on current HEAD (typecheck + lint + coverage branches 88.4% + build). Docker scenario for `--with <id>` exit 0. - **What's left:** Fixes 3 & 4 (wizard copy + COMPATIBILITY honesty). **Open PR #165 is not merged** — publishing is blocked until P0 complete (per persona-feedback-improvements.md). Branch `fix/persona-p0` unpushed for the last 2 commits. - **Next action:** Implement fix 3 (wizard understanding-category copy), then re-run `npm run ci`. **Suggested /compact line:** `/compact Resume fix/persona-p0: do fix 3 (wizard copy) next, then ci; PR #165 open & blocks publish until all 4 P0 done` Notice what the anchor does deliberately: it leads with the **next action** (working-backwards), keeps the open PR visible in "what's left" instead of assuming it shipped, and separates the *verified* CI evidence from the *unverified* remaining fixes. ## Pitfalls this guards against - **Lossy summary-stripping** — a headline-only handoff looks complete but is unrecoverable because the evidence and reasoning chains are gone. Fix: preserve-list + ADR provenance, not a prose blob. - **Lost-in-the-Middle over-stuffing** — dumping full history into the new window doesn't help; buried facts follow a U-shaped accuracy curve. The anchor stays short and structured. - **Telephone-game decay** — fidelity erodes across successive compactions. Routing load-bearing facts to stable memory/ADRs breaks the degradation chain a chain of summaries can't. - **Non-atomic snapshot** — handing off with a half-committed tree reconstructs an inconsistent state. The git leg forces a clean or savepoint-committed tree. - **Incomplete state save** — omitting the processed-vs-remaining boundary forces duplicate work or silent re-execution of irreversible actions. The "what's left" field is mandatory. ## References - Anthropic — *Effective context engineering for AI agents* (Compaction; Structured Note-Taking / Agentic Memory): https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents - Hendricks.ai — Checkpoint patterns (State Completeness, Atomicity, Recovery Automation): https://hendricks.ai/insights/checkpoint-patterns-long-running-ai-agent-tasks - XTrace — AI agent context handoff (Decisions / Artifacts / Preferences / Timeline; decision provenance): https://xtrace.ai/blog/ai-agent-context-handoff - Architectural Decision Records (ADR) — append-only single-decision records; route load-bearing decisions here so the *why* survives compaction. - Amazon *Working Backwards* — lead the anchor with the end state and the single next action. ## Related skills - **strategic-compact** — decides WHEN to compact (phase boundaries, token pressure). Pair with it: it answers "compact now?", this skill executes the handoff when the answer is yes. - **git-policy Session Cleanup** — the open-PR check (leg 2) is the same gate; this skill folds it into the pre-compaction moment.