{"slug":"claude-compaction-restore","title":"claude-compaction-restore","summary":"Use when a Claude Code session has just compacted, is about to compact, reached context limit, resumed after /compact, or needs to rebuild its working mental model from Claude JSONL transcripts and touched files.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-31T16:20:53.619167Z","repo":{"url":"https://github.com/mvschwarz/openrig","stars":371,"forks":51,"license":"Apache-2.0","updatedAt":"2026-09-25T04:59:18Z"},"bodyHtml":"
\n

name: claude-compaction-restore\ndescription: Use when a Claude Code session has just compacted, is about to compact, reached context limit, resumed after /compact, or needs to rebuild its working mental model from Claude JSONL transcripts and touched files.\nmetadata:\nopenrig:\nstage: factory-approved\nsibling_skills:\n- mental-model-ha\n- scope-recovery\n- session-compaction-and-restore\n- agent-startup-and-context-ingestion\n- agent-starters\n- composable-priming-packs\n- session-source-fork\n- seat-continuity-and-handover\n- claude-compact-in-place\n- pre-maintenance-agent-preservation

\n

Claude Compaction Restore

\n

Use this skill to preserve continuity before Claude Code compacts and to\nrestore continuity after compaction. Do the work described here; do not merely\nexplain the protocol.

\n

If You Are About To Compact

\n

Prepare durable continuity before the context boundary.

\n
    \n
  1. Identify the active task, queue item, mission/slice, branch or commit, and\ncurrent working directory.
    2. \n
  2. Record the current state: decisions made, files changed, commands/tests run,\nevidence produced, blockers, caveats, and the next concrete step.
    3. \n
  3. Create or update a durable mental-model restore map. This map is the main\nartifact future-you will use to rebuild context after compaction.
    4. \n
  4. In the restore map, write an ASCII file/folder tree of every path that\nmattered to your working mental model during this session. Include:\n\n
    5. \n
  5. For every file or folder in the tree, add a short note explaining why it\nmatters and whether it is required reading after compaction.
    6. \n
  6. Write any important glue context that is not already on disk into the\nhandoff/restore map. This includes assumptions, partial conclusions, failed\npaths, and why the listed files fit together.
    7. \n
  7. In the compaction summary, include the restore map path and the top required\nreading paths from that map.
    8. \n
\n

If You Just Compacted

\n

Treat your memory as unreliable until you restore from durable evidence.\nRestoration is your current task. Do not wait for a future user request or a\nnew task assignment before reading the required files.

\n
    \n
  1. Read any restore prompt, marker path, packet path, transcript path, restore\nmap, or extra instruction file named by the operator or OpenRig.
    2. \n
  2. Run the restore script from this skill:
    3. \n
\n
node ~/.claude/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs --out /tmp/claude-compaction-restore\n
\n

If the prompt names a specific Claude JSONL transcript, pass it explicitly:

\n
node ~/.claude/skills/claude-compaction-restore/scripts/restore-from-jsonl.mjs /path/to/session.jsonl --out /tmp/claude-compaction-restore\n
\n
    \n
  1. Read the generated restore-instructions.md.
    2. \n
  2. Read the generated touched-files.md.
    3. \n
  3. Find and read the mental-model restore map if one exists. Treat it as the\nhighest-value guide to which memory files, mission files, source files, and\ndocs mattered before compaction.
    4. \n
  4. Identify the important files for the active task. The touched-file list is\na triage aid, not a complete inventory.
    5. \n
  5. Read every important file in full. Prioritize the restore map, Claude memory\nfiles named in the map, Markdown state/planning files, queue/mission packets,\nsource files with active edits, root instruction files, and as-built or\ncodemap docs.
    6. \n
  6. After the required reads are complete, state:
    7. \n
\n
restored from packet at <path>; resumed at step <X>\n
\n

Include the main files you read in full when you make that statement.

\n
    \n

  1. REFOCUS BEFORE YOU RESUME — the restore returns your TASK, not your BEARINGS. Everything\nabove rebuilds what you were doing. None of it rebuilds what the work is for or how this\nrig operates — those live in the chains, and nothing in steps 1–8 walks them. Invoke the\nrefocus skill and do its reads before your next substantive move.

    \n

    Measured 2026-08-13, and this step exists because of it: a seat completed this protocol\nfaithfully — packet built, narrative read tail-first, read-depth audit reported honestly — and\nresumed with a perfect picture of its atom and zero work-tree context. It had never opened\nthe mission or project nodes, and could only paraphrase the release's intent second-hand from\na peer's message. It then produced a technically-correct trace concluding \"I hold nothing\"\nwhile holding 18 pending rows. A restore that returns you to your task without your bearings\nis how a confidently-wrong agent gets back to work.

    \n
    2. \n
\n

On the marker and the packet's size (measured across restores, 2026-08): two realities the restore\nmust handle honestly —

\n\n

Required Read-Depth Audit

\n

After the first restore pass, audit yourself before continuing.

\n
    \n
  1. List every file, packet, marker, restore map, instruction file, and source\ndocument you were asked to read during restore.
    2. \n
  2. Mark each item as FULL, PARTIAL, or NOT_READ.
    3. \n
  3. You will be given a task where all of these files are required reading in\norder to understand the task.
    4. \n
  4. Read PARTIAL/NOT_READ items in full — but to a declared budget with a stopping rule, not\nunbounded. Prioritize by relevance to the active task; for a large transcript read the most recent\nunique narrative first (see If You Just Compacted), not front-to-back.
    5. \n
  5. Stop when either every task-relevant item is FULL, or you reach the budget — a restore that\ncannot leave room for the work it was restored to do is not a successful restore. \"Read everything,\nnever conserve\" has no termination condition; that open-endedness is the bug, not the goal.
    6. \n
  6. Report the final read-depth table honestly (FULL/PARTIAL/NOT_READ, each with a reason)\nbefore task work. An honest PARTIAL with its reason is a correct outcome, not a failure — do\nnot claim a completion you did not reach.
    7. \n
\n

Guardrails

\n\n

Failure Modes To Avoid

\n
    \n
  1. Confidently-wrong restoration: claiming restoration after reading only\nthe touched-file list or summary.
    2. \n
  2. Partial restore: reading the first few files, then continuing before the\nfull reading list is complete.
    3. \n
  3. Skipping project instructions: missing AGENTS.md, CLAUDE.md,\nREADME.md, as-built docs, or codemaps that govern the task.
    4. \n
  4. Treating the packet as exhaustive: ignoring mission or workspace files\nthat are important but were not discovered by the script.
    5. \n
  5. Waiting for the next task: treating restore reading as conditional on a\nfuture user assignment instead of completing it immediately.
    6. \n
\n","files":[{"path":"scripts/precompact-hook.mjs","sizeBytes":12428,"isText":false},{"path":"scripts/restore-from-jsonl.mjs","sizeBytes":20308,"isText":false},{"path":"SKILL.md","sizeBytes":8980,"isText":true},{"path":"templates/compact-instruction.md","sizeBytes":191,"isText":true},{"path":"templates/post-compact-restore-instruction.md","sizeBytes":90,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-12T07:22:00.702465Z","sha256":"720E9AFEA2E7F60CE1CEE01B8195DF56B9AF061221FCE053ED0BC970535F116F","sizeBytes":15560},"review":null,"source":{"repositoryUrl":"https://github.com/mvschwarz/openrig","path":"packages/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore","license":"Apache-2.0","commit":"b374dde300fd2a3cf1ee139b89b11e2fa3945784","subtreeSha":"957AD9603A4DC148FC64B098245C9632414A764402F7C150A8BFD2E4B19A4CD8","lastSyncedAt":"2026-09-25T06:48:47.236757Z"},"reviewedAt":"2026-09-12T07:23:12.586851Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/mvschwarz/openrig/tree/main/packages/daemon/assets/plugins/openrig-core/skills/claude-compaction-restore"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mvschwarz-openrig@llmmart"},{"target":"git","command":"git clone https://github.com/mvschwarz/openrig.git"}]}