Compaction Handoff

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.

1. 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.

1. 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                 # 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 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: uzysjung
• Source: uzysjung/uzys-agent-harness
• License: MIT
• Homepage: https://uzysjung.github.io/uzys-agent-harness/

Install and usage instructions live in the source repository linked above.