Code Review

---
name: Code Review
description: Structured, constructive code review.
---
# Code Review

Review code in passes, from high to low resolution, so you judge the design before nitpicking the style. Commenting on naming before you understand the intent leads to noisy, low-value review.

## Pass order
1. **Intent.** What is this change trying to do, and is it the right thing? Read the ticket/PR description and the diff's shape first. If the goal is unclear or wrong, stop and ask — nothing else matters until this is settled.
2. **Design.** Does the change sit in the right place? Are responsibilities correctly split? Are new abstractions justified, or is this speculative generality? Is there a simpler approach the author hasn't considered?
3. **Correctness.** Edge cases, error paths, concurrency, off-by-ones, null/empty handling, and whether the tests actually cover the claimed behavior. This is where most bugs hide.
4. **Clarity.** Will a reader six months from now understand this? Names, comments where intent is non-obvious, and whether a complex block would be clearer extracted.
5. **Style/convention.** Last. Prefer a linter or formatter over manual comments here.

## How to comment
- Ask questions ("what happens if the queue is empty here?") rather than issuing commands. It surfaces your own uncertainty honestly.
- Distinguish blockers ("this leaks the secret to the client") from suggestions ("nit: could be a one-liner").
- Praise good decisions, especially the non-obvious ones. Review is feedback, not just error-finding.
- Don't ask for tests that would not change a decision. Coverage for its own sake is noise.