Comprehensive PR Review

Run a comprehensive pull request review by spawning general-purpose subagents with inlined reference instructions. Each subagent gets a fresh context window with its specialized review instructions, the diff, and project context.

Review Aspects (optional): “$ARGUMENTS”

1. Determine Review Scope

• Check git status to identify changed files
• Parse arguments to see if user requested specific review aspects
• Default: Run all applicable reviews

2. Available Review Aspects

3. Identify Changed Files

• Run git diff --name-only to see modified files
• Check if PR already exists: gh pr view
• Identify file types and what reviews apply

Error handling:

• If git diff fails (not a git repo): Report error clearly and stop
• If gh pr view fails with “no PR found”: Expected for pre-PR reviews, continue with git diff
• If gh pr view fails with auth error: Note that GitHub CLI authentication is needed
• If no changed files found: Report “No changes detected” and stop

4. Determine Applicable Reviews

Based on changes:

• Always applicable: code (general quality)
• If test files changed: tests
• If comments/docs added: comments
• If error handling changed: errors
• If types added/modified: types
• After passing review: simplify (polish and refine)

5. Read Reference Instructions

Read each applicable reference file into a variable for inlining into subagent prompts:

code_instructions      = Read("./references/code-reviewer-instructions.md")
test_instructions      = Read("./references/pr-test-analyzer-instructions.md")
comment_instructions   = Read("./references/comment-analyzer-instructions.md")
errors_instructions    = Read("./references/silent-failure-hunter-instructions.md")
types_instructions     = Read("./references/type-design-analyzer-instructions.md")
simplify_instructions  = Read("./references/code-simplifier-instructions.md")

Only read files for applicable review aspects. Also read:

• git diff output into diff_content
• CLAUDE.md (if exists) into project_context

6. Resolve Model Profile

MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")

Default to “balanced” if not set.

Model lookup table:

7. Launch Review Agents

Spawn general-purpose subagents via parallel Task calls. Each agent receives its reference instructions inlined as <agent-instructions>, the diff, and project context.

Task call pattern:

Task(
  prompt="<agent-instructions>\n{instructions_content}\n</agent-instructions>\n\nReview the following changes:\n\n<diff>\n{diff_content}\n</diff>\n\n<project-context>\n{project_context}\n</project-context>",
  subagent_type="general-purpose",
  model="{resolved_model}",
  description="PR review: {aspect}"
)

Example parallel launch (3 agents):

Task(prompt="<agent-instructions>\n{code_instructions}\n</agent-instructions>\n\nReview these changes:\n<diff>\n{diff_content}\n</diff>\n<project-context>\n{project_context}\n</project-context>", subagent_type="general-purpose", model="{code_model}", description="PR review: code")
Task(prompt="<agent-instructions>\n{test_instructions}\n</agent-instructions>\n\nReview these changes:\n<diff>\n{diff_content}\n</diff>\n<project-context>\n{project_context}\n</project-context>", subagent_type="general-purpose", model="{test_model}", description="PR review: tests")
Task(prompt="<agent-instructions>\n{errors_instructions}\n</agent-instructions>\n\nReview these changes:\n<diff>\n{diff_content}\n</diff>\n<project-context>\n{project_context}\n</project-context>", subagent_type="general-purpose", model="{errors_model}", description="PR review: errors")

All run in parallel. Task tool blocks until all complete.

Agent failure handling:

• If agent completes: Include results in aggregation
• If agent times out: Report “[aspect] review timed out – consider running independently”
• If agent fails: Report “[aspect] review failed: [error reason]”
• If one agent fails, STILL proceed with remaining agents
• Never silently skip a failed agent – always report its status

8. Aggregate Results

After agents complete, summarize:

• Critical Issues (must fix before merge)
• Important Issues (should fix)
• Suggestions (nice to have)
• Positive Observations (what’s good)

Edge cases:

• If no issues found: “All Checks Passed” summary
• If agents conflict: Note the disagreement and let user decide
• If agent output malformed: Note “[aspect] output could not be parsed”
• Always include count of agents completed vs failed

9. Provide Action Plan

Organize findings:

# PR Review Summary

## Critical Issues (X found)
- [aspect]: Issue description [file:line]

## Important Issues (X found)
- [aspect]: Issue description [file:line]

## Suggestions (X found)
- [aspect]: Suggestion [file:line]

## Strengths
- What's well-done in this PR

## Recommended Action
1. Fix critical issues first
2. Address important issues
3. Consider suggestions
4. Re-run review after fixes