| name | code-review |
| description | Use when a major project step has been completed and needs review against the plan and coding standards. Also use when someone says 'review this', 'check my code', 'is this ready', or when a significant chunk of implementation is done. Use after completing tasks from an implementation plan, before creating PRs, or when asked to assess code quality. |
Code Review
Two-Stage Review Process
Stage 1: Spec Compliance
Before assessing quality, verify the code does what was asked:
- Compare implementation against the spec/plan — requirement by requirement
- Is anything missing? — features specified but not implemented
- Is anything extra? — features added that weren't requested (YAGNI violation — remove them)
- Are deviations justified? — if the implementation differs from the plan, is it a genuine improvement or a problematic departure?
If spec compliance fails: Fix gaps before moving to Stage 2. Don't review quality of incomplete work.
Stage 2: Code Quality
- Error handling — are errors caught, logged, and handled appropriately? Are edge cases covered?
- Type safety — proper types, no
any unless justified, interfaces match contracts
- Naming — clear, descriptive, consistent with codebase conventions
- Organization — separation of concerns, single responsibility, loose coupling
- Test coverage — are tests meaningful? Do they test behavior, not implementation?
- Security — input validation, no hardcoded secrets, SQL injection, XSS
- Performance — obvious N+1 queries, unnecessary re-renders, missing indexes
Issue Categories
- Critical (must fix) — blocks merge, breaks functionality, security vulnerability
- Important (should fix) — code smell, missing edge case, poor naming, missing test
- Suggestion (nice to have) — style preference, minor optimization, alternative approach
Review Output Format
## Spec Compliance: ✅ PASS / ❌ FAIL
[If FAIL: list missing/extra items]
## Code Quality
### Strengths
- [What was done well — always acknowledge before critiquing]
### Critical Issues
- [File:line] Description. Fix: [specific suggestion]
### Important Issues
- [File:line] Description. Fix: [specific suggestion]
### Suggestions
- [File:line] Description. Consider: [alternative]
## Verdict: APPROVED / CHANGES REQUESTED
Principles
- Always acknowledge what was done well before highlighting issues
- Be specific — file, line, concrete suggestion, not vague "improve error handling"
- Provide code examples for non-obvious fixes
- Don't nitpick style if the codebase has no established convention
- Check the tests — are they testing real behavior or mock existence?
- Verify independently — don't trust claims, check the actual code/output
