/two-lens-review

name: two-lens-review
version: 1.2.0
description: "Run pixtuoid's review protocol at either scope — the mandatory pre-merge DIFF gate (2+ differentiated-lens agents on the diff) or a whole-codebase AUDIT (subsystem × factor fan-out over the whole tree). Both draw ONE shared factor taxonomy + verify contract + disposition; they differ only in population and orchestration. Use before merging ANY PR, on 'review this PR/branch' / 'is this ready to merge' (diff scope), or on 'whole-codebase review' / pre-release / periodic audit (whole-codebase scope). Encodes the convergence contract (churn budget, two-fix-round cap, HIGH-only blocking), the five hard requirements, the escalation triggers, the adversarial finder→verify fan-out, and the disposition sweep the repo learned the hard way."
metadata:
  scope: "pixtuoid repo only"

two-lens-review (v1.2) — 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`](../../../.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).

Convergence contract (diff scope)

From the measured review history (derivation in this section's introducing commit): under ~1500 lines of churn, PRs converge in 0–1 fix rounds; above it, rounds 2+ are dominated by defects the PREVIOUS round's fixes introduced and by reversals of already-settled calls — the loop generates its own work. Hence:

• **Churn budget** — a diff whose ADDED + MODIFIED lines exceed ~1500 does

not enter review; split it first (stacked PRs). Pure deletions are exempt from the count — a removed line ships no behavior for a lens to verify — but only when the census rule below is satisfied. A change that both adds and deletes at scale is two PRs.

• **Two fix rounds, hard cap.** Round 1: full review, all lenses, folded into

ONE commit. Round 2: verify the dispositions + review ONLY the delta since round 1's head — no full re-sweep (full re-sweeps are where settled calls get re-litigated). If round 2 confirms a HIGH in round 1's fixes, STOP: revert the fold and re-land smaller, or re-scope the PR. There is no round 3 of patching patches.

• **Round 2's fold is the last commit that may change behavior, and it is

verified, not re-reviewed.** Every round-2 fix must be one of three shapes: a revert, a deletion, or a change that ships a test FAILING without it. Anything else is not a fix — revert the fold and re-land smaller. (Rounds 2+ are dominated by fix-introduced defects; this keeps the one unreviewed commit from carrying one.)

• **Blocking bar** — only a HIGH (correctness / security / invariant)

CONFIRMED BY THE ORCHESTRATOR against the code — never by the finder's own severity label — blocks merge. A MEDIUM this change INTRODUCED is fixed in the fold or forces a re-scope; taste findings are optional by default — drop them; a pre-existing find is SURFACED to the owner in one line. Nothing spawns another round, and agents never file issues.

• **No new gates in a fix round.** A fix may not introduce a new bespoke

checker/lint/census — gate-shaped fixes routinely arrive fail-open and feed the next round. Prefer making the failure IMPOSSIBLE (derive from the one source of truth) over DETECTED (police two copies); a genuinely wanted new check becomes its own small PR through the design gate. A check asserts facts in its own layer — a Rust fact is checked from Rust, never a Python regex over `.rs` files.

• **Deletion-shaped PRs enumerate first.** Before deleting N members of a

class, the population census (full list + criterion) lands in the FIRST commit or the PR body, before review starts — reviewers check the census once instead of restoring survivors one per round (#943).

• **The bot's `Findings: 0` is evidence, not the gate** — it can be vacuous

(an errored run wearing a clean badge). The gate: every finding (local lenses + both bots) dispositioned, and zero OPEN confirmed HIGH at the final head.

Diff scope — how to run (orchestration)

1. **Isolate**: the reviewed branch in a worktree (never the s