PR Review Team

Step 1: Identify Target PR & Detect Project Context

Resolve the PR number:

• If user specified: use that number
• Otherwise: !gh pr view --json number --jq '.number' 2>/dev/null

Gather context:

• File overview: gh pr diff <PR番号> --name-only (fallback: git diff <base>...HEAD --name-only)
• Base branch: git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' (fallback: main)
• Test command: detect from package.json, Makefile, pytest.ini, etc.
• Project rules: read project's CLAUDE.md if present

Note: gh commands may require dangerouslyDisableSandbox: true for TLS issues.

Step 2: Create Review Team

MANDATORY: Use TeamCreate to create the team, then spawn agents with Task tool.

Team structure:

Team Lead (yourself)
├─ Reviewer 1: pr-review-toolkit:code-reviewer
├─ Reviewer 2: pr-review-toolkit:silent-failure-hunter
├─ Reviewer 3: pr-review-toolkit:pr-test-analyzer
├─ Reviewer 4: pr-review-toolkit:comment-analyzer
└─ Fixer: general-purpose (code-fixer)

Launch all 4 reviewers in parallel via Task tool.

MANDATORY: Always specify an explicit model parameter when spawning each agent. Choose the appropriate model based on task complexity (haiku for lightweight, sonnet for standard, opus for complex reasoning). Never omit model (default inherit may fail in parallel spawning).

Review criteria: agents read ${CLAUDE_PLUGIN_ROOT}/skills/review-commit/references/review-criteria.md — leader does NOT read this file (agents handle criteria, leader handles integration).

Agent Launch Failure Handling

If any reviewer agent fails to launch:

Agent	Failure Severity	Action
code-reviewer	CRITICAL	Abort review. Report failure and STOP.
silent-failure-hunter	WARNING	Continue with remaining reviewers. Note in report.
pr-test-analyzer	WARNING	Continue with remaining reviewers. Note in report.
comment-analyzer	WARNING	Continue with remaining reviewers. Note in report.

If ALL agents fail: report error and STOP.

Step 3: Collect CI Results

Leader collects CI data (do NOT delegate):

Check Status

gh pr checks <PR番号>

Parse output for FAIL/PASS/PENDING status per check.

CI Pending Strategy

If any checks are PENDING:

FOR attempt = 1 TO 3:
  1. Wait 30 seconds
  2. Re-check: gh pr checks <PR番号>
  3. IF all checks resolved → BREAK
END FOR

If still PENDING after 3 attempts (90 seconds total):

• Continue review without CI results
• Add to final report: "CI: PENDING (timed out — manual verification recommended)"

Get Failure Details

For each failed check:

# Get failed checks
gh pr checks <PR番号> --json name,bucket,link --jq '.[] | select(.bucket == "fail")'

# Get failed log
gh run view <run-id> --log-failed

Collect Review Comments

gh pr view <PR番号> --json comments --jq '.comments[].body'

Also check for Claude Code review comments (automated review feedback).

HEAD Filtering

Avoid sending already-fixed issues to the fixer.

FOR each CI issue or review comment:
  1. Extract the file path and line number from the issue
  2. Get current diff: gh pr diff <PR番号>
  3. Check if the referenced line still exists in the current HEAD
  4. IF the line has been modified or removed since the issue was reported:
       → Mark as "already addressed" — do NOT send to fixer
  5. ELSE:
       → Include in the fixer's issue list
END FOR

Sandbox Notes

gh commands may fail in sandboxed environments due to TLS certificate restrictions. Use dangerouslyDisableSandbox: true when calling gh via Bash tool. This is safe for read-only operations like gh pr view, gh pr checks, and gh run view.

Step 4: Integrate & Send to Fixer

MANDATORY: Combine reviewer results + CI results into one single message to fixer. Split messages are prohibited (message loss risk).

Security checklist: read ${CLAUDE_PLUGIN_ROOT}/skills/pr-review-team/references/security-checklist.md now (deferred from Step 2 to save context).

Fixer Message Template

Structure the message to fixer using this template:

## Critical Issues
[List critical issues from all reviewers + CI failures]
- Source: <reviewer-name>
- File: <path>:<line>
- Issue: <description>

## Important Issues
[List important issues]
- Source: <reviewer-name>
- File: <path>:<line>
- Issue: <description>

## Security Checklist Failures
[List security checklist items that failed]
- Check: <checklist-item>
- File: <path>:<line>
- Issue: <description>

## Already Addressed (informational — do NOT fix)
[List issues filtered out by HEAD filtering logic]
- Source: <reviewer-name or CI>
- Reason: Line modified/removed in current HEAD

Step 5: Iterative Fix Loop

MAX_ITERATIONS=5
MAX_RETRIES=2

WARNING: Never use counts from a previous iteration to check the exit condition. Every exit check MUST use counts produced by the re-review in step 4 of the SAME iteration.

FOR iteration = 1 TO $MAX_ITERATIONS:
  SET fresh_critical = UNSET
  SET fresh_important = UNSET
  SET fresh_security = UNSET
  SET retry_count = 0
  SET review_retry_count = 0

  1. Fixer applies fixes
  2. Run test command (detected in Step 1)
  3. IF tests fail:
       SET retry_count = retry_count + 1
       IF retry_count >= MAX_RETRIES → report to user ("Test failures persist after MAX_RETRIES retries"), do NOT merge, BREAK outer loop
       ELSE → Fixer retries (loop back to step 1 of this iteration; do NOT advance to step 4)
     IF tests pass → CONTINUE to step 4
  4. Re-review with ALL 4 reviewers in parallel (same failure handling as Step 2):
     - code-reviewer
     - silent-failure-hunter
     - pr-test-analyzer
     - comment-analyzer
     ASSIGN fresh_critical, fresh_important, fresh_security FROM this re-review output
     (fresh_security MUST be one of: "all_pass" or "has_failures". Any other value including empty string is treated as UNSET.)
  5. Aggregate results (same template as Step 4) using fresh_critical, fresh_important, fresh_security
  6. MUST VERIFY: fresh_critical, fresh_important, fresh_security are SET (not UNSET).
     If any is UNSET:
       SET review_retry_count = review_retry_count + 1
       IF review_retry_count >= 2 (i.e., any fresh_ variable still remains UNSET after retry), report "Re-review failed" to user and BREAK.
       ELSE go back to step 4 of THIS iteration (do NOT advance to step 5 or 6; do NOT start a new iteration).
     IF fresh_critical = 0 AND fresh_important = 0 AND fresh_security = "all_pass":
       → BREAK
END FOR

If iteration limit reached with remaining issues: report to user, do NOT merge.

Step 6: Report & Shutdown

Report summary:

• Issues found / fixed / remaining
• Iterations performed
• Security checklist status
• CI status (including any PENDING timeouts)
• Agents that failed to launch (if any)

Do NOT merge — wait for user's explicit instruction.

Shutdown Procedure

Send shutdown_request to all agents individually via SendMessage (one message per agent):

• code-reviewer, silent-failure-hunter, pr-test-analyzer, comment-analyzer, code-fixer

Wait up to 30 seconds for shutdown_response from each agent.

Then call TeamDelete.

If TeamDelete fails (agents did not respond to shutdown):

1. Note the team name used in the TeamCreate step (store as TEAM_NAME)
2. Force-delete team directories using Bash with dangerouslyDisableSandbox: true:

   rm -rf ~/.claude/teams/"${TEAM_NAME:?}"/ ~/.claude/tasks/"${TEAM_NAME:?}"/
   

   The ${TEAM_NAME:?} guard prevents rm -rf from running with an empty path.
3. Inform user: "Team force-deleted. If agent polling continues, restart Claude Code."