Loading
Use when a Claude Code session is about to compact, has just compacted, reached its context limit, resumed after /compact, or must rebuild its working picture of a long-running seat from its own resto
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add mvschwarz/openrig --skill claude-compaction-restore -a cursor -y
Use when a Claude Code session is about to compact, has just compacted, reached its context limit, resumed after /compact, or must rebuild its working picture of a long-running seat from its own restore map, its JSONL transcript and the files it touched.
Use when a Claude Code session is about to compact, has just compacted, reached its context limit, resumed after /compact, or must rebuild its working picture of a long-running seat from its own restore map, its JSONL transcript and the files it touched.
Compaction keeps facts and loses connections. After a compaction you still know file names, row ids and decisions as items. What you lose is the web between them: why a file matters, what depends on what, which decision produced which artifact, what you were about to do next, and how this window relates to the ones before it. Seats whose value is a wide, long-running picture (planners, orchestrators, reviewers holding a standard) lose the most.
This skill keeps that picture alive across compactions. Before compacting, you write a restore map: a short summary plus the connections between things that already exist on disk. After compacting, you re-enter the world, read your own map, and rebuild the picture before acting. Over several compactions the maps chain into one continuous record: a global context window that outlives any single session.
The previous version of this skill is kept at reference/SKILL-v1.md for comparison.
Already on disk; point to it, don't copy it:
~/.claude/projects/<cwd-slug>/<session-uuid>.jsonl (the post-compaction restore
request names the exact path). It holds every message and tool call you made, in order. It does not hold
your reasoning;SPEC.md, NOTES.md, PROGRESS.md), your seat's
LEARNED.md, evidence folders, branches and PRs.Only in your head; write it down:
The map is the second list, pinned to the first.
Every restored seat must come back competent. It should understand the OpenRig world and its command surface, the project, its own role, and where it stands in time. Some seats also need the global picture.
Both classes read the same thing: the ranked reading list in your own map, in order. They differ only in how far down the list they go.
| Class | Who | Reads |
|---|---|---|
| Default | drivers, builders, reviewers, QA, and any seat not listed below | Tier 1: the top of the list, to about 100k of real context |
| High-context | orchestrators, planners, advisors, leads: any seat that makes product, scope or routing decisions | Tier 1 and Tier 2, to about 200k of real context |
The tiers are real context added by the restore, on top of what the compaction summary leaves (about 60k).
These budgets assume a context window of about 1M tokens; on a smaller window, scale them to about 10% and
20% of it. File size is a poor guide to that cost: in OpenRig's own runs, real context grew 1.7 to 2 times the bytes ÷ 4 estimate,
because of line numbers on reads, tool output and your own reasoning. So rank to about 50k of bytes ÷ 4 for
Tier 1 and about 100k for Tier 2, and check real usage at each checkpoint with
rig compact-plan --json (your seat's estimatedUsedTokens).
Tier 2 buys width, not depth: more sources, more connections, more of the mission's history and the wider
worlds, not the same files read more fully. Choose your class from your role (rig whoami --json). A per-seat
instruction file or your own map can name the class explicitly, and that overrides the role default. In both
classes, transcripts and the session JSONL appear only as targeted line ranges, never as whole files.
If there is no ranked list (no preparation turn happened), use this default order. Default seats stop at about 100k of real context:
SPEC.md and NOTES.md;High-context seats then add, to about 200k:
PROGRESS.md and recent returns;RESTORED notes;LEARNED.md.You are about to lose every connection you have built. Spend this turn making them durable.
.tmp file,
with the exact completion marker as its last line, then finish and close it. The daemon publishes
the completed map atomically; do not run a shell rename or write the final file incrementally.
Do not substitute the seat folder or another map. Managed preparation normally publishes
<launch cwd>/.openrig/compaction/preparation/<session>/<attempt>/RESTORE-MAP.md; its parent
compaction folder ignores itself in Git because maps hold private working context. Unknown or
unwritable launch directories retain the instance-home fallback named in the request; it may need
permission if outside your working directories. When there is no named path, use your durable seat
folder instead: <topology root>/rigs/<rig>/seats/<seat>/RESTORE-MAP-<UTC yyyymmdd-hhmm>.md, derived
from rig whoami --json and rig config get topology.root. Run date -u for the timestamp and every
time you write in the map. Do not estimate times: an estimated time can land before events it describes.rig context recap-write --rig <rig> --seat <seat> --file <that file>. If your world profile has a seat
recap atom, it loads this recap, and an old recap would be served as if it were current.grep -n the JSONL for a row id
or timestamp), and which file holds the evidence for which claim.grep -n), not the
whole file unless the whole file is the point;wc -c);rig context profile … --json (totalEstimatedTokens).RESTORED note, if one exists) so a later
reader can walk back through earlier windows.LEARNED.md; mission state goes in the mission's own files; work another seat must act on goes in a queue
row. The map points to these rather than repeating them./compact next; the summary should
name the map path and the next authorized step.A map that lists files without saying how they connect is an inventory, and an inventory is what compaction already leaves you. The edges are the point.
You have facts without connections. Rebuild the connections before you act on anything.
Use the native read tool for file reads throughout restoration. Load refocusing
and consume the current topology and work trace that actually arrived with the
restore request; do not rerun Python merely to duplicate it. If no current trace
arrived, name that delivery gap. A packet pointer, compact summary or truncated
extract is not a full source read. Read required notes and full sources separately
and complete the restore steps and read-depth audit below; partial reading does
not establish completed restoration. The earlier acknowledgement-only boundary
is not a restore request.
<OPENRIG_HOME>/compaction/post-compact-extra/<session>.md, named by your full session such as
[email protected]) when it exists, the newest row or message from whoever routes your work, and any hold
from the authority above them. A hold, a release order or an operator's own restore map overrides the default
order below. Before any write, also run rig whoami --json and rig queue whoami.rig context list; for a private world install, run
rig context profile <world-ref> --situation post-compaction --rig <rig> --seat <seat> (the seat flags are
needed for its seat-scoped recap atom; take both values from rig whoami --json). Without a private world,
run rig context profile world-public --situation post-compaction and rig context get onboarding-width. This restores how the system works before you
restore what you were doing in it. If your work belongs to a project, re-enter its declared context too:
rig context work-install lists what the project declares (intent, context files, skills), so read the pieces
your task needs. --deliver prints them all; when several projects are declared (--json lists the ids), name
one with --project <id>.RESTORE-MAP-*.md
in your seat folder. If the selected map points to an earlier map for context you need, read that too.rig queue show <id> --full --json) and anything that may have changed since
the map was written: merged PRs, new rows, a new hold. The map records what was true when it was written;
current state still has to be derived.restore-instructions.md and touched-files.md help find
things the map does not cover.restore-instructions.md, then the most recent unique narrative, tail first, within the budget; and say in
your report that you restored without a map.restored from packet at <path>; resumed at step <X>, naming the map you used. When no packet exists, give
the map's path as <path> and say that you restored from the map.The audit message asks for a read-depth table and tells you not to conserve tokens. Do both in this form:
FULL, PARTIAL or NOT_READ, the ranges you actually read, and a reason.
Mark FULL only for content you read after this compaction; content carried in through the summary is
inherited, not read, and a file the harness re-attached after compaction is
PARTIAL (injected), not FULL, until you read it.FULL. "Required" means the ranked entries
above your class's tier line, in the exact parts they name. Everything else is lookup-only: every file in the restore packet
(touched-files.md, restore-instructions.md, transcript.md, transcript-latest.md, restore-summary.json),
the session JSONL and archives. Those stay
NOT_READ with the reason "lookup only", unless a human or the owning seat releases them. The audit
message's "do not optimize for token conservation" applies to required items: read those fully rather
than skimming them. It does not turn lookups into reading lists. In an early run of this skill, reading
the packet transcripts during the audit cost a default seat about 75k, more than the restore itself.RESTORED-<UTC yyyymmdd-hhmm>.md beside the
map:
The next restore map links this note, which keeps the chain unbroken.
PARTIAL with its reason is a correct outcome. Claiming coverage you did not reach is the
failure.