| 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:
- 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.
- 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.
- 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:
git status --short
git add -A && git commit -m "chore: savepoint before compaction handoff"
gh pr list --state open
git branch --show-current
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
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.
