Code Review

Overview

Comprehensive code review against the original plan, coding standards, and learned project patterns. This skill dispatches a dedicated code-reviewer agent for thorough analysis, ensuring every change is evidence-based, plan-aligned, and convention-aware before it reaches the main branch.

Announce at start: "I'm using the code-review skill to review the implementation."

Phase 1: Gather Context

Goal: Identify what changed, what the plan required, and what conventions apply.

Actions

1. Retrieve the changes to review:

git diff HEAD~N..HEAD          # or specific commit range
git log --oneline HEAD~N..HEAD # what was done

2. Locate the plan document:

ls docs/plans/*.md | tail -1

3. Load project conventions from memory/learned-patterns.md

4. Identify:

   • What files were changed
   • What the plan/spec required
   • What conventions apply

STOP — Do NOT proceed to Phase 2 until:

• All changed files are identified
• The plan or spec requirements are loaded
• Relevant conventions from memory are loaded
• You can state what was supposed to be built

Phase 2: Dispatch Code Reviewer

Goal: Send structured review request to the code-reviewer agent.

Review Prompt Template

Review the following changes against:
1. Plan: [plan document or requirements]
2. Conventions: [learned patterns from memory]
3. Standards: [CLAUDE.md rules]

Changes:
[git diff output or file list]

Check for:
- Plan alignment (did we build what was specified?)
- Code quality (DRY, YAGNI, naming, structure)
- Error handling (edge cases, failure modes)
- Security (injection, XSS, auth issues)
- Test coverage (are changes tested?)
- Performance (obvious bottlenecks)
- Documentation (are public APIs documented?)

STOP — Do NOT proceed to Phase 3 until:

• Review request has been dispatched
• Reviewer agent has returned findings

Phase 3: Categorize and Resolve Issues

Goal: Classify findings and fix all Critical issues.

Issue Categorization Table

Fix Loop

For Critical and Important issues:

1. Fix the issue
2. Run tests to verify the fix
3. Re-dispatch code-reviewer agent for the specific fix
4. Repeat until no Critical issues remain

STOP — Do NOT proceed to Phase 4 until:

• All Critical issues are resolved
• All Important issues are resolved or explicitly deferred with justification
• Test suite passes after all fixes

Phase 4: Self-Learning Integration

Goal: Persist patterns discovered during review for future sessions.

Actions

1. If new patterns were identified, update memory/learned-patterns.md
2. If a common mistake was found, note it for future reference
3. If the plan needed adjustment, update memory/decisions-log.md

Review Output Format

## Code Review Summary

**Scope:** [files/components reviewed]
**Plan alignment:** [aligned / minor deviations / major deviations]

### Critical Issues (N)
1. **[Issue title]** — `file:line`
   Problem: [description]
   Fix: [specific recommendation]

### Important Issues (N)
1. **[Issue title]** — `file:line`
   Problem: [description]
   Fix: [specific recommendation]

### Suggestions (N)
1. **[Suggestion]** — `file:line`

### What Was Done Well
- [Positive observations]

Decision Table: Review Depth

Anti-Patterns / Common Mistakes

Rationalizations — STOP If You Think These

Subagent Dispatch Opportunities

Follow the dispatching-parallel-agents skill protocol when dispatching.

Integration Points

Iron Law

┌─────────────────────────────────────────────────────────────────┐
│  HARD-GATE: NO MERGE WITHOUT REVIEW                            │
│                                                                 │
│  Every change gets reviewed. No exceptions for "small fixes"   │
│  or "obvious changes." If you are about to merge without       │
│  review, STOP immediately.                                     │
└─────────────────────────────────────────────────────────────────┘

Skill Type

RIGID — The four-phase process is mandatory. Every change must be reviewed by the code-reviewer agent. No merge without review. No exceptions.