double-review

name	double-review
description	Validation gate for freshly written code — run two independent reviews (codex CLI + a Claude review subagent) over the same scoped diff, then empirically vet every finding against ground truth before accepting or vetoing it. Use after landing a work item (especially subagent-written code) and before committing.
allowed-tools	Bash, Read, Glob, Grep, Edit, Write, Task, Agent, AskUserQuestion

Double Review

Documented in depth: Most AI code reviews are noise. Here's how to fix that.

Gate the change you just landed behind two independent reviews and an empirical vetting pass. This is a validation gate, not a discussion: it ends with every finding either accepted with proof or vetoed with proof, the accepted ones fixed and pinned by tests.

Two failure modes motivate the gate:

1. A green test suite is not proof of correctness. Implementers (subagents especially) satisfice: they code until their own tests pass. Semantic mismatches with the spec, stateful-API gotchas, and edge cases the tests never pin all survive.
2. Reviewers are confidently wrong, too. Every review pass mixes real bugs with plausible-but-wrong findings. Accepting blindly injects regressions; vetoing blindly ships the bugs.

So: review twice, independently — then trust neither until ground truth has spoken.

1. Scope the gate

Before launching anything, write down:

• The diff range — commit range, staged diff, or working-tree diff, plus the file list. Both reviewers get exactly the same scope.
• The ground truth — the thing a disputed finding can be tested against: a reference implementation you can execute, a spec with runnable examples, the real API. Write the exact command to query it. No executable ground truth? Say so, and name the fallback (spec text, maintainer ruling).
• A scrutiny list — the 3-6 riskiest spots you'd check first: stateful APIs, encoding boundaries, off-by-one-prone length math, error paths, concurrency. Both reviewers get this list; it aims them without capping them.

2. Launch two independent reviewers

Run both against the identical scope, blind to each other:

• codex (external reviewer):

  codex exec --sandbox read-only "/review <scoped prompt>" </dev/null >/tmp/codex-review.txt
  

  Launch it through your harness's own background mechanism (in Claude Code: the Bash tool's run_in_background — not a trailing shell &) so the harness tracks the real codex process and delivers a genuine completion notification. Then wait for that notification; don't busy-poll.

  Hard-won gotchas:

  • Close stdin (</dev/null) or codex exec hangs forever at zero CPU.
  • Never combine a shell & with the harness background flag. Double-backgrounding detaches codex: the harness tracks the shell, which returns instantly because of the &, so it fires a false "completed" the moment codex launches while the real review runs on with nothing waiting on it — you end up hand-polling a growing trace. Pick exactly one backgrounder.
  • Reviews take minutes (xhigh can run 10+ min on a large diff). If your harness can't background-and-notify, use a shell & with an explicit completion sentinel and poll that line (bounded), never the bare &: ( codex exec … </dev/null; echo "__CODEX_DONE__ $?" ) >/tmp/codex-review.txt 2>&1 &
  • codex emits a huge reasoning trace. Extract only its final answer — the last codex-turn block — rather than reading the whole file into context (e.g. awk '/^codex$/{n=NR} END{print n}' then tail -n +N).

• A Claude review subagent running this plugin's ../review/SKILL.md methodology: proof before reporting, concrete failing scenario per finding, "No issues found" over padding. Give it the same diff range and scrutiny list, and require file:line + evidence for every finding.

Don't idle while they grind: read the new code yourself. You are yet another reviewer, and the only one who knows the full context of what the change was supposed to do. If a reviewer goes silent well past its usual turnaround, keep working — treat a late report as a cross-check of what you've already verified, not a blocker.

3. Vet every finding — accept and veto only with proof

For each finding from either reviewer (and from your own read):

1. Construct the empirical test: run ground truth and the new code on the same input; compare. A finding you can't test this way gets downgraded to a question, not silently accepted.
2. Accept only when ground truth confirms the bug.
3. Veto only when ground truth confirms the code is right — or the finding demands fidelity nothing requires (e.g. mimicking a reference's internals on a path no contract pins).
4. When the diagnosis is right but the proposed fix is mediocre, take the better fix — reviewers identify problems; you own the remedy.

Reviewer confidence, eloquence, and agreement between reviewers are not evidence. Two reviewers converging on the same wrong finding is common; one command against ground truth beats both.

4. Fix and pin

Apply accepted fixes. Every accepted finding gets a pinning test whose expected values come from ground truth (paste the command that produced them into the test's comment). The full suite must be green again — not just the new tests.

5. Report the verdicts

Summarize for the user (and for whatever plan/PR document tracks this work): every finding, accepted and vetoed, with one-line evidence for each verdict. Record vetoes especially — the next session (or reviewer) will rediscover the same "bug" and must not re-litigate it.

Adapting for your project

• Name the ground truth explicitly — e.g. "the vendored reference implementation via ./third-party/tool/run", "CPython 3.12 via uv run python -c ...", "the RFC's test vectors". The vetting step is only as strong as this.
• Swap reviewers freely. The structure needs two independent reviews, not codex specifically — any external reviewer plus a Claude review subagent works. Keep them blind to each other.
• Tune the scrutiny list to your codebase's recurring failure modes and bake the worst offenders into this file.
• Callers welcome: other skills (e.g. tpp-orchestrate) reference this file as their review gate. Keep the gate generic here; put workflow-specific bookkeeping (where verdicts get recorded, commit conventions) in the calling skill.