Code Review

Review the code changes on the current branch compared to the target branch.

Target branch: $ARGUMENTS

If the argument above is empty, use main as the target branch. Otherwise use the provided value as the target branch name.

Step 1: Fetch and detect changes

First, fetch the latest remote state:

git fetch origin

Then get the list of changed files with their statuses:

git diff --name-status origin/<target_branch>...HEAD

If this fails (branch doesn't exist on remote), try:

git diff --name-status <target_branch>...HEAD

If that also fails, fall back to reviewing the last commit:

git diff --name-status HEAD~1

The output shows statuses: A (added), M (modified), D (deleted), R (renamed).

Skip deleted (D) files — there's nothing to review in removed code.

Step 2: Filter files

Skip files that don't need code review — see REVIEW_GUIDELINES.md for the default exclude list.

If .review-agent.md has a "Files to skip" section, apply those patterns in addition to the defaults.

Step 3: Read review-specific context

If .review-agent.md exists in the repo root, read it — it contains review-specific conventions and rules that apply ONLY during code review (e.g., what to ignore, project-specific patterns to accept, review strictness). This is separate from CLAUDE.md which is for general development context. Respect these conventions and do NOT suggest changes that contradict them.

Step 4: Parallel review with sub-agents

This is the critical step for performance. You MUST use the Agent tool to review files in parallel.

Group the filtered files into batches and launch sub-agents concurrently. Each sub-agent reviews its batch independently.

Batching strategy:

• 1-3 files: Launch 1 agent per file (maximum parallelism)
• 4-10 files: Group into batches of 2-3 files, launch agents in parallel
• 11-20 files: Group into batches of 4-5 files, launch agents in parallel
• 20+ files: Group into batches of 5-7 files, launch agents in parallel. Prioritize critical files (auth, security, payments, data access, API routes, DB) in earlier batches

Sub-agent prompt:

For each sub-agent, read REVIEW_GUIDELINES.md and include its content in the prompt along with:

You are a senior code reviewer. Review the following files for a branch targeting <target_branch>.

<review-specific context from .review-agent.md if found>

<REVIEW_GUIDELINES.md content>

Files to review:
<list of files in this batch with their statuses (A/M/R)>

For each file:
1. Run: git diff origin/<target_branch>...HEAD -- <file_path>
   to see what changed.
2. Read the file (or relevant sections) for surrounding context.
3. For new files (A): review entire content.
4. For modified files (M): focus on changed lines, consider context.
5. For renamed files (R): review code changes if any.

For EACH file, output in this format:

**<file_path>**

**[error/warning/info] Line X(-Y): Brief title** (category)
Description with concrete scenario. Fix suggestion with code.

---

If a file has no issues, output:
**<file_path>** — no issues found.

Categories: bug, security, performance, error-handling, type-safety, typo, naming, unused-code, code-style, best-practice, documentation, maintainability, other

IMPORTANT: Launch ALL sub-agents in a single message using multiple Agent tool calls. Do NOT wait for one to finish before launching the next.

Step 5: Collect results and output

After all sub-agents complete, collect their findings and output the consolidated review.

Deduplication

• If multiple agents found the same issue (same file, same line, same problem) — keep only one
• If the same pattern issue appears in multiple files — combine into one comment listing all locations

Final output format

Output all file reviews (from sub-agents), then add a summary:

Summary

• Files reviewed: N
• Issues found: N (X errors, Y warnings, Z info)
• Risk: low/medium/high/critical (1-10) — brief explanation
• Quality: poor/needs-improvement/good/excellent (1-10) — brief explanation
• Recommendation: What to focus on before merging

Risk scoring (1-10):

• Scope of changes, critical systems affected, breaking changes, complexity, dependencies, reversibility
• 1-3 = low, 4-5 = medium, 6-7 = high, 8-10 = critical

Quality scoring (1-10):

• Code clarity, error handling, test coverage, documentation, best practices, performance
• 1-3 = poor, 4-5 = needs-improvement, 6-7 = good, 8-10 = excellent

If no issues found: "No issues found in N files reviewed. The changes look good."

Out-of-Scope Critical Issues

If any sub-agent found a CRITICAL issue (security, major bug) in code OUTSIDE changed lines but RELATED to the changes — list separately at the end under "Out-of-scope issues".

Understanding Context

• Consider the overall scope and intent of changes before judging individual files
• Don't flag things that are clearly intentional
• For draft/WIP branches (branch name contains "draft", "wip"): focus only on errors and warnings
• If mock data or stubs are clearly temporary, don't flag as errors