Code Review

Code Review

Guide proper code review practices emphasizing technical rigor, evidence-based claims, and verification over performative responses.

Overview

Code review requires three distinct practices:

1. Receiving feedback - Technical evaluation over performative agreement 2. Requesting reviews - Systematic review processes 3. Verification gates - Evidence before any completion claims

Core Principle

Technical correctness over social comfort. Verify before implementing. Ask before assuming. Evidence before claims.

When to Use

Receiving Feedback

• Receiving code review comments from any source
• Feedback seems unclear or technically questionable
• Multiple review items need prioritization
• External reviewer lacks full context
• Suggestion conflicts with existing decisions

Requesting Review

• Completing tasks in subagent-driven development (after EACH task)
• Finishing major features or refactors
• Before merging to main branch
• Stuck and need fresh perspective
• After fixing complex bugs

Verification Gates

• About to claim tests pass, build succeeds, or work is complete
• Before committing, pushing, or creating PRs
• Moving to next task
• Any statement suggesting success/completion

Quick Decision Tree

SITUATION?
│
├─ Received feedback
│  ├─ Unclear items? → STOP, ask for clarification first
│  ├─ From human partner? → Understand, then implement
│  └─ From external reviewer? → Verify technically before implementing
│
├─ Completed work
│  ├─ Major feature/task? → Request systematic review
│  └─ Before merge? → Request systematic review
│
└─ About to claim status
   ├─ Have fresh verification? → State claim WITH evidence
   └─ No fresh verification? → RUN verification command first

CI Verification

Before any completion claim or commit:

• Run CI checks (types, tests, lint)
• Prefer single CI command if available
• Verify all checks pass
• Do not proceed if checks fail

References

For detailed protocols, see:

• references/receiving-feedback.md - How to handle code review feedback
• references/requesting-review.md - Systematic review processes
• references/verification-gates.md - Evidence before claims protocol

Receiving Code Review Feedback

Response Pattern

READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT

Key Rules

• ❌ No performative agreement: "You're absolutely right!", "Great point!", "Thanks for [anything]"
• ❌ No implementation before verification
• ✅ Restate requirement, ask questions, push back with technical reasoning, or just start working
• ✅ If unclear: STOP and ask for clarification on ALL unclear items first
• ✅ YAGNI check: grep for usage before implementing suggested "proper" features

Source Handling

• Human partner: Trusted - implement after understanding, no performative agreement
• External reviewers: Verify technically correct, check for breakage, push back if wrong

Response Examples

Bad - Performative:

"Great point! I'll fix that right away!"
"Thanks for the feedback, I'll implement this."
"You're absolutely right about that."

Good - Technical:

"Checking if this breaks existing functionality first."
"Verifying the requirement - grep shows this pattern is used in 3 places."
"Implementing after confirming the edge case."

Handling Unclear Feedback

1. STOP implementation 2. List ALL unclear items 3. Ask specific questions 4. Wait for clarification 5. Then proceed

Technical Evaluation

Before implementing any feedback:

• Verify it's technically correct
• Check for potential breakage
• Consider alternative approaches
• Push back with reasoning if wrong

Requesting Code Review

When to Request

• After each task in subagent-driven development
• After major feature completion
• Before merge to main
• When stuck and need fresh perspective
• After fixing complex bugs

Review Process

1. Prepare context:

• What was implemented
• Plan or requirements
• Git SHAs (BASE_SHA, HEAD_SHA)
• Description of changes

2. Request review:

• Use systematic review process
• Provide full context
• Include relevant files

3. Act on feedback:

• Fix Critical issues immediately
• Address Important before proceeding
• Note Minor for later consideration

Review Checklist

• [ ] Functionality works as intended
• [ ] Edge cases handled
• [ ] Error handling appropriate
• [ ] Code follows project conventions
• [ ] Tests are present and passing
• [ ] No obvious bugs or logic errors
• [ ] Security considerations addressed
• [ ] Performance implications considered

Integration with Workflows

• Subagent-Driven: Review after EACH task
• Pull Requests: Request review before merge
• Feature Completion: Review before marking done

Verification Gates

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

Gate Function

IDENTIFY command → RUN full command → READ output → VERIFY confirms claim → THEN claim

Skip any step = not verifying

Requirements

• Tests pass: Test output shows 0 failures
• Build succeeds: Build command exit 0
• Bug fixed: Test original symptom passes
• Requirements met: Line-by-line checklist verified

Red Flags - STOP

• Using "should"/"probably"/"seems to"
• Expressing satisfaction before verification
• Committing without verification
• Trusting agent reports without evidence
• ANY wording implying success without running verification

Verification Commands

Before claiming success, run:

Preferred: Single CI Command

pnpm ci  # or npm run ci, just ci, make ci

Fallback: Individual Checks

# Type checking
pnpm typecheck  # or tsc --noEmit, mypy .

# Tests
pnpm test  # or pytest, cargo test

# Lint
pnpm lint  # or ruff check, cargo clippy

Always verify CI passes before staging or committing changes.

Evidence Format

Bad - No evidence:

"Tests should pass now."
"Build probably works."
"Looks good to me."

Good - With evidence:

"Tests pass: Ran `npm test`, output shows 0 failures."
"Build succeeds: `npm run build` completed with exit code 0."
"Bug fixed: Original test case now passes."

Integration

• Before committing
• Before pushing
• Before creating PRs
• Before moving to next task
• Before any completion claim