Code Review

---
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:

1. **Compare implementation against the spec/plan** — requirement by requirement
2. **Is anything missing?** — features specified but not implemented
3. **Is anything extra?** — features added that weren't requested (YAGNI violation — remove them)
4. **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

1. **Error handling** — are errors caught, logged, and handled appropriately? Are edge cases covered?
2. **Type safety** — proper types, no `any` unless justified, interfaces match contracts
3. **Naming** — clear, descriptive, consistent with codebase conventions
4. **Organization** — separation of concerns, single responsibility, loose coupling
5. **Test coverage** — are tests meaningful? Do they test behavior, not implementation?
6. **Security** — input validation, no hardcoded secrets, SQL injection, XSS
7. **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