Use after implementation completes to verify work against spec and context. Triggers: "review this", "check the implementation", task/phase complete, before merge.
Verify implementation against spec and context. Catch what escaped execution.
Load Context → Spec Compliance → Code Quality → Artifact Verification → Report
# From planning
Read history/<topic>/CONTEXT.md
Read history/<topic>/phase-1-spec.md
# Current diff
git diff <base>..<head>
From CONTEXT.md:
From phase-spec.md:
Compare implementation against locked requirements.
| Check | Source | Method |
|---|---|---|
| Each requirement implemented | CONTEXT.md R1, R2... | Code inspection |
| Constraints honored | CONTEXT.md constraints | Code inspection |
| Exit state achieved | phase-spec.md | Functional test |
| Stories complete | phase-spec.md "done when" | Verification command |
## Spec Compliance
| Requirement | Status | Evidence |
|-------------|--------|----------|
| R1: {desc} | PASS/FAIL | {file:line or test output} |
| R2: {desc} | PASS/FAIL | {evidence} |
| Constraint | Status | Evidence |
|------------|--------|----------|
| {constraint} | HONORED/VIOLATED | {evidence} |
If any FAIL/VIOLATED: Create P1 finding. Do not proceed until acknowledged.
| Dimension | Check |
|---|---|
| Correctness | Logic errors, edge cases, error handling |
| Security | Injection, auth, secrets, data exposure |
| Performance | O(n²) loops, unnecessary allocations, N+1 queries |
| Maintainability | Naming, complexity, coupling |
| Test coverage | Missing tests, edge cases, integration gaps |
Critical: Review only sees:
Do NOT include session history or implementation notes. Objectivity requires seeing only work product.
3-level check on every deliverable from spec.
ls <expected-file-path>
Scan for anti-patterns:
return null / return {} / return []
Empty handlers: onClick={() => {}}
TODO / FIXME / PLACEHOLDER
console.log-only implementations
API routes returning static data
# Check if actually imported/used
Grep pattern="<component/function>" path="src/"
| Artifact | L1 Exists | L2 Substantive | L3 Wired | Status |
|---|---|---|---|---|
| {file} | YES/NO | YES/STUB | YES/NO | OK/P1/P2 |
| Priority | Criteria | Action |
|---|---|---|
| P1 | Security, data corruption, spec violation, missing feature | Blocks merge |
| P2 | Performance, architecture, reliability | Should fix |
| P3 | Minor improvements, cleanup, style | Record for later |
## Finding: {title}
**Severity:** P1/P2/P3
**Location:** {file}:{line}
**Spec Reference:** {R1/D2/Story 1 or "code quality"}
### Issue
{Plain language: what the code does today}
### Effect
{What breaks if not fixed — concrete scenario}
### Evidence
{Code snippet or command output}
### Fix
{Smallest credible fix direction}
# Review Report: {feature}
**Date:** YYYY-MM-DD
**Scope:** {files reviewed}
**Base:** {commit}
**Head:** {commit}
## Spec Compliance
- Requirements: {N}/{total} pass
- Constraints: {N}/{total} honored
- Exit state: ACHIEVED/NOT ACHIEVED
## Findings Summary
- P1 (blocking): {count}
- P2 (should fix): {count}
- P3 (minor): {count}
## P1 Findings (if any)
{list with full details}
## P2 Findings
{list}
## P3 Findings
{list}
## Artifacts
{3-level verification table}
## Verdict
PASS / PASS WITH ISSUES / BLOCKED
## Next Steps
- [ ] {action items}
If any P1 findings exist:
Before ANY completion claim:
| Situation | Action |
|---|---|
| Spec requirement missing | P1 finding |
| Constraint violated | P1 finding |
| Stub/placeholder found | P1 finding |
| Security issue | P1 finding |
| Performance concern | P2 finding |
| Missing test | P2 finding |
| Style/cleanup | P3 finding |
| Artifact exists but not wired | P2 finding |
| Don't | Do |
|---|---|
| Review from session memory | Review from diff + spec only |
| "Looks good" without evidence | Run verification commands |
| Skip artifact verification | Check all 3 levels |
| Vague findings | Specific file:line + effect |
| All P1 severity | Calibrate: P2 is default |
After review complete:
Review complete for {feature}.
**Verdict:** {PASS/PASS WITH ISSUES/BLOCKED}
Findings:
- P1: {count} (blocking)
- P2: {count}
- P3: {count}
{If BLOCKED: must fix P1 before proceeding}
{If PASS WITH ISSUES: recommend fixing P2 before merge}
{If PASS: ready for merge}
Artifacts:
- Review report: history/<topic>/review-report.md