| name | automatic-code-review |
| description | How to conduct and receive effective code reviews. Use when reviewing a PR, requesting review, or improving review quality. |
| authors | ["Automatic"] |
Code Review
Code review is a quality gate and a knowledge-sharing mechanism. Its purpose is to catch defects, surface design problems, and spread understanding — not to enforce style preferences or demonstrate superiority.
Mindset
Review the code, not the person. Every comment should serve the goal of shipping better software. Assume good intent; ask questions before making accusations.
What to Look For
Correctness (highest priority)
- Does the code do what it claims to do?
- Are there edge cases that are not handled? (null, empty, overflow, concurrency)
- Are error states handled explicitly, or silently swallowed?
- Does it match the requirements or specification?
Security
- Is user input validated and sanitised before use?
- Are secrets or credentials ever logged or exposed?
- Are permissions and authorisation checks in the right place?
- See the
security-review skill for a full checklist
Design
- Does the change fit the existing architecture, or does it introduce inconsistency?
- Is responsibility correctly assigned — does each function/class do one thing?
- Are dependencies pointing in the right direction?
- Would a future maintainer understand this without asking the author?
Testability and tests
- Is the new code covered by tests?
- Do the tests verify behaviour, not implementation?
- Would a failing test give a clear signal about what broke?
Performance
- Are there obvious algorithmic issues (N+1 queries, O(n²) in a hot path)?
- Are expensive operations cached where appropriate?
- For critical paths, is there evidence of measurement rather than assumption?
Maintainability
- Are names clear and specific?
- Is duplication introduced that could be extracted?
- Are there comments that explain why, not just what?
- Is dead code removed?
How to Comment
Be specific. Vague comments waste everyone's time.
// Bad: "This could be better"
// Good: "This will execute a database query for every item in the list.
// Consider fetching all items in a single query before the loop."
Label the severity. Not all comments are blockers.
[blocking] — must be resolved before merge; correctness or security issue[suggestion] — improvement worth discussing; not required[nit] — minor style or preference; take it or leave it[question] — asking for understanding, not requesting a change
Suggest, do not just criticise. If you identify a problem, offer a direction for fixing it.
Scope
Review what was changed. Do not block a PR because of pre-existing issues in surrounding code — create a separate ticket for those. Do not add scope to a PR during review.
For Authors
Before requesting review:
When receiving feedback:
- Respond to every comment — either with a change or a rationale for not changing
- Do not silently resolve comments you disagree with; discuss them
[nit] comments are optional — you do not need to justify ignoring them
What Code Review Is Not
- A style guide enforcement tool (use a linter for that)
- A place to redesign the entire system
- A gatekeeping exercise
- A substitute for automated testing
