Hankliu447 Superspec Code Review

Code Review

Overview

Catch issues before they cascade. Review early, review often.

Core principle: Two-stage review ensures both correctness AND quality.

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

When to Request Review

Mandatory:

• After each task in subagent-driven development
• After completing major feature
• Before merge to main
• Before running /superspec:archive

Optional but valuable:

• When stuck (fresh perspective)
• Before refactoring (baseline check)
• After fixing complex bug

Two-Stage Review Process

┌─────────────────────────────────────────────────────────────────┐
│                    Two-Stage Review                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│   Stage 1: Spec Compliance Review                                │
│   └─→ Does implementation match Specs?                          │
│   └─→ Every Requirement implemented?                             │
│   └─→ Every Scenario has test?                                   │
│   └─→ No missing/extra features?                                 │
│                                                                   │
│        [Must pass before Stage 2]                                │
│                                                                   │
│   Stage 2: Code Quality Review                                    │
│   └─→ Error handling                                             │
│   └─→ Type safety                                                │
│   └─→ SOLID principles                                           │
│   └─→ Test quality                                               │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

Stage 1: Spec Compliance Review

What to Check

1. Requirement Coverage

   • Does implementation match the Requirement description?
   • Are all SHALL/MUST statements implemented?

2. Scenario Coverage

   • Is there a test for each Scenario?
   • Does the test cover WHEN condition?
   • Does the test verify THEN result?
   • Does the test verify AND conditions (if any)?

3. No Missing Features

   • Are all aspects of the Scenario tested?
   • Any edge cases in the Scenario not covered?

4. No Extra Features

   • Is there any code NOT required by the Spec?
   • Any "nice to have" additions not in Spec?

Review Checklist

## Spec Compliance Review

### Requirement: [Name]
[✅ COMPLIANT / ❌ NOT COMPLIANT]

### Scenario: [Name]
- Test exists: [✅/❌]
- WHEN covered: [✅/❌]
- THEN verified: [✅/❌]
- AND verified: [✅/❌ or N/A]

### Issues Found
1. [Issue description] - [Missing/Extra/Incorrect]

### Verdict
[✅ SPEC COMPLIANT / ❌ NEEDS WORK]

If not compliant, list specific fixes needed.

If Spec Review Fails

1. Fix issues found
2. Request re-review
3. Repeat until compliant
4. Do NOT proceed to Quality Review until Spec Review passes

Stage 2: Code Quality Review

What to Check

1. Error Handling

   • Are errors caught appropriately?
   • Are error messages helpful?
   • No swallowed errors?

2. Type Safety

   • Proper TypeScript types?
   • No any without justification?
   • Null/undefined handled?

3. Code Quality

   • SOLID principles followed?
   • No code duplication?
   • Clear naming?
   • Appropriate abstraction level?

4. Test Quality

   • Tests are focused (one thing)?
   • Tests are readable?
   • No testing implementation details?
   • Mocks used appropriately?

Issue Classification

• Critical: Must fix before proceeding
• Important: Should fix, impacts maintainability
• Suggestion: Nice to have, optional

Review Output

## Code Quality Review

### Strengths
- [Good things about the code]

### Issues

#### Critical
1. [Issue] - [Why it's critical] - [Suggested fix]

#### Important
1. [Issue] - [Impact] - [Suggested fix]

#### Suggestions
1. [Suggestion] - [Benefit]

### Verdict
[✅ APPROVED / ❌ NEEDS WORK]

If needs work, list required fixes (Critical + Important).

If Quality Review Fails

1. Fix Critical and Important issues
2. Request re-review
3. Repeat until approved
4. Suggestions are optional

How to Request Review

1. Get Git Context

BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

2. Prepare Review Request

## Review Request

**Change ID:** [change-id]
**Spec Files:**
- superspec/changes/[id]/specs/[cap]/spec.md

**Task Completed:**
- Requirement: [Name]
- Scenario: [Name]

**Code Changes:**
[Git diff or file paths]

**Base SHA:** [BASE_SHA]
**Head SHA:** [HEAD_SHA]

3. Act on Feedback

• Fix Critical issues immediately
• Fix Important issues before proceeding
• Note Suggestions for later
• Push back if reviewer is wrong (with reasoning)

Quick Reference

Red Flags

Never:

• Skip review because "it's simple"
• Ignore Critical issues
• Proceed with unfixed Important issues
• Do Quality review before Spec review
• Accept "close enough" for Spec compliance

If reviewer wrong:

• Push back with technical reasoning
• Show code/tests that prove it works
• Request clarification

Integration with Subagent Development

In subagent-driven development, reviews happen automatically:

1. Implementer completes task
2. Spec Reviewer checks compliance
3. Quality Reviewer checks code quality
4. Issues found → Implementer fixes → Re-review
5. Both pass → Mark task complete

See subagent-development skill for full workflow.

Related References

Prompt templates (for subagent dispatch):

• code-reviewer.md - Full code reviewer subagent template with placeholders

Handling review feedback:

• receiving-code-review skill - How to respond to review feedback professionally

Integration

Called by:

• subagent-development - Per-task reviews
• Before verify - Ensure quality before verification
• Before finish-branch - Final check before integration

Pairs with:

• tdd - Reviews should verify TDD was followed
• verify - Reviews complement verification
• verification-before-completion - Evidence before claims

Converted and distributed by TomeVault — claim your Tome and manage your conversions.