How to use the passes

Free sample

The shared frame, running them, triaging findings, and the two-reviewer trick.

review/00-how-to-use.md · 2.1 KB

review/00-how-to-use.md

# How to use the review passes

## The frame every pass shares

Each pass opens with the same three instructions, because they are what
separate a useful review from a list of opinions:

1. **You did not write this code.** Assume it is wrong somewhere.
2. **Every finding needs a concrete failing scenario** — specific input,
   specific state, specific wrong outcome. If you cannot produce one, it is
   a style opinion; mark it as such and put it last.
3. **Do not fix anything. Do not summarise the code as good.**

Instruction 2 does the most work. It is the difference between "this could
be a race condition" and "if two requests arrive within the same tick, both
read `count` as 4 and both write 5; the second increment is lost."

## Running them

```
Review this diff for [one class of problem].
[paste the pass]

Diff:
[paste `git diff main...HEAD`]

Spec or requirement, if there is one:
[paste]
```

Fresh session per pass, or at least a fresh session from the one that wrote
the code.

## Triage

Not every finding deserves a fix. Sort into four buckets:

- **Real bug** → fix, and add the test that would have caught it
- **Real, out of scope** → write it down as follow-up, do not fix now
- **Style opinion** → ignore unless it makes review harder
- **Wrong** → say why. A reviewer misreading the code is often a signal the
  code is hard to read.

The third bucket is where reviews go to die. If more than half the findings
are style opinions, the pass was too broad — use a narrower one.

## Two reviewers

For anything high-stakes, run the same pass twice in separate sessions.

- Findings in both → act first
- Findings in one → look
- Disagreement between them → the code is ambiguous enough that two careful
  readers disagree, which is itself worth fixing

## What these passes will not do

They read the diff. They do not know your architecture, your team's history,
or why the weird thing is weird. They will occasionally flag something that
is correct for a reason not visible in the change.

That is fine. The cost of a false positive is one sentence. The cost of the
bug it would have caught is not.

That was one of 20 files

The rest of Review & Repair is written the same way. $29 once, yours permanently, 14-day refund.

# How to use the review passes ## The frame every pass shares Each pass opens with the same three instructions, because they are what separate a useful review from a list of opinions: 1. **You did not write this code.** Assume it is wrong somewhere. 2. **Every finding needs a concrete failing scenario** — specific input, specific state, specific wrong outcome. If you cannot produce one, it is a style opinion; mark it as such and put it last. 3. **Do not fix anything. Do not summarise the code as good.** Instruction 2 does the most work. It is the difference between "this could be a race condition" and "if two requests arrive within the same tick, both read `count` as 4 and both write 5; the second increment is lost." ## Running them ``` Review this diff for [one class of problem]. [paste the pass] Diff: [paste `git diff main...HEAD`] Spec or requirement, if there is one: [paste] ``` Fresh session per pass, or at least a fresh session from the one that wrote the code. ## Triage Not every finding deserves a fix. Sort into four buckets: - **Real bug** → fix, and add the test that would have caught it - **Real, out of scope** → write it down as follow-up, do not fix now - **Style opinion** → ignore unless it makes review harder - **Wrong** → say why. A reviewer misreading the code is often a signal the code is hard to read. The third bucket is where reviews go to die. If more than half the findings are style opinions, the pass was too broad — use a narrower one. ## Two reviewers For anything high-stakes, run the same pass twice in separate sessions. - Findings in both → act first - Findings in one → look - Disagreement between them → the code is ambiguous enough that two careful readers disagree, which is itself worth fixing ## What these passes will not do They read the diff. They do not know your architecture, your team's history, or why the weird thing is weird. They will occasionally flag something that is correct for a reason not visible in the change. That is fine. The cost of a false positive is one sentence. The cost of the bug it would have caught is not.