A first pass on every pull request

Code review has a queueing problem more than a quality problem. The reviewer is busy, the diff sits, and when it is finally read half the comments are things nobody enjoys writing: a missing test, an unhandled error, a name that contradicts what the function does.

Getting those said immediately is worth more than it sounds, because the author still has the change in their head.

Write your conventions down where they can be read

Not in a linter. Linters already catch what linters catch. What is missing is the tacit half: what you consider a public interface, when you require a test, what you do about errors you cannot handle, how you feel about comments.

Put it in Documents. A page is enough, and writing it is useful whether or not you automate anything.

Ask for a first pass, not a verdict

Review this pull request against our conventions document.

Leave findings only where you can name the specific problem and what would
go wrong. For each: the file and line, what is wrong, and the failure it
would cause.

Do not comment on style a formatter would fix. Do not restate what the code
does. Do not say "consider" anything you would not defend.

If a change looks fine, say so in one line rather than manufacturing
feedback.

Flag separately, without judging them: anything touching auth, anything
that writes to the database without a transaction, and any test that was
deleted.

"Do not manufacture feedback" is the instruction that decides whether anyone reads the second one of these. An automated reviewer that always finds three things will pad, developers learn within a week that the comments are noise, and after that a genuine finding is indistinguishable from filler. Permission to say "this looks fine" is what makes the tool credible.

Keep it out of the PR at first

Have the findings come to you, not to the pull request. You are calibrating against your own judgement, and doing that in public costs the author's attention every time it is wrong.

A week of that will tell you which categories it is good at. In most codebases it is reliably good at missing error handling and missing tests, and unreliable about architecture, which is fair enough because so is everyone.

Then post only the categories it is good at

Narrow the prompt to those and let it comment on the PR. Keep the flagged list — auth, untransactioned writes, deleted tests — coming to a human regardless, because those want a person's eyes rather than a comment.

What good looks like

A pull request has three specific, correct comments on it within a minute of opening, and the human reviewer starts from the interesting part.

The measure is not comment volume. It is whether the author fixes things before the reviewer arrives. If the comments are being ignored, they are either wrong or padded, and the fix is to narrow what it is allowed to comment on.