/two-lens-review

name: two-lens-review
version: 1.1.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 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.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`](../../../.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. 2. **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). 3. **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. 4. **Fold** accepted findings into ONE review-round commit; record any reviewer-flagged plan-misses as `plan-miss:` lines in its message. 5. **Disposition sweep** (shared, below). 6. **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). Ea