agentleFS
uzysjunguzysjung/uzys-agent-harness/.claude/skills/compaction-handoff/SKILL.md

compaction-handoff

Skill3 starsChanged 9 days agoMITView on GitHub

Create a compact, reconstructible checkpoint immediately before context compaction. Persist only durable facts and decisions, overwrite one current resume anchor, verify Git and open-PR state, and emit one concrete next action plus a short /compact line. Use for "컴팩션 준비해줘", "컴팩션하고 이어서 진행할 수 있게 준비해줘", "핸드오프 준비해줘", or "prepare for compaction", or equivalent. Repeated execution must be idempotent and must not grow state files without bound.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

37 rules. About 0 are common, 34 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈34

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Compact: only load-bearing information survives.

    line 35
  2. Distinctive:

    Run on explicit compaction or handoff requests, or proactively before automatic compaction while there is still enough context to write a …

    line 41
  3. Distinctive:

    Do not run after compaction without first reconstructing the best available state.

    line 44
  4. Distinctive:

    No raw logs, full file contents, or conversation replay.

    line 52
  5. Distinctive:

    Write atomically through a temporary file when practical.

    line 55
  6. Distinctive:

    Does it change what I do next time?: If not, don't write it. "We shipped X" changes nothing.

    line 67
  7. Very specific:

    Prefer updating an existing entry over adding a near-duplicate.

    line 81
  8. Distinctive:

    Size is a symptom, not the standard: Keep the index under 200 lines / 20 KB (unless the repository sets another limit), but being under it …

    line 85
  9. Distinctive:

    Create or update an ADR only for expensive-to-reverse decisions such as:

    line 94
  10. Distinctive:

    Do not create ADRs for branch status, task order, temporary workarounds, test failures, or today's remaining work.

    line 101
  11. Distinctive:

    When GitHub CLI is available:

    line 115
  12. Distinctive:

    Never assume a PR is merged.

    line 122
  13. Distinctive:

    When uncertain, preserve a concise reference rather than duplicated content.

    line 136
  14. Distinctive:

    Use existing files to update and prune.

    line 148
  15. Distinctive:

    remove completed transient state.

    line 167
  16. Distinctive:

    add only genuinely durable information.

    line 168
  17. Very specific:

    keep a pointer to .handoff/CURRENT.md.

    line 169
  18. Distinctive:

    search for an equivalent ADR.

    line 174
  19. Distinctive:

    update or supersede when possible.

    line 175
  20. Distinctive:

    create a new ADR only when necessary.

    line 176
  21. Distinctive:

    If there are no durable changes, leave these files unchanged.

    line 178
  22. Distinctive:

    use a temporary savepoint commit only as a last resort.

    line 187
  23. Distinctive:

    if no safe write action is authorized, leave the tree unchanged and record dirty files and risk.

    line 188
  24. Distinctive:

    Do not stage unrelated files.

    line 190
  25. Distinctive:

    no old anchor was appended.

    line 250
  26. Very specific:

    no transient state leaked into MEMORY.md.

    line 251
  27. Distinctive:

    no duplicate ADR was created.

    line 252
  28. Distinctive:

    If size limits are exceeded, prune.

    line 257
  29. Distinctive:

    After compaction, load only:

    line 279
  30. Distinctive:

    Do not auto-load archives, old summaries, raw logs, or the full prior conversation.

    line 288
  31. Distinctive:

    Every rerun must satisfy:

    line 293
  32. Distinctive:

    no new savepoint without material repository change.

    line 298
  33. Distinctive:

    If tools or repository access are unavailable:

    line 305
  34. Distinctive:

    do not fabricate Git, PR, CI, or test status.

    line 307
  35. Distinctive:

    create the best available anchor from known state.

    line 309
  36. Distinctive:

    do not claim an atomic checkpoint when repository state could not be inspected.

    line 311
  37. Distinctive:

    If durable files cannot be written, do not claim that compaction is safe.

    line 313

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Compaction Handoff Protocol

Context compaction is lossy. Create a deliberate checkpoint that lets the next session resume from verified state without replaying the full conversation.

This protocol is snapshot-based, not append-based:

  • MEMORY.md: durable facts and pointers only.
  • docs/decisions/: durable, load-bearing decisions only.
  • .handoff/CURRENT.md: current resumable state; overwrite on every handoff.
  • Git and PR state: authoritative implementation snapshot.
  • /compact line: short pointer to the anchor, not another summary.

Claude Code compacts on its own when the context fills up. This skill defines how to checkpoint before that happens — or before you compact by hand.

Goals

A valid handoff is:

  • Recoverable: the next session can start from one exact action.
  • Atomic: the anchor refers to one coherent repository state.
  • Evidence-based: verified results are distinct from claims and pending work.
  • Compact: only load-bearing information survives.
  • Idempotent: rerunning updates existing state instead of duplicating it.
  • Bounded: state files remain within fixed size limits.

Trigger

Run on explicit compaction or handoff requests, or proactively before automatic compaction while there is still enough context to write a clean checkpoint.

Do not run after compaction without first reconstructing the best available state.

State and retention rules

.handoff/CURRENT.md — transient resume SSOT

  • Single source of truth for current resumable state.
  • Overwrite; never append old anchors.
  • No raw logs, full file contents, or conversation replay.
  • Reference commits, PRs, tests, files, and ADRs instead of copying them.
  • Target: 120 lines / 12 KB maximum.
  • Write atomically through a temporary file when practical.
  • Historical archives are disabled by default. If explicitly required, keep them under .handoff/archive/, apply a retention limit, and never auto-load them on resume.

MEMORY.md — rules, not history

Memory is loaded every session, so every line is a standing cost. What earns that cost is principles, recurrence countermeasures, and facts you actually need to do the work — not a record of what was done.

Judge every entry — the ones you are adding AND the ones already there — with three questions:

  1. Does it change what I do next time? If not, don't write it. "We shipped X" changes nothing.
  2. Does it already live somewhere? Rules, the project's instruction files, ADRs, skills, and git history are each a source of truth. If the fact is there, that place owns it — do not keep a copy here. A duplicated fact is guaranteed to rot on one side, and you cannot tell which.
  3. Is it finished? Completed cycles, release logs, and version history belong to the changelog, ADRs, and git — not here.

What survives all three: operating principles · countermeasures for repeated mistakes · facts that cannot be derived from the repository (another tool's flags, limits, and policies; standing decisions such as "we accepted this risk, do not re-open it").

Re-judge the whole index at every handoff, not just the new lines. An index only ever grows unless something forces the question, and this is that moment.

Prefer updating an existing entry over adding a near-duplicate. To drop one, move the file to archive/ rather than deleting it — it leaves the index (so it stops loading) while staying recoverable.

Size is a symptom, not the standard. Keep the index under 200 lines / 20 KB (unless the repository sets another limit), but being under it is not evidence the index is healthy: a short index full of duplicates and finished history still fails all three questions. Measured case: an index at 67 lines / 20.7 KB passed the size rule while 48 of its entries were dead — completed cycle records and copies of facts already owned by rules and ADRs. Re-judged against the three questions, it came out at 23 lines / 6.0 KB.

docs/decisions/ — durable decisions only

Create or update an ADR only for expensive-to-reverse decisions such as:

  • architecture or major dependency choices;
  • API, data-model, compatibility, or migration contracts;
  • security trust boundaries and control ownership;
  • deployment topology, operational responsibility, or deliberate breaking changes.

Do not create ADRs for branch status, task order, temporary workarounds, test failures, or today's remaining work. Search existing ADRs first; update or supersede rather than duplicate.

Git and PR state — implementation authority

Inspect:

git status --short
git branch --show-current
git rev-parse --short HEAD
git log -1 --oneline

When GitHub CLI is available:

gh pr list --state open
gh pr status

Never assume a PR is merged. Surface open PR number, CI/review status, and mergeability when available. Never merge or modify a PR unless separately requested.

Preserve versus discard

PreserveDiscard
Current objective and processed/remaining boundaryFull conversation replay
Durable decisions via ADR referenceIntermediate reasoning already acted on
Unresolved blockers and exact impactRaw logs and repetitive tool output
Branch, commit, dirty state, open PRsRe-readable file contents
Test/build evidenceUnsupported "done" claims
One exact next actionBroad speculative future work

When uncertain, preserve a concise reference rather than duplicated content.

Workflow

1. Inspect existing state

test -f MEMORY.md && sed -n '1,240p' MEMORY.md
test -f .handoff/CURRENT.md && sed -n '1,180p' .handoff/CURRENT.md
find docs/decisions -maxdepth 1 -type f 2>/dev/null | sort

Use existing files to update and prune. Never blindly append.

2. Classify each item

Route each fact once:

  1. durable fact → MEMORY.md;
  2. durable decision with rationale → ADR;
  3. transient resumable state → .handoff/CURRENT.md;
  4. reconstructible or low-value detail → discard.

A fact should not exist in multiple places unless one location contains only a pointer.

3. Update durable state

For MEMORY.md:

  • merge duplicates;
  • replace superseded facts;
  • remove completed transient state;
  • add only genuinely durable information;
  • keep a pointer to .handoff/CURRENT.md.

For ADRs:

  • confirm the decision is durable;
  • search for an equivalent ADR;
  • update or supersede when possible;
  • create a new ADR only when necessary.

If there are no durable changes, leave these files unchanged.

4. Make Git state reconstructible

Preferred order:

  1. reuse the current meaningful commit if the tree is clean;
  2. make a normal semantic commit for a coherent completed unit when authorized;
  3. otherwise use a named stash when safe and authorized;
  4. use a temporary savepoint commit only as a last resort;
  5. if no safe write action is authorized, leave the tree unchanged and record dirty files and risk.

Do not stage unrelated files. Do not create another savepoint when state has not materially changed.

5. Overwrite .handoff/CURRENT.md

Use this structure:

# Compaction Resume Anchor

- Updated: <ISO-8601 timestamp with timezone>
- Repository: <name or path>
- Branch: <branch or n/a>
- Commit: <short SHA or n/a>
- Working tree: <clean | concise dirty-file summary>
- Open PRs: <none | concise status>

## Current state
<Active objective, completed work, and processed-vs-remaining boundary.>

## Verified
<Evidence only: command and exit status, reviewed diff, artifact, merged PR, or "not verified".>

## What's left
<Pending work, blockers, dirty or unpushed state, open PRs, and unresolved decisions.>

## Next action
<Exactly one executable next step, preferably naming the file, command, or decision target.>

## References
- <Only directly useful plan/spec/ADR/PR/file references>

Requirements:

  • Next action is mandatory and singular.
  • Verified must name evidence; assumptions are not passes.
  • What's left must expose relevant uncommitted, unpushed, unmerged, failed, or blocked state.
  • Keep references minimal.

Atomic write example:

mkdir -p .handoff
cat > .handoff/CURRENT.md.tmp <<'ANCHOR'
...
ANCHOR
mv .handoff/CURRENT.md.tmp .handoff/CURRENT.md

6. Validate

wc -l -c MEMORY.md .handoff/CURRENT.md 2>/dev/null
git status --short
git diff --check

Confirm:

  • anchor matches current branch and commit;
  • no old anchor was appended;
  • no transient state leaked into MEMORY.md;
  • no duplicate ADR was created;
  • open PR state is visible;
  • Verified is evidence-backed;
  • Next action is singular and executable.

If size limits are exceeded, prune. Do not create another summary file to hide the problem.

7. Report and suggest /compact

| Check | Result | Status |
|---|---|---|
| Durable memory | unchanged / updated and pruned | ✓ / ⚠ |
| ADRs | none / updated / created | ✓ / ⚠ |
| Git snapshot | branch, commit, clean/dirty | ✓ / ⚠ |
| Open PRs | none / concise status | ✓ / ⚠ |
| Resume anchor | overwritten and validated | ✓ / ⚠ |

Then give the four resume fields in concise form and one short pointer:

/compact Resume from .handoff/CURRENT.md; next: <single action>; <branch>@<sha>; <PR or dirty-state warning if material>

Resume protocol

After compaction, load only:

  1. repository instructions (CLAUDE.md or equivalent);
  2. MEMORY.md;
  3. .handoff/CURRENT.md;
  4. ADRs referenced by the anchor;
  5. current Git and open-PR state;
  6. source files required for the next action.

Do not auto-load archives, old summaries, raw logs, or the full prior conversation. If Git conflicts with the anchor, Git wins; report the discrepancy before continuing.

Idempotency checks

Every rerun must satisfy:

  • CURRENT.md replaced, not appended;
  • memory facts updated, not duplicated;
  • ADRs reused, updated, or superseded rather than cloned;
  • no new savepoint without material repository change;
  • one open PR represented once;
  • completed work removed from What's left;
  • file sizes remain stable.

Failure handling

If tools or repository access are unavailable:

  • do not fabricate Git, PR, CI, or test status;
  • mark unavailable evidence as not verified;
  • create the best available anchor from known state;
  • identify missing verification as a blocker or next action when material;
  • do not claim an atomic checkpoint when repository state could not be inspected.

If durable files cannot be written, do not claim that compaction is safe. Report the failure and emit a minimal manual resume anchor in the response.

Anti-patterns

  • Appending each handoff to MEMORY.md.
  • Keeping multiple active anchors.
  • Creating ADRs for routine task progress.
  • Copying complete logs into the anchor.
  • Loading all historical handoffs after compaction.
  • Creating a savepoint commit on every run.
  • Hiding dirty files, failed CI, unpushed commits, or open PRs.
  • Listing several possible next actions instead of one entry point.

Related skills

  • git-policy Session Cleanup — defines repository and PR cleanup expectations.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.