Verify

Verify - Reality Check

Spawn a subagent to cold-review a claim, a diff or a piece of code. The subagent is a hostile reviewer. Its job is to find problems, not to validate. Its verdict has teeth, because a CRITICAL PROBLEM FOUND halts the main agent's current line of work.

The subagent's full operating manual lives in .claude/VERIFY_INSTRUCTION.md. The main agent does NOT read or understand that file. The main agent has four responsibilities: spawn the subagent, point it at that file, hand it the target material verbatim, then act on the verdict. The manual stays out of this skill for two reasons. It keeps the main agent's context lean. It also removes the temptation to paraphrase the reviewer's rules into the spawn prompt, which is how bias enters the review.

When to invoke

• The user types /verify <anything>. The argument is freeform. Examples:
  • /verify your last claim about "<quoted claim>"
  • /verify the weird code in cerf/memory/shared_mem_pool.cpp
  • /verify current diff for hacks
  • /verify my fix for the tray bug
• The main agent wants an independent check. This happens after non-trivial code, after a refactor, or before it hands back a long-form explanation as authoritative.

Self-audit gate - mandatory before spawning

Rule-compliant code is the main agent's own responsibility. /verify does not discharge that responsibility, because it is not a find-my-bugs service. It is a fresh-eyes pass for blind spots that the main agent cannot see alone.

Before you spawn the subagent, audit the target yourself against CLAUDE.md and every page under agent_docs/. If your self-audit finds a violation you can already name, the spawn is invalid. The subagent never gets to be the first reader of a problem the author already saw.

The self-audit lands in one of two shapes. Each shape allows exactly one next action.

Shape A - known small-scale violation, locally fixable

You can name a specific, bounded rule violation in what you wrote or are about to hand back. Examples: a reader-side guard that masks a writer bug. A stub that returns fake success. A peripheral-register handler you wrote without reading its reference, so the prompt can carry no grounding for it. A hex or decimal value you computed in your head instead of through a tool. A free function that takes services as parameters. A static or global that holds service state. A comment that names a checklist filename or a § reference. A LOG site that fires per-clock and belongs in a trace file. A x ? f(x) : 0 null-guard around a callee that already handles null.

Action: fix it yourself, in the same turn, before you spawn. You can never spawn /verify while you sit on a violation you can name. After the fix, decide whether you still want /verify at all, because the reason to spawn often disappears with the known defect. If you still want it, spawn against the fixed target.

Shape B - foundational damage, not locally fixable

The target rests on hacks. The architecture breaks dependency-inversion or service-locator rules at its core. The implementation layers reader-side suppression over an unfixed writer chain. The change cascades workarounds over a wrong premise. Several CLAUDE.md serious-violation categories apply at once, such as guessed implementations, reader-side suppression, host-API blame, or CE binaries mocked in host C++. Local edits cannot rescue the code.

A spawn produces nothing here. The hostile reviewer returns CRITICAL PROBLEM FOUND, and you already know why, so the spawn burns budget to confirm what you can already see. A silent fix is equally wrong, because the scope makes a unilateral rewrite a direction-changing decision that belongs to the user.

Action: halt the spawn, halt further patching, and present the situation to the user in this shape:

"I was about to run /verify on <target>, but caught myself first. The target has foundational damage I can already name without a hostile-reviewer pass: <specific rule(s) violated, specific hack(s), specific architectural break>. Running /verify here will not produce information I do not already have. I propose deleting <files / sections / commits / staged changes> and rewriting properly: <one-sentence sketch of the correct shape>. Want me to proceed with the delete-and-rewrite, or take a different direction?"

Then wait for the user's call. Do NOT spawn the subagent. Do NOT soften the diagnosis to justify a spawn, as in "but maybe a reviewer must double-check just in case". Do NOT start the rewrite alone, because direction-changing work waits for explicit user approval.

When the self-audit comes up clean

The spawn is valid when three things hold. You looked at the target honestly. You found no rule violation you can name. You want a fresh pair of eyes for blind spots you cannot see yourself. If you catch yourself rationalizing during the self-audit, as in "this is probably fine, the reviewer will confirm it", that rationalization is the answer. The spawn is invalid. Pick Shape A or Shape B and act.

Protocol

1. Collect the target material

Resolve the freeform input into a concrete target. Be literal:

• Quoted claim - take the claim verbatim. Do NOT rephrase it, summarize it, or soften its tone.
• File path - read the file. For a single function, capture its full body plus enough surrounding context to make it reviewable.
• "current diff" / "this diff" / "unstaged" - run git diff. If anything is staged, also run git diff --cached. Capture the full patch. A diff against the last commit absorbs whatever else is uncommitted. This tree carries the parallel work of other agents and of the user, so scope the target to the files your own change touched. A target that reaches wider spends the verdict of the reviewer on code that is not yours. Its findings then name the in-flight work of somebody else as a defect.
• Commit or range - git diff <range>.
• Mix - collect every piece the input references.

If the target is genuinely ambiguous, ask the user one short clarifying question before you spawn. Do not guess the target.

2. Spawn the subagent

Use the Agent tool with:

• subagent_type: Explore - read-only by construction, with no Edit, Write or Agent tool. This matches the hostile-reviewer role and stops the reviewer from modifying anything.
• model: opus - mandatory, never omitted. Without it the reviewer runs on whatever the agent definition or the parent session supplies, which can be a smaller model. This review is the gate for guessed implementations, fabricated IDA citations and reader-side suppression. A weaker reviewer waves those through with a confident LEGIT. A false LEGIT is worse than no review, because the main agent then treats the target as cleared.
• description - short, for example Reality-check on <short target>.
• prompt - the pointer to the prompt file, and nothing else. See § The prompt file below.
• run_in_background: true - the preferred default. A review reads CLAUDE.md plus every page under agent_docs/, greps the codebase, and often runs IDA decompiles, so it routinely takes minutes. Spawn it in the background and advance other work, because the harness signals you when the verdict is ready. Do NOT poll it, sleep, or check its progress. CLAUDE.md § Background tasks makes the signal the contract, so polling a backgrounded task violates the rules. Use the foreground only when your strict next step depends on the verdict and no other work exists, such as a hand-back to the user. When in doubt, background it, because an idle wait on the signal costs less than a blocked foreground call.

The prompt file

The whole spawn prompt lives on disk, in tmp/verify/<slug>.md under the repo root. <slug> names the body of work. One file serves one body of work across every round.

Before you create the file, list tmp/verify/. If a file with your slug holds other work, pick another slug. Never overwrite a file you did not write.

Give the Agent call this text as its prompt, and nothing else. Replace the path placeholder with the absolute path:

"Your full spawn prompt is the file <absolute path of tmp/verify/<slug>.md>. Read the whole file before anything else. If one Read cannot hold it, read it in slices to the end. Its contents are your prompt, verbatim."

Everywhere below, "the prompt" means the contents of that file.

Keep the prompt minimal. Do NOT paraphrase the operating manual, summarize its rules, or hand-pick which categories to include. The subagent reads the authoritative file itself. A long explanatory prompt from the main agent gives bias a way in.

The prompt file carries these four items, in this order, and nothing else:

1. The pointer to the operating manual, on the first line. Use this text: "START WITH READING .claude/VERIFY_INSTRUCTION.md TO UNDERSTAND WHY YOU WERE SPAWNED AND WHAT IS YOUR OBJECTIVE. That file is your operating manual and is authoritative over anything in this prompt - if this prompt and the file disagree, the file wins. READING THAT FILE IS MANDATORY. Check pwd if not found. It is at repo root (INSERT PWD/REPO ROOT PATH)"
2. The target material verbatim. Claim text, file contents, diff, or all of them, unmodified. No preface that softens it. No "I think this is probably fine" framing.
3. Every piece of context that cuts against your own claim. State your doubts, your counter-evidence and the weak links in your reasoning plainly. If prior reasoning led you to the claim, include that chain, so the reviewer can spot the rationalization.
4. One neutral closing line. "Produce your finding in the required output format from the operating manual. Do not accept my framing on faith."

That is the whole prompt. The operating manual already holds the role explainer, the category list, the verification-tools section and the output format, so add none of them. When you feel the urge to add "and also, remember to check X", that urge is the bias entering. Resist it. .claude/VERIFY_INSTRUCTION.md is the single source of truth for the subagent's work. Your job is to hand over the target and step aside.

Special case - a checklist target declares an audit mode. A checklist target is a planning document, a numbered phase-by-phase design plan, or any file under docs/ai_checklists/ or agent_docs/checklists/. For these, insert exactly one of the lines below directly above the target material, between item 1 and the verbatim checklist:

• AUDIT MODE: PLAN - the work is not implemented yet. The reviewer audits the plan itself: IDA grounding, hidden assumptions, bullet ambiguity, and every "known gaps" section. It also verifies that the steps in literal order produce the claimed runtime behavior. The reviewer does NOT compare the codebase against the checklist, because the work has not started.
• AUDIT MODE: IMPLEMENTATION - the work is done, and this diff or branch claims to implement it. The reviewer audits the codebase against each bullet: literal file-layout compliance, per-bullet code mapping, silent deviations from checklist values, and fabricated citations.

A checklist target with no AUDIT MODE: line returns CRITICAL PROBLEM FOUND. [UNVERIFIABLE], because the reviewer cannot tell which audit shape applies. A planning document and a completion claim look identical to a reviewer. Without the declaration the reviewer guesses, and a wrong guess spends the whole verdict on an accusation that the main agent lied about completion.

Special case - hardware behavior declares its grounding. A citation inside a source file is optional (agent_docs/code_style.md § Comments), so the reviewer cannot read your grounding off the diff. Declare it in the prompt instead, directly above the target material, one line per non-trivial hardware behavior the target implements:

• GROUNDING: <what> <- <bundle> <module> <function> <address> for a decompilation, which is the common case on this project. Most CERF behavior is grounded in the guest ROM, not in a document.
• GROUNDING: <what> <- <reference path> § <section> for a document: a datasheet, a SoC user manual, a CPU architecture manual, a standard.

agent_docs/rules.md § Reference Licence Hygiene governs both shapes. It requires the ROM bundle name on every decompilation citation, and it rules out a ROM that a user compiles.

A register handler, a bit field, a reset value, an instruction encoding, an MMU rule and a timing each need one. Name the reference you actually opened, or the address you actually decompiled. If the prompt grounds none of it, the reviewer returns CRITICAL PROBLEM FOUND. [UNGROUNDED HARDWARE BEHAVIOR]. A value nobody can point at came from memory. Never write a GROUNDING: line for a reference you did not open, or for an address you did not decompile. The reviewer can re-run the decompile, so an invented address returns a fabricated-citation verdict.