Code Review

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

Default (No Arguments)

If invoked with context (recent changes/PR), proceed with review. If invoked WITHOUT arguments, ask the user to choose available review operations:

Operation	Description
(default)	Review recent changes/PR
codebase	Full codebase scan & analysis
codebase parallel	Parallel multi-reviewer audit

Present options with header "Review Operation", question "What would you like to do?".

Core Principle

YAGNI, KISS, DRY always. Technical correctness over social comfort. Be honest, be brutal, straight to the point, and be concise.

Verify before implementing. Ask before assuming. Evidence before claims.

Practices

Practice	When	Reference
Receiving feedback	Unclear feedback, external reviewers, needs prioritization	references/code-review-reception.md
Requesting review	After tasks, before merge, stuck on problem	references/requesting-code-review.md
Verification gates	Before any completion claim, commit, PR	references/verification-before-completion.md
Edge case scouting	After implementation, before review	references/edge-case-scouting.md
Task-managed reviews	Multi-file features (3+ files), parallel reviewers, fix cycles	references/task-management-reviews.md

Quick Decision Tree

SITUATION?
│
├─ Received feedback → STOP if unclear, verify if external, implement if human partner
├─ Completed work → Scout edge cases → Request code_reviewer subagent
├─ Multi-file feature (3+ files) → Create review pipeline tasks (scout→review→fix→verify)
└─ About to claim status → RUN verification command FIRST

Receiving Feedback

Pattern: READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT

Rules:

• No performative agreement: "You're absolutely right!", "Great point!"
• No implementation before verification
• Restate, ask questions, push back with reasoning, or just work
• YAGNI check: grep for usage before implementing "proper" features

Source handling:

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

Full protocol: references/code-review-reception.md

Requesting Review

When: After each task, major features, before merge

Process:

1. Scout edge cases first (see below)
2. Get SHAs: BASE_SHA=$(git rev-parse HEAD~1) and HEAD_SHA=$(git rev-parse HEAD)
3. Dispatch code_reviewer subagent with: WHAT, PLAN, BASE_SHA, HEAD_SHA, DESCRIPTION
4. Fix Critical immediately, Important before proceeding

Full protocol: references/requesting-code-review.md

Edge Case Scouting

When: After implementation, before requesting code_reviewer

Process:

1. Invoke $scout with edge-case-focused prompt
2. Scout analyzes: affected files, data flows, error paths, boundary conditions
3. Review scout findings for potential issues
4. Address critical gaps before code review

Full protocol: references/edge-case-scouting.md

Task-Managed Review Pipeline

When: Multi-file features (3+ changed files), parallel code_reviewer scopes, review cycles with Critical fix iterations.

Pipeline: scout → review → fix → verify (each a Task with dependency chain)

tracked task creation: "Scout edge cases"         → pending
tracked task creation: "Review implementation"    → pending, blockedBy: [scout]
tracked task creation: "Fix critical issues"      → pending, blockedBy: [review]
tracked task creation: "Verify fixes pass"        → pending, blockedBy: [fix]

Parallel reviews: Spawn scoped code_reviewer subagents for independent file groups (e.g., backend + frontend). Fix task blocks on all reviewers completing.

Re-review cycles: If fixes introduce new issues, create cycle-2 review task. Limit 3 cycles, escalate to user after.

Full protocol: references/task-management-reviews.md

Verification Gates

Iron Law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

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

Requirements:

• Tests pass: Output shows 0 failures
• Build succeeds: Exit 0
• Bug fixed: Original symptom passes
• Requirements met: Checklist verified

Red Flags: "should"/"probably"/"seems to", satisfaction before verification, trusting agent reports

Full protocol: references/verification-before-completion.md

Integration with Workflows

• Subagent-Driven: Scout edge cases → Review after EACH task → Verify before next
• Pull Requests: Scout → Verify tests → Code-reviewer review → Merge
• Task Pipeline: Create review tasks with dependencies → auto-unblock through chain
• Cook Handoff: Cook completes phase → review pipeline tasks → all complete → cook proceeds

Codebase Analysis Subcommands

Subcommand	Reference	Purpose
$code-review codebase	references/codebase-scan-workflow.md	Scan & analyze the codebase
$code-review codebase parallel	references/parallel-review-workflow.md	Ultrathink edge cases, then parallel verify

Bottom Line

1. Technical rigor over social performance
2. Scout edge cases before review
3. Task-manage reviews for multi-file features
4. Evidence before claims

Verify. Scout. Question. Then implement. Evidence. Then claim.