two-lens-review (v1.1) — the review gate + the whole-codebase audit

ONE protocol, two SCOPES over the SAME factors:

• Diff scope — the repo's mandatory merge gate ("Don't merge a PR without

the two-lens review" — workspace CLAUDE.md, "Things NOT to do"; PR #23 merged unreviewed with a critical path-traversal). 2+ differentiated-lens agents on the diff, disposition in the PR thread.

• Whole-codebase scope — the periodic / pre-release AUDIT. A diff review and

an audit scan DIFFERENT populations (fix-introduced-in-one-change vs existing code + cross-PR accumulation), so the audit is a SEPARATE pass, not a bigger PR review — but it runs the same factors, verify contract, and disposition.

The factors, the fill-in-the-slots lens briefs, the five hard requirements, the escalation triggers, AND the whole-codebase fan-out orchestration are all canonical in .github/prompts/pr-review.prompt.md — read it; fill from THAT file, never a paraphrase here (a copy here is the exact two-copies-drift class Lens 2 hunts — when the prompt gains a factor or trigger, a copy here silently lags). This skill owns only when to invoke each scope, how to orchestrate, and the red-flag self-checks.

When to use

Diff scope:

• Before merging any PR (no exceptions — it's the gate, not a nicety; no size

exemption — lens count can shrink, the gate can't).

• User says "review this branch/PR", "two-lens review", "is this ready to merge".
• After a fix round, to re-review the new head before merge.

Whole-codebase scope:

• User says "whole-codebase review" / "audit the repo"; a pre-release or milestone

sweep; a periodic drift/design-debt pass.

• NOT the per-PR gate — that's the diff scope above.

Two agents MINIMUM (diff scope), lenses differentiated (a shared lens makes their misses re-correlate); lens/finder count scales with blast radius (or tree size). The quality lever is never the lens NAME — it's the change-specific checklist filled into the <...> slots, and the FACTOR COVERAGE (no family silently dropped).

Diff scope — how to run (orchestration)

1. Isolate: the reviewed branch in a worktree (never the shared checkout —

two sessions on one tree race on HEAD). Note path, branch, base sha.

1. Dispatch both lenses in parallel, in the background, each a subagent with

its brief from pr-review.prompt.md, <...> slots FILLED with this change's specific claims (a lazily-filled slot turns both reviewers generic). Give each the worktree path + git -C <path> diff <base>..HEAD. Then add an escalation lens for EVERY trigger the prompt's "When two lenses aren't enough" section matches on this change — that trigger→lens list is canonical THERE; don't restate it here (a copy would be the two-copies-drift class the header names — a new trigger added to the prompt must reach reviews without a manual mirror).

1. Collect + verify: first read each lens's ACTUAL return before counting it

toward the lens floor — a one-word summary or "test"/placeholder findings is a STUB (a dispatch, not a review); re-run that lens as a single focused agent (PR #455's a11y lens stubbed under an APPROVE-WITH-NITS aggregate; its re-run caught a real AA failure). Then for every MEDIUM+ finding, verify the premise yourself before coding a fix — reviewers have incomplete design context; read the crate's SHARP-EDGES.md entry first (its CLAUDE.md only INDEXES them — the index line is not the entry; tests/, Raycast and site keep theirs inline in the guide), and if a finding is deliberate design, REFUTE it by citing (or ADDING) that entry.

1. Fold accepted findings into ONE review-round commit; record any

reviewer-flagged plan-misses as plan-miss: lines in its message.

1. Disposition sweep (shared, below).
2. After a fix round, re-run the gates and watch the NEW head's CI; before

merging, read the online bot review's LATEST COMMENT verdict (Findings: N) + mergeStateStatus — the review JOB passes even when it posts findings, so the check table alone can't gate (#448). If the bot ERRORED or left no findings comment at HEAD (it can fail on a very large diff — error_max_turns with no comment — or on a spent quota, which the workflow now states itself in an <!-- absent-<marker>:<sha> --> comment; do NOT read that as a review), the gate is unsatisfiable as written: split the PR smaller, else fall back to one extra differentiated lens + owner merge, recorded in the PR thread. State the condition behaviorally (errored/absent), never a fixed LOC ceiling.

Whole-codebase scope — how to run (orchestration)

The full fan-out template (subsystem finders + whole-tree specialist sweeps → adversarial verify → dedup → ranked report) is the "Whole-codebase scope — orchestration" section of pr-review.prompt.md. In brief:

1. Scout (main loop): map crates / LOC / churn / hot files → the work-list.
2. Find: fan out subsystem finders (per crate/module cluster) + whole-tree

specialist sweeps (arch-invariants, concurrency/liveness, security, drift — the aggregate-only lenses). Each finder carries the FULL factor checklist. Prefer a Workflow (pipeline per cell); degrade to parallel Agent fan-out.

1. Verify each finding adversarially (default REFUTE; check sharp edges;

construct a repro or refute) — a separate skeptic per finding, never the finder self-certifying.

1. Dedup + rank survivors; ship a report ranked by corrected severity,

grouped by factor family, KEEPING the refuted-as-deliberate list (coverage proof + sharp-edge context for the next agent).

1. Disposition sweep (shared, below); end with the repo-wide stale-phrase

grep == 0.

Scale to the ask: "any bugs?" → a few finders, single-vote verify; "thoroughly audit / be comprehensive" → larger finder pool, multi-vote adversarial verify, synthesis. Do the involved/cross-crate refactors it surfaces IN-ARC (design-debt lens); defer only genuinely big/refactor work to issues.

Disposition sweep (both scopes)

Drive every reviewer/finder/bot finding to exactly one terminal state: FIXED · REFUTED-with-trace (cite or ADD the relevant per-crate SHARP-EDGES.md entry, or the guide's inline section where no sibling exists — that keeps the next agent's context accurate) · ISSUE-FILED (no-deferral rule: only big/refactor defers). "Acknowledged, no action" is NOT a state — #40's ignored finding became a 0.4.1 blocker (#46). Diff scope: in the PR thread. Whole-codebase scope: in the ranked report. Sweep at the FINAL merge head — a finding that lands after the local lenses ran is the #283/#383 drop class; and check WHICH commit a bot re-flag was raised against before re-litigating (#316's were stale).

Red flags (you're about to skip the gate / short the audit)

| Thought | Reality | |---------|---------| | "It's a tiny/doc-only PR" | The gate has no size exemption; run it (lens count can shrink, the gate can't). | | "CI is green, that's enough" | CI can't see design, blast radius, drift, or a deliberate-looking real bug. | | "The reviewer said X, so fix X" | Verify the premise first — check sharp edges; a wrong fix contradicts a design decision. | | "One thorough agent is fine" | Two differentiated lenses is the floor; one lens's blind spots go uncaught. | | "I'll note the finding and move on" | Every finding needs a terminal state — dropped findings become release blockers. | | "The diff looks clean, we're done" (audit) | The diff scope can't see drift accumulation / design-debt accretion / arch erosion — those need the whole-codebase pass. | | "The verdict row shows N lenses ran" | Count REAL returns, not dispatches — a stubbed lens under a clean aggregate hid a real AA failure (#455). | | "The bot says it's still broken" | Check WHICH commit it reviewed — #316's re-flags were raised against an old commit; five were already fixed (REFUTED-STALE). | | "The finder found it, report it" (audit) | Findings self-certify nothing — a separate skeptic must try to REFUTE each survivor first. | | "Just unify the duplication" | Some duplication is documented deliberate separation (per-source decoders, per-CLI targets); check the sharp edge before proposing a merge. |