Team mechanics

The code review that actually helps

A good review is not a scavenger hunt for style nits. It is a fast, careful pass over the parts that can hurt users, future readers, or production.

~5 minCoding
scroll
01 · the job

Review the change, not the author

The best reviews have a narrow ego footprint. They ask: does this change solve the right problem, preserve the contract, keep failure modes visible, and leave the next person a path through the code? Everything else is secondary.

The reviewer owns the health of the codebase. The author owns the patch. A useful review helps both.stdout reviewer note
change looks calm

A tiny patch rarely touches only one thing. Push it and watch the review surface appear.

02 · the pass

Read from the outside in

Start with the user-facing behavior, public API, data shape, and tests. Then read the implementation. That order catches the real bugs: the endpoint changed shape, the migration misses old rows, the background job retries forever, or the test proves the mock instead of the feature.

zsh · review checklist

A review pass that stays focused.

03 · the comment

Make blockers unmistakable

A blocker should name the bad outcome and the fix direction. A suggestion should sound like a suggestion. Mixing those two wastes time because the author has to reverse-engineer priority from tone.

review-comment.txt

Priority is part of the message.

change confidence lab
guessy
safe0
fragile: this change still depends on hope and a lucky deploy

Flip the switches and watch the story turn into a tiny operating model.

04 · the finish

The fastest review is the one with trust in it

Small PRs, clear tests, and direct comments create speed. Not because people type faster, but because there is less guessing. The review becomes a shared debugging session instead of a courtroom transcript.

source trail