complete-project-scope-code-review

Files (4)

• SKILL.md
• failure-modes.md · references/
• lane-brief.md · references/
• owner-gate-form-lifecycle.md · references/

SKILL.md (first lines)

# Complete project-scope code review

A review campaign, not a review. The output is a graded record, a reviewed plan, and merged work —
each stage gated by something that has been watched fail.

**This skill composes; it does not replace.** Each phase names the skill that owns its mechanics.
Load those rather than reimplementing them:

| Phase needs | Skill that owns it |
|---|---|
| Grade vocabulary, record shape, the `## Still open` discipline | `evidence-first-research` |
| Merging lane blocks into one record | `multi-lane-report-assembly` |
| Adversarially re-deriving a written record from its sources | `research-record-audit` |
| Tautology / fake-honesty hunting inside a lane | `code-review-evidence` |
| Mechanical per-diff gates inside a lane | `code-review-checklist` |
| Blast-radius ranking of a merge | `review-changes` |
| Verifying the diff base before judging it | `review-gate-diff-verification` |
| Auditing a plan's acceptance gates before anyone builds | `design-gate-audit` |
| Getting a human ruling per decision | `owner-gate-review` |
| Per-agent isolation | `worktree-agent-isolation` |
| Running one work package end to end | `task` (and `create-task-spec` when it needs a spec) |


## Phase 0 — Ground truth before anyone is dispatched

Measure, do not assume. Everything the lanes are told must be something you ran.

1. **Run the project's build, test and lint commands** from its config and record the exact
   numbers — counts, duration, warnings. A prior note saying "two flakes" is a claim about a
   different machine at a different commit; re-run it.
2. **Size the codebase**: production lines by layer, test lines, ratio. Write the number down
   before forming an opinion about it — a suspicion recorded as a hypothesis can be disconfirmed,
   and one held silently cannot.
3. **Verify every claim you plan to brief the lanes with**, at `path:line`. Plan documents, prior
   reviews and issue bodies go stale between writing and reading; paths move, counts drift,
   "N unused copies" is routinely 1 used copy.
4. **Name the base commit.** Every finding is against it. Lanes citing a moving ref cite nothing.

Brief the lanes with a labelled block — *"VERIFIED GROUND TRUTH (trust these over anything the
brief says)"* — so a lane knows which half of its input has been checked.

## Phase 1 — Parallel expert lanes

**Derive the lane roster from the repository, never from this list.** Read the project's own
stacks, personas and top-level directories, and open one lane per distinct expertise the code
actually demands. A fixed roster reviews the project you expected. A service with a separate
front end and its own infrastructure definitions needs different lanes from a single-runtime
library, and both need lanes nobody would have guessed without looking.

Lanes that recur: architecture/layering, domain algorithm (retrieval, scoring, whatever the
product's hard part is), the primary language's code quality, data access, test-suite QA, the
consumer-facing surface (CLI, API, UI), the product's **design** — flows, states, wording — and
operations/infrastructure.

The surface and the design are two lanes, not one. "Is this contract correct" and "is this good
to use" are different questions, and the second loses to the first whenever they share a lane.
Give the design lane a way to *run* the product, and read `references/lane-brief.md` before
dispatching it — a design lane briefed like a code lane returns opinions.

Each lane is **read-only**, gets **its own worktree and its own workspace id**, and is told:

- The verified ground truth, the base commit, and its own lens.
- **The lane contract:** one `### F<n> — <claim, present tense> [GRADE]` block per finding, grade
  from the closed set `MEASURED` / `READ` / `INFERRED` / `UNVERIFIED` at the end of the claim
  line, an `**Evidence:**` line carrying `path:line` for everything `READ` or `MEASURED`, a
  severity, a `## Still open` list, and its grade mix. This is `evidence-first-research`'s
  vocabulary; do not invent a second one.
- **Permission to disagree with the brief, in writing.** Say it: *"if a briefed finding is wrong,
  proving it wrong is a first-class result and worth more than confirming it."* The highest-value
  lane output on the session this skill comes from was a lane that proved a briefed feature had
  never worked at all. A brief that only invites confirmation gets confirmation.
- **Decision-ready owner questions**, one line each, so they can be routed without reformatting.

Run lanes concurrently up to your dispatch cap; where the cap bites, wave them and give the later
wave the integrated result of the earlier one to review rather than the same raw input.

## Phase 2 — Integration

Follow `multi-lane-report-assembly` for the mechanics — read it before assembling, because
renumbering, truncation at embedded `## ` headers and stale cross-references are where assembled
records break. On top of it:

- **Convergence raises confidence; lane count does not settle a fact.** Two lanes reaching the
  same finding independently is evidence. Two lanes disagreeing is not a vote — go read the code
  and settle it. The minority lane is right often enough that counting is not a method.
- **Re-verify at `path:line` every finding that drives expensive work** before it enters the
  record. Cheap findings can ride on their lane's grade; a finding that will cost a week cannot.
- Record what is **healthy**, explicitly, so a later simplification pass does not sweep it up.
- Record every **disconfirmed hypothesis** as plainly as the defects. "We suspected bloat; we
  measured it; the suspicion was wrong" is a finding.

## Phase 3 — Adversarial verification

Dispatch an independent reviewer **instructed to falsify the record**, with the sources but not
your reasoning. It re-derives every load-bearing claim, re-runs every `MEASURED` one, and checks
quotes verbatim at their cited lines — `research-record-audit` owns that procedure; read it when
briefing this pass.

Then publish what it changed, in the record, as a table: claim → refuted / corrected / softened /
reproduced. A reader must be able to see which way the errors ran. On the source session this
pass refuted or corrected six claims while every core conclusion survived — the failures were in
supporting numbers, which is exactly what gets quoted later.

**Attack before anyone implements.** A refuted number that reached a plan costs a work package.

## Phase 4 — Calibrate severity against production reality

A defect that is real in code and has never once fired in a deployment is still real — and it is
not a hotfix. Before ranking anything, query the live system read-only: does the table the defect
writes to have any rows? Has the flag it depends on ever been set? Is the feature reachable at all
in the shipped configuration?

Where the live system is a managed service rather than a file you can open, "read-only" is an
access decision with a cost — say which instrument you used (a direct query, telemetry, logs, a
staging replica) and grade the answer accordingly. An `UNVERIFIED` calibration is a legitimate
result; a calibration inferred from the code is not one at all.

State the result as *loaded, not fired* when that is what it is. This changes urgency and
sequencing; it must not change the finding. Two blockers on the source session had never fired in

From Arasz/ai-badger, MIT.

More from Arasz/ai-badger