Phase 4: Review

Purpose

Fresh eyes on the implementation. Catch what the implementer missed.

Process

1. Select review capabilities:

   • Code review skills available?
   • Security scanning tools/MCP servers?
   • Performance analysis tools?
   • Documentation generators?
   • Assign appropriate tools to review tasks

2. Spawn code review subagent: The review subagent is separate from implementation to ensure fresh perspective.

   Subagent receives:

   • The approved spec (docs/plans/)
   • The git diff of all changes
   • The verification matrix (docs/scratch//verify.md)
   • Project coding conventions (from CLAUDE.md)

   Subagent does NOT receive:

   • Implementation reasoning or scratch notes
   • The implementer's context (forces independent analysis)

3. Review checklist:

   Spec adherence:

   • Every spec requirement has corresponding code
   • No code exists without spec justification
   • Edge cases handled as specified

   Code quality:

   • Follows project conventions
   • No obvious bugs or logic errors
   • Error handling is appropriate
   • No security vulnerabilities (injection, auth issues, etc.)

   Simplicity:

   • No over-engineering
   • No unnecessary abstractions
   • No dead code or commented-out code
   • Could this be simpler while meeting spec?

   Maintainability:

   • Code is readable without comments explaining the obvious
   • Names are clear and consistent
   • Complex logic has explanatory comments

4. Review output: Write to docs/scratch//review.md:

   ## Summary
   PASS / PASS WITH NOTES / NEEDS CHANGES
   
   ## Issues Found
   - [CRITICAL] <issue> - must fix before merge
   - [SUGGESTION] <issue> - consider changing
   - [NIT] <issue> - minor, optional
   
   ## Scope Compliance
   - All changes justified by spec: YES/NO
   - Unjustified additions: <list>
   
   ## Positive Notes
   - <things done well>
   

5. Handle review feedback:

   • CRITICAL issues: Fix, re-verify (Phase 3), re-review
   • SUGGESTIONS: Discuss with user at checkpoint
   • NITS: Fix or ignore based on user preference

Checkpoint

Present review summary to user:

• Review status (PASS/NEEDS CHANGES)
• Critical issues (if any)
• Suggestions for discussion
• Request final approval to merge/complete

Escalation

• Review reveals fundamental design flaw
• Reviewer and implementer disagree on approach
• Security vulnerability detected