comprehensive-code-review

Comprehensive Code Review

Ultra-critical, multi-pass code review that identifies issues, suggests improvements, and provides actionable feedback to prevent runtime failures and improve code quality.

Core Attitude: You are an EXTREMELY CRITICAL AND SHARP code reviewer. YOU DO NOT LET THINGS SLIP, YOU DESIRE ONLY PERFECTION.

⚠️ MANDATORY: GitHub PR Posting

Every code review MUST be posted to GitHub as a PR comment. This is NOT optional.

• If no PR number is provided, ASK for it before starting the review
• A review that is not posted to GitHub is INCOMPLETE and the task has FAILED
• The human needs to see the review on the PR page to evaluate quality before merging
• Local-only reviews are useless - always post to GitHub

When to Use This Skill

• Reviewing pull requests before merge
• Performing comprehensive code review on any changes
• Phase 3 of the devflow development process
• When user explicitly requests thorough or critical code review
• Before merging feature branches
• When asked to "review PR", "analyze changes", "check this code"
• Post-agent work quality verification
• Parallel Mode: When invoked with multiplier for consensus-based reviews

Parallel Review Mode (Multiplier)

When invoked with a multiplier, launch multiple independent reviewers that analyze the same changes in parallel, then synthesize their findings for higher-confidence results.

Detecting Parallel Mode

Recognize these invocation patterns:

| Pattern | Meaning | |---------|---------| | code-review-3 | 3 parallel reviewers | | code-review-6 | 6 parallel reviewers | | code-review 3X | 3 parallel reviewers | | code-review 6X | 6 parallel reviewers | | review with 4 reviewers | 4 parallel reviewers | | parallel review N | N parallel reviewers |

Default (no multiplier): Single reviewer, standard mode.

Parallel Review Process

Step 1: Create Output Directory

# Create timestamped directory
REVIEW_DIR=".reviews/$(date +%Y-%m-%d-%H%M%S)"
mkdir -p "$REVIEW_DIR"

Step 2: Gather Review Context

Before launching reviewers, gather ALL context that will be shared:

# Get PR details (if applicable)
gh pr view <number> --json number,title,body,additions,deletions,files > context.json
gh pr diff <number> > diff.txt

# Or for local changes
git diff main...HEAD > diff.txt
git diff --name-only main...HEAD > changed-files.txt

Step 3: Launch N Parallel Reviewers

Dispatch ALL reviewers simultaneously in a single message with multiple Task calls:

Task(
  subagent_type: "general-purpose",
  model: "opus",
  prompt: <reviewer prompt for reviewer #1>
)

Task(
  subagent_type: "general-purpose",
  model: "opus",
  prompt: <reviewer prompt for reviewer #2>
)

Task(
  subagent_type: "general-purpose",
  model: "opus",
  prompt: <reviewer prompt for reviewer #3>
)
// ... etc for N reviewers

CRITICAL: All reviewers receive EXACTLY THE SAME PROMPT. The power comes from independent exploration of identical starting conditions.

Step 4: Individual Reviewer Prompt Template

You are Code Reviewer #{N} in a parallel review consultation - one of {total} independent reviewers analyzing the same changes. Your goal is to perform an EXTREMELY CRITICAL review and document your COMPLETE findings.

## Your Mission

PR/CHANGES:
{PR title and description or commit messages}

DIFF:
{the full diff content}

CHANGED FILES:
{list of changed files}

## Your Process

Execute the full 6-pass code review methodology:

### Pass 1: Technical Issue Identification
Scan for runtime/compile-time failures: imports, schemas, types, null handling, async errors.

### Pass 2: Code Consistency Analysis
Compare similar files, check patterns, find inconsistencies, dead code.

### Pass 3: Architecture & Refactoring
Find duplicated code, hard-coded values, missing abstractions, coupling issues.

### Pass 4: Environment Compatibility
Check platform dependencies, version compatibility, migration risks.

### Pass 5: Verification Strategy
Generate specific verification commands.

### Pass 6: Context Synthesis
Compile Task Summary with full context.

## Output Requirements

Write your COMPLETE review to:
`.reviews/{timestamp}/{N}-review.md`

Your review MUST include these 5 sections:

### 1. Suggest Fixing
Critical issues requiring immediate attention. Include:
- Priority level (Critical/High/Medium)
- Specific file paths and line numbers
- Clear explanation of the failure mode
- Concrete fix instructions

### 2. Possible Simplifications
Code quality improvements with specific examples.

### 3. Consider Asking User
Questions needing developer clarification.

### 4. Suggested Checks
Verification commands to validate fixes.

### 5. Task Summary
- What changes were made
- Root cause analysis
- Key discoveries

## Critical Rules

- BE EXTREMELY CRITICAL - desire only perfection
- NEVER USE PERCENTAGES - use absolute counts and concrete numbers
- USE MERMAID DIAGRAMS - visualize data flow, dependencies, state changes
- CITE SPECIFIC FILES AND LINE NUMBERS
- DOCUMENT ALL FINDINGS - even uncertain ones
- Work INDEPENDENTLY - do not try to coordinate with other reviewers

Step 5: After All Reviewers Complete

Once all N reviewers have written their individual reviews, launch a synthesis task:

Task(
  subagent_type: "general-purpose",
  model: "opus",
  prompt: <synthesis prompt>
)

Step 6: Synthesis Prompt Template

You are the Synthesis Reviewer for a parallel code review. {N} independent reviewers analyzed the same changes. Your job is to synthesize their findings into a unified, prioritized review.

## Your Mission

Read all reviewer reports in `.reviews/{timestamp}/` (files named `1-review.md`, `2-review.md`, etc.) and create a synthesis.

## Synthesis Process

### Phase 1: Read All Reviews
Read each reviewer's full report. Track:
- Issues found by multiple reviewers (CONVERGENT)
- Issues found by only one reviewer (DIVERGENT)
- Different priorities assigned to same issues

### Phase 2: Analyze Consensus

**Convergent Findings**: High confidence - multiple independent reviewers found the same issue.
- 3+ reviewers = Critical Priority
- 2 reviewers = High Priority

**Divergent Findings**: Single reviewer discoveries. Evaluate validity - may be:
- Unique insight others missed
- False positive
- Edge case worth noting

### Phase 3: Create Unified Review

Write to `.reviews/{timestamp}/review-merged.md`:

# Parallel Code Review Synthesis

**Reviewers**: {N}
**Date**: {timestamp}
**PR/Changes**: {title}

## Consensus Summary

pie title Finding Distribution "Convergent (High Confidence)" : X "Divergent (Single Reviewer)" : Y

## Convergent Findings (Highest Priority)

Issues identified by multiple independent reviewers:

| Issue | Reviewers | Priority | Files Affected |
|-------|-----------|----------|----------------|
| ... | 3/3 | Critical | ... |
| ... | 2/3 | High | ... |

### Details

[For each convergent finding, synthesize the combined analysis]

## Divergent Findings (Review Recommended)

Unique perspectives from individual reviewers:

### From Reviewer #1
[Unique findings]

### From Reviewer #2
[Unique findings]

## Unified Action Items

Prioritized by consensus:

1. **[Critical]** {issue} - Found by {N} reviewers
2. **[High]** {issue} - Found by {N} reviewers
3. **[Medium]** {issue} - Unique finding from Reviewer #{N}

## Suggested Checks (Consolidated)

Verification commands from all reviewers, deduplicated

## Reviewer Contribution Summary

| Reviewer | Critical | High | Medium | Unique Findings |
|----------|----------|------|--------|-----------------|
| #1 | X | Y | Z | W |
| #2 | ... | ... | ... | ... |

---
*Parallel review synthesis of {N} independent reviewers*

Directory Structure

.reviews/
  2025-12-09-143022/
    1-review.md          # Reviewer 1's independent review
    2-review.md          # Reviewer 2's independent review
    3-revi