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
1---2name: code-review3description: 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.4---56# Code Review78## Two-Stage Review Process910### Stage 1: Spec Compliance1112Before assessing quality, verify the code does what was asked:13141. **Compare implementation against the spec/plan** — requirement by requirement152. **Is anything missing?** — features specified but not implemented163. **Is anything extra?** — features added that weren't requested (YAGNI violation — remove them)174. **Are deviations justified?** — if the implementation differs from the plan, is it a genuine improvement or a problematic departure?1819**If spec compliance fails:** Fix gaps before moving to Stage 2. Don't review quality of incomplete work.2021### Stage 2: Code Quality22231. **Error handling** — are errors caught, logged, and handled appropriately? Are edge cases covered?242. **Type safety** — proper types, no `any` unless justified, interfaces match contracts253. **Naming** — clear, descriptive, consistent with codebase conventions264. **Organization** — separation of concerns, single responsibility, loose coupling275. **Test coverage** — are tests meaningful? Do they test behavior, not implementation?286. **Security** — input validation, no hardcoded secrets, SQL injection, XSS297. **Performance** — obvious N+1 queries, unnecessary re-renders, missing indexes3031### Issue Categories3233- **Critical** (must fix) — blocks merge, breaks functionality, security vulnerability34- **Important** (should fix) — code smell, missing edge case, poor naming, missing test35- **Suggestion** (nice to have) — style preference, minor optimization, alternative approach3637### Review Output Format3839```40## Spec Compliance: ✅ PASS / ❌ FAIL4142[If FAIL: list missing/extra items]4344## Code Quality4546### Strengths47- [What was done well — always acknowledge before critiquing]4849### Critical Issues50- [File:line] Description. Fix: [specific suggestion]5152### Important Issues53- [File:line] Description. Fix: [specific suggestion]5455### Suggestions56- [File:line] Description. Consider: [alternative]5758## Verdict: APPROVED / CHANGES REQUESTED59```6061### Principles6263- **Always acknowledge what was done well** before highlighting issues64- **Be specific** — file, line, concrete suggestion, not vague "improve error handling"65- **Provide code examples** for non-obvious fixes66- **Don't nitpick style** if the codebase has no established convention67- **Check the tests** — are they testing real behavior or mock existence?68- **Verify independently** — don't trust claims, check the actual code/output
burhankhatri