Code review guidelines

Most of what slows code review down is not the reviewing. It is receiving a pull request that cannot be reviewed yet: conflicts, a red pipeline, no description, no ticket, changes from three unrelated pieces of work in the same diff.

Fixing the input is most of the fix. The rest of it is automatable, and the parts a machine can check are the parts a human should never spend attention on: style, formatting, ticket linking, commit message shape, security scanning.

What a pull request owes its reviewer

1. All the changes, and nothing else. Reviewers cannot see what you left on your machine, and they should not have to skip past an unrelated refactor.
2. A clean merge into main. If it has conflicts or needs a rebase, it is not ready for review.
3. A title that says what the change does.
4. A description, once the change is large or subtle enough that the diff does not explain itself.
5. The ticket ID, either leading the title (PRJ-123: add the Preferred badge to the hotel card) or in the description as Solves PRJ-123. Pick one convention and let automation depend on it.
6. A green pipeline. Tests, linters and security checks all pass, or the pull request is not ready and the reviewer's time is being spent on a draft.

What a reviewer owes the author

1. Speed. Review time is the author's blocked time, and a pull request waiting overnight is a pull request that will need rebasing tomorrow.
2. Questions before corrections. Ask what the author was solving before proposing something else. Often the something else does not work, for a reason the author already found.
3. Participation from everyone. Not just the seniors. Experienced developers make mistakes, and reviewing is how newer developers learn the codebase faster than by writing in it.
4. Objectivity. Distinguish a defect from a preference. If it is a preference, say so, and let the author decide. If the preference is worth enforcing, it belongs in the linter, not in a comment thread.
5. Directness without unkindness. You are reviewing the change, and the person who wrote it is going to read what you wrote.

Where agents fit

An agent can hold every one of the mechanical rules above and apply them consistently at any hour, which makes it a better first reviewer than a person. Let it take the pass that checks the diff against the ticket, flags the obvious defects, and tells the author what is missing before a human opens the tab.

What it does not replace is the judgement call about whether this is the right change to make. That still needs someone who knows what the team decided last month and why.