Comprehensive Code Review

Run a comprehensive code review using multiple specialized agents, each focusing on a different aspect of code quality. Agents are invoked via the Agent tool and run with read-only access to the project (except code-simplifier which needs write access).

Review Aspects (optional): "$ARGUMENTS"

Step 1 — Determine Review Scope

1. Run git diff --name-only to identify unstaged changed files (this is the

default scope). If there are no unstaged changes, fall back to git diff --cached --name-only (staged changes).

1. If no changes are found at all, tell the user and stop.
2. Parse $ARGUMENTS to detect:

• Aspect selection: one or more of code, errors, comments, types,

tests, simplify, all. Default: all.

• Execution mode: parallel keyword triggers parallel mode. Default:

sequential.

1. Run git diff (or git diff --cached) to capture the full diff content —

this is what agents will review.

Display to the user:

── review-pr ──────────────────────────────────────
Scope: git diff (unstaged changes)
Files: {N} changed
Aspects: {selected aspects or "all"}
Mode: {sequential | parallel}
────────────────────────────────────────────────────

Step 1.5 — Load shared tier config

Read .review-loop/config.md if it exists. Extract:

• judgment_model: shared tier override for judgment-tier review agents
• cheap_model: shared tier override for cheap-tier review agents; if absent,

cheap-tier dispatches backstop to claude-haiku-4-5-20251001

• review_style: optional review tone / cross-cutting rules

Missing agent tier defaults to judgment.

Step 2 — Available Review Aspects

Each aspect maps to a specialized agent in the agents/ directory:

When all is selected, determine applicable aspects based on the changed files:

• Always run: code, errors, tests (catches missing tests for new code too)
• If comments or docs changed: comments
• If type definitions added/modified (interfaces, type aliases, classes): types
• `simplify` runs last when selected — it applies changes, so it goes after

all read-only reviews complete.

Step 3 — Launch Review Agents

For each applicable aspect, invoke the corresponding agent via the Agent tool.

All agents (code, errors, comments, types, tests, simplify)

Due to a known plugin agent type sandbox bug, all plugin-defined agent types have their tools silently blocked (both tools: read-only and tools: all). Therefore, all agents must be invoked via subagent_type: general-purpose with the agent's full body inlined in the prompt.

Read-only agents (code, errors, comments, types, tests):

Agent tool parameters:
  subagent_type: general-purpose
  prompt: |
    {contents of agents/<agent-name>.md body}

    Review the following code changes. Focus on your area of expertise.
    IMPORTANT: Report only, do not modify any files.

    ## Changed Files
    {list of changed file paths}

    ## Diff
    {git diff output}

    Provide your findings as a structured report with:
    - **Critical Issues** (must fix)
    - **Important Issues** (should fix)
    - **Suggestions** (nice to have)
    - **Positive Observations** (what's done well)

    Reference specific files and line numbers where possible.

Agent name mapping (all use subagent_type: general-purpose with agent body inlined):

• code → inline agents/code-reviewer.md body
• errors → inline agents/silent-failure-hunter.md body
• comments → inline agents/comment-analyzer.md body
• types → inline agents/type-design-analyzer.md body
• tests → inline agents/pr-test-analyzer.md body

Concrete dispatch inventory:

• review_pr_code_reviewer_dispatch -> code-reviewer; tier: judgment; model: {judgment_model if set; else omit}
• review_pr_silent_failure_hunter_dispatch -> silent-failure-hunter; tier: judgment; model: {judgment_model if set; else omit}
• review_pr_comment_analyzer_dispatch -> comment-analyzer; tier: cheap; model: {cheap_model if set; else claude-haiku-4-5-20251001}
• review_pr_type_design_analyzer_dispatch -> type-design-analyzer; tier: judgment; model: {judgment_model if set; else omit}
• review_pr_pr_test_analyzer_dispatch -> pr-test-analyzer; tier: cheap; model: {cheap_model if set; else claude-haiku-4-5-20251001}

Hallucination guard: After each agent returns, check the Agent tool metadata. If tool_uses: 0, the agent did not actually read files or run commands — its output is fabricated. Discard the result and retry once. If the retry also has tool_uses: 0, skip this agent and report the failure.

The simplify aspect

The code-simplifier agent modifies files to apply simplifications.

CRITICAL — plugin sandbox bug: Do NOT use subagent_type: review-loop:code-simplifier. That agent type has tools silently blocked — it will produce tool_uses: 0 hallucinated output. Always use subagent_type: general-purpose with the agent's full body inlined in the prompt:

Agent tool parameters:
  subagent_type: general-purpose
  prompt: |
    {full body of agents/code-simplifier.md — everything below the frontmatter}

    ## Changed Files to Simplify
    {list of changed file paths}

    ## Diff
    {git diff output}

    Review the changed code and apply simplifications directly.
    After making changes, summarize what you simplified and why.

Concrete dispatch anchor: review_pr_code_simplifier_dispatch. code-simplifier is a cheap-tier dispatch and resolves model as cheap_model if set, else claude-haiku-4-5-20251001.

Important: simplify always runs last (after all read-only reviews), because it modifies files. Skip `simplify` if any prior review returned CRITICAL issues — fix those first, then re-run with simplify.

Sequential mode (default)

Run agents one at a time in this order:

1. code (general quality first — sets the baseline)
2. errors (error handling)
3. comments (if applicable)
4. types (if applicable)
5. tests (if applicable)
6. simplify (if selected — always last)

After each agent completes, display its findings to the user before proceeding to the next.

Parallel mode

Launch all read-only agents simultaneously (multiple Agent tool calls in one response). Wait for all to complete, then:

1. Display all findings together
2. Run simplify last if selected (never in parallel — it modifies files)

Step 4 — Aggregate Results

After all agents complete, compile a unified summary:

# Code Review Summary

## Critical Issues ({count} found)
- [{agent-name}] Issue description [file:line]
- ...

## Important Issues ({count} found)
- [{agent-name}] Issue description [file:line]
- ...

## Suggestions ({count} found)
- [{agent-name}] Suggestion [file:line]
- ...

## Strengths
- What's done well (from agent observations)

## Recommended Actions
1. Fix critical issues first
2. Address important issues
3. Consider suggestions
4. Re-run `/review-loop:review-pr` after fixes to verify

If simplify was run, also note:

## Simplifications Applied
- {file}: {what was simplified}

Usage Examples

Full review (all applicable aspects, sequential):

/review-loop:review-pr

Specific aspects:

/review-loop:review-pr tests errors
# Reviews only test coverage and error handling

/review-loop:review-pr comments
# Reviews only code comments

/review-loop:review-pr simplify
# Simplifies changed code

Parallel review:

/review-loop:review-pr all parallel
# Launches all applicable agents in parallel

Combine:

/review-loop:review-pr code errors parallel
# Reviews code quality and error handling in parallel

Agent Descriptions

code-reviewer (review-loop:code-reviewer):

• Checks CLAUDE.md / project guideline compliance
• Detects bugs, logic errors, and anti-patterns
• Reviews general code quality and style

silent-failure-hunter (review-loop:silent-failure-hunter):

• Finds silent failures and swallowed errors
• Reviews catch blocks and error propagation
• Checks error logging adequacy

comment-analyzer (review-loop:comment-analyzer):

• Verifies comment accuracy vs actual code
• Identifies comment rot and stale docs
• Checks documentation completeness

type-design-analyzer (review-loop:type-design-analyzer):

• Analyzes type encapsulation and invariants
• Reviews type design quality
• Rates invariant expression strength

pr-test-analyzer (review-loop:pr-test-analyzer):

• Reviews behavioral test coverage
• Identifies critical test gaps
• Evaluates test quality and assertions

code-simplifier (via general-purpose — has write access):

• Simplifies complex or verbose code
• Improves clarity and readability
• Applies project standards
• Preserves all existing functionality

Tips

• Run early: before creating a PR, not after
• Focus on changes: agents analyze git diff by default
• Address critical first: fix high-priority issues before lower priority
• Re-run after fixes: verify issues are resolved
• Use specific aspects: target what you care about to save time
• Parallel for speed: use parallel when you want all results at once