Stage 1: Audit context

Concept — scoped sub-agents and parallel delegation

You leave with — a context ledger you reconciled yourself

Agents reason locally. You reconcile globally.

Why not just hand one agent both repositories?

You could. Someone in the room will. Here is what happens:

   ONE AGENT, BOTH REPOS              TWO AGENTS, ONE REPO EACH
   ─────────────────────              ─────────────────────────
   spends attention on                each finding is local
   framework detail                   and checkable

   reasons deeply about one           neither can guess across
   side, shallowly about the          the boundary — so it says
   other                              so instead

   fills the gap between them         the gaps stay visible,
   with plausible invention           and YOU close them

   you cannot tell which parts        the disagreements show up
   it actually verified               as disagreements

The second shape is not more work. It is the only shape where the seam becomes visible, because a disagreement can only appear when two independent accounts are laid side by side.

◆ Predict #2

The first agent will audit its repository and report with total confidence. Name two things it cannot possibly know — things only the other repository can tell you.

Write them down before you dispatch it.

The facilitator demonstrates — briefing the first auditor

The repo-auditor agent already exists at .claude/agents/repo-auditor.md. The capability is standardised; the brief is yours. Watch what the brief pins down:

   ▸ which repository — and that it may read nothing else
   ▸ what to inspect: entry points, contract artifacts and versions, outbound
     calls, business rules, boundary validations, error mappings, idempotency,
     correlation, tests
   ▸ that every claim cites a file, and a line where one applies
   ▸ that anything needing the other repository goes under UNKNOWNS, not a guess
   ▸ that it must report what the source requires and the repo does NOT do —
     absence from code is not absence from authority
   ▸ the exact return headings, so two returns can be COMPARED, not just read

That last one is quietly the most important. Identical structure is what turns two reports into one comparison.

▶ Your turn — brief the second auditor

Write the brief for the other repository yourself.

Same return shape — that is what makes them comparable. But the things worth inspecting are not identical on both sides of a seam: one side translates and calls, the other decides and records. A brief that treats them as mirror images will miss what is specific to each.

Both auditors can run at once. They only read, so there is nothing to serialise.

Then the real work — reconcile

In docs/context-ledger.md:

  │ Claim │ Asserted in │ Evidence │ Contradicted by │ Your ruling │ Status │

This part is yours, not the agents’. Three things to be deliberate about:

A claim is what a repository believes about the world beyond itself. Those are the rows that matter. A claim can be entirely true locally and false at the seam — that is precisely the failure mode you are hunting.

UNKNOWN is a finish state. If neither repository can settle something, it stays UNKNOWN. Do not resolve it because an empty cell looks unfinished.

When the two disagree, you rule. Not the agent that sounded more certain. Confidence is not evidence, and an agent has no way to signal the difference.

⚠ Trap — the tempting move here is to accept whichever account is more detailed. Detail is a property of how much the agent had to say, not of how much it verified.

Reveal: compare your ledger against Prediction #2. What could the first agent not have known?

⌘  /hand-off

---