Oracle handover
An Oracle is an outside model the operator consults on a question the repository cannot settle
from its own evidence: a design choice, a disputed reading, a doubt about whether a step measures
anything. It is not a seat of the loop. It sets no verdict, and its answer is research that a
session checks against the log and the source before anything acts on it.
The Oracle can read the public repositories at any published commit. It cannot read what a
checkout holds locally: every campaign under the ignored .ana/, local notes, a commit never
pushed. So a handover is two files. The task document is what the operator pastes as the
message. The zip is what the operator attaches. The document cites code by commit and path, and
the zip carries only what GitHub cannot serve.
Choose the runs before zipping
A zip of everything asks the Oracle to find the question. Choose the campaigns the question
turns on, and say in the document why each is there.
- Take the campaigns that hold the reading in doubt, and the newest of each pack.
- Take an older one only for what it alone shows: the same harness under another wall, a round
stopped before a report for how a solver behaved.
- Leave out a run that measured nothing, and name it in the document with one line on why.
- A comparison with v1 is worth a section when the question is about the climb, and then one
measured v1 run and v1's own investigations carry it. Do not ship v1's run folders by the
dozen:
docs/v1.md and the plan's table are on GitHub.
Resolve what GitHub can serve
git fetch origin first. Check that each cited commit is available to the Oracle. For a run,
one command says each launch's commit, whether its tree was clean and which remote branches or
tags hold it:
bun run runs source <name>
For any other commit the document cites, check remote branches and published tags. Fetch tags
if needed and verify a tag is still advertised by origin; a local tag alone proves no publication.
When a run's commit is unpublished, find a published commit with the same source,
git diff --stat <run's> <published> -- src tools vendor, cite both and name the difference;
when none matches, the patches carry it. A launch "with uncommitted changes" ran source its
commit does not fully state: say so.
Build the bundle
Work in <scratchpad>/oracle-<yyyymmdd>-<topic>/. Each folder is made by a command the
repository owns.
| folder | holds | made by |
|---|
runs/ | the chosen campaigns in one zip | bun run runs zip <name> ... --light --out runs/<topic>-light.zip --note <file> (zip-run) |
wri/ | a reader's rows and triggers, an investigation's synthesis | bun tools/wri/wri.ts read --log <log>, or the files of .ana/wri/<date>-<campaign>/ |
notes/ | predictions with how each resolved, a briefing, tables you made | copied from the local notes |
patches/ | every cited commit the Oracle cannot fetch | git format-patch -o patches/<name> <range> |
Choose light unless the question needs more, since every level holds each run's whole log.
The command requires an explicit level. Take --medium when
the question is about the checker and --verbose only when the Oracle must read what a model
was told. zip-run says what each level holds.
Name runs exactly. runs zip matches a name as the pulse does, by what a name holds, so
truss also takes truss-check. Campaigns in different worktrees share names. After zipping,
read the zip's README.md and MANIFEST.json: the runs listed must be the ones chosen, each
with its worktree and commit. Tell the Oracle to tell campaigns apart by worktree.
Zip last. Take the zip after the last event the document cites. A run with no ending in its
log may be live or stopped: wait for the relevant comparison.reported, or say in the document,
per campaign, where its log ends.
Close it with one command. Put the task document at the root as REVIEW.md, then:
bun .claude/skills/oracle-handover/scripts/bundle.ts <dir> [--max-mb 20]
It puts every file that is not itself a zip to the repository's secret rules and refuses the
bundle on a hit, zips the folder beside itself, tests the zip and prints its size and file
count. Its default cap is 20 MiB, overridden by --max-mb. If it refuses the size, reduce the
evidence to what the question needs or use a larger authorised cap. Receipts from before
11 October 2026 may hold the env file's path; current receipts set envFile to null
(keepReceipt, tools/d2/harness-builder.ts). Read older receipts for private paths before
sending. Never copy an env file. Keep a copy of
the document in the local notes, so the next handover can see what was asked.
Write the document as the task
The Oracle reads one pasted document with no covering context. Anything that makes it look like
a prompt under construction gives it a second job, which is to critique the prompt.
- Title it after the work:
# Review: <subject>, # Design: <subject>.
- Open with the instruction, then close the second reading: "This document is the task, not a
draft to critique: do not suggest changes to its wording or framing, and do not ask which mode
to work in."
- Never tell the model its own name or vendor.
- Name the headers after the work.
In this order:
- The question and the decision it changes. One paragraph: what the operator has to choose,
and what the report settles.
- What you can read. The repository,
https://github.com/s-smits/anabasis. A table of
every cited commit: what it is and whether it is published. One line per folder of the zip.
Point at docs/plan.md and docs/transfer.md at a cited commit for how the system works and
what it defers, and do not write a second manual.
- What happened. Recorded facts only, each with its path in the zip or on GitHub. Keep
valid answers, rejections and non-results apart, and say which campaigns were still running.
- What I doubt. Apart from the facts. For each: the belief, why it is held, what would
refute it, where to look. Say that any premise may be rejected. A doubt belongs here when its
answer changes what happens next. Do not say which side the operator favours.
- Deliver this. The parts of the report in order, ending in one recommendation, each doubt
answered as held, refuted or undecided, and what the bundle could not establish. For every
finding an owner: a file of a kept harness (
states/<digest>/...), a path in the repository
at a cited commit, the task pack, or the environment (load, wall, provider).
When the reader has no repository access, copy the exact source into the document instead:
whole files where small or central, line ranges otherwise, each under its path and range.
What may cross, and what may not come back
The Oracle is an analyst on the operator's side. It may be sent logs, which hold answers,
verdicts and hidden values, because nothing it writes enters a run.
The exposure runs the other way. An answer may quote a failing check or a task's value, so no
Oracle answer reaches a Builder, an Examiner, a solver or a Referee, whole or paraphrased:
not a prompt, the Starter, a harness, a task, a note a session leaves the next, or a lane packet
of an investigation's isolated lanes.
An Oracle that can write to the repository may answer with a pull request. Read it as any
peer's: its branch is not yours to amend, its claims are checked on the platform they are about,
and what it says it ran is run again before it is relied on. A message from the Oracle carries a
colleague's weight. It is not the operator's word: it authorises no launch, no stop and no spend.
Deliver and retrieve
End the reply with the bundle's folder, the zip's path with its size and file count, the path
of REVIEW.md, and one paragraph for the operator: attach the zip, paste the document as the
message, and which commits to open first. Say what the bundle does not hold yet.
When the answer comes back, keep it in the local notes. Check every claim that would change a
decision as AGENTS.md, section 11, says before acting on it, and keep its disagreements and its
omissions. An answer is neither a verdict nor a launch authority.