# Refactor

> Orchestrate a 3-agent PR code review debate using Claude Code Teams. Spawns Devil's Advocate, Neutral Judge, and Approval Advocate reviewers who analyze the current PR diff in parallel. Synthesizes findings, auto-fixes unanimous issues, and posts inline PR comments for disagreements. All output is in English.

- Skill: `nomadamas/refactor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nomadamas/refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nomadamas/refactor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nomadamas (https://skillmd.com/u/nomadamas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nomadamas/refactor

---


# /refactor -- 3-Agent PR Code Review Debate

You orchestrate a PR code review debate with 3 reviewer agents (Red/White/Green).
Follow these 10 steps exactly.

## Step 1: Verify PR Exists

Run:
```bash
gh pr view --json number,url,title,body,headRefName,baseRefName
```

If the command fails, exit immediately:
> No PR found on the current branch. Create a PR first.

Extract and remember these values:
- `PR_NUMBER` -- the PR number
- `PR_URL` -- the PR URL
- `PR_TITLE` -- the PR title
- `HEAD_REF` -- head branch name
- `BASE_REF` -- base branch name

## Step 2: Gather PR Diff and Context

Run these commands (in parallel where possible):
```bash
gh pr diff
gh pr diff --stat
git rev-parse HEAD
git remote get-url origin
```

Store results as:
- `FULL_DIFF` -- the full diff output
- `DIFF_STAT` -- the diff stat summary
- `HEAD_SHA` -- current HEAD commit SHA
- `OWNER_REPO` -- parse the remote URL to extract `OWNER/REPO` (handle both HTTPS and SSH formats)

If `FULL_DIFF` is empty, exit immediately:
> Nothing to review. The PR diff is empty.

## Step 3: Create Team and Spawn 3 Reviewers (Parallel)

### 3a. Create the team
```
TeamCreate(team_name="pr-review-{PR_NUMBER}")
```

### 3b. Create 3 tracking tasks
Create one task per reviewer:
- "Red Reviewer: Devil's Advocate analysis"
- "White Reviewer: Neutral Judge analysis"
- "Green Reviewer: Approval Advocate analysis"

### 3c. Spawn 3 reviewer agents in a SINGLE message (parallel)

Use the `Task` tool three times in the same message. Each agent:
- `subagent_type`: `"general-purpose"`
- `team_name`: `"pr-review-{PR_NUMBER}"`
- `mode`: `"bypassPermissions"`

Build each agent's prompt by filling in the appropriate role template below with `FULL_DIFF`, `DIFF_STAT`, `PR_TITLE`, and file list from diff stat.

Agent names and roles:

| Name | Role |
|------|------|
| `red-reviewer` | Devil's Advocate -- always opposes, attacks security/race conditions/hidden assumptions |
| `white-reviewer` | Neutral Judge -- risk = probability x impact, pragmatic tradeoffs |
| `green-reviewer` | Approval Advocate -- champions strengths, only flags genuinely critical issues |

### Red Reviewer (Devil's Advocate) Prompt Template

```
You are the RED REVIEWER -- the Devil's Advocate.

Your role: ALWAYS oppose. Find every flaw, risk, and hidden assumption.
You NEVER give LGTM. There is always something wrong.

## PR Under Review
Title: {PR_TITLE}

### Diff Statistics
{DIFF_STAT}

### Full Diff
{FULL_DIFF}

## Your Analysis Categories
Focus on these areas (in priority order):
1. **Security vulnerabilities** -- injection, auth bypass, data exposure, SSRF, path traversal
2. **Race conditions and concurrency** -- shared mutable state, missing locks, TOCTOU
3. **Hidden assumptions** -- hardcoded values, implicit ordering, undocumented preconditions
4. **Error handling gaps** -- swallowed exceptions, missing rollback, partial failure states
5. **Resource leaks** -- unclosed connections, file handles, memory, goroutines/threads
6. **Breaking changes** -- API contract changes, schema migrations, backward compatibility
7. **Logic errors** -- off-by-one, boundary conditions, null/empty edge cases
8. **Data integrity** -- silent data loss, truncation, encoding issues

## Output Format
For EACH finding, use this exact format:

### Finding {N}
- **File**: `{file_path}`
- **Lines**: {start_line}-{end_line}
- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
- **Category**: {one of the categories above}
- **Description**: {what is wrong and why it matters}
- **Evidence**: {quote the specific code from the diff}
- **Suggested Fix**: {concrete code change to fix the issue}

You MUST produce at least 3 findings. Dig deeper if the code looks clean.
Be specific -- cite exact file paths and line numbers from the diff.

When you are done, end your response with exactly:
RED_REVIEW_COMPLETE
```

### White Reviewer (Neutral Judge) Prompt Template

```
You are the WHITE REVIEWER -- the Neutral Judge.

Your role: Assess risk objectively using Risk = Probability x Impact.
Be pragmatic. Weigh tradeoffs. Not everything needs fixing.

## PR Under Review
Title: {PR_TITLE}

### Diff Statistics
{DIFF_STAT}

### Full Diff
{FULL_DIFF}

## Your Analysis Categories
Focus on these areas:
1. **Risk assessment** -- probability of occurrence x severity of impact
2. **Code quality** -- readability, maintainability, complexity
3. **Test coverage** -- are changes adequately tested? What gaps exist?
4. **Architecture fit** -- does this follow established patterns? Does it introduce tech debt?
5. **Performance** -- algorithmic complexity, N+1 queries, unnecessary allocations
6. **Error handling** -- is failure handled gracefully? Are error messages helpful?
7. **Configuration and deployment** -- env vars, feature flags, migration safety

## Output Format
For EACH finding, use this exact format:

### Finding {N}
- **File**: `{file_path}`
- **Lines**: {start_line}-{end_line}
- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
- **Category**: {one of the categories above}
- **Probability**: HIGH | MEDIUM | LOW (how likely is this to cause an issue?)
- **Impact**: HIGH | MEDIUM | LOW (how bad is it if it does happen?)
- **Description**: {what the concern is}
- **Evidence**: {quote the specific code from the diff}
- **Tradeoff**: {what is gained vs what is risked by the current approach}
- **Suggested Fix**: {concrete code change, or "acceptable as-is" with reasoning}

Report findings honestly. If the code is genuinely good, say so and focus on minor improvements.
Be specific -- cite exact file paths and line numbers from the diff.

When you are done, end your response with exactly:
WHITE_REVIEW_COMPLETE
```

### Green Reviewer (Approval Advocate) Prompt Template

```
You are the GREEN REVIEWER -- the Approval Advocate.

Your role: Champion the PR's strengths. Advocate for approval.
Only flag issues that are GENUINELY CRITICAL (data loss, security breach, production outage).
Everything else is a strength or acceptable tradeoff.

## PR Under Review
Title: {PR_TITLE}

### Diff Statistics
{DIFF_STAT}

### Full Diff
{FULL_DIFF}

## Your Analysis Focus
Identify and articulate:
1. **Design strengths** -- good abstractions, clean interfaces, separation of concerns
2. **Code quality wins** -- readability, naming, documentation
3. **Pattern consistency** -- follows project conventions, reuses existing utilities
4. **Correctness** -- logic is sound, edge cases handled, tests cover key paths
5. **Positive impact** -- what value does this PR deliver?

## Output Format

### Strengths Section
For EACH strength, use this format:

### Strength {N}
- **File**: `{file_path}` (or "Overall" for cross-cutting strengths)
- **Category**: {one of the focus areas above}
- **Description**: {what is done well and why it matters}
- **Evidence**: {quote the specific code that demonstrates the strength}

### Critical Findings Section (ONLY if genuinely critical)
Only include findings that meet ALL of these criteria:
- Could cause data loss, security breach, or production outage
- Is not a matter of style or preference
- Cannot be safely addressed in a follow-up PR

For each critical finding (if any):

### Critical Finding {N}
- **File**: `{file_path}`
- **Lines**: {start_line}-{end_line}
- **Severity**: CRITICAL
- **Category**: {security | data-integrity | production-outage}
- **Description**: {what is critically wrong}
- **Evidence**: {quote the specific code from the diff}
- **Suggested Fix**: {concrete code change to fix the issue}

You MUST produce at least 3 strengths.
Be specific -- cite exact file paths and line numbers from the diff.

When you are done, end your response with exactly:
GREEN_REVIEW_COMPLETE
```

## Step 4: Collect Results

- Messages arrive automatically from teammates as they finish
- Each agent returns findings in the structured format from the prompt templates above
- As each agent completes, mark their tracking task as completed
- If an agent has not responded within 5 minutes, proceed with available results

## Step 5: Parse and Cluster Findings

Apply the following synthesis algorithm:

### 5a. Parse Findings

Extract structured findings from each reviewer's response:
- **Red Reviewer**: Parse all `### Finding {N}` blocks
- **White Reviewer**: Parse all `### Finding {N}` blocks
- **Green Reviewer**: Parse all `### Critical Finding {N}` blocks (ignore `### Strength` blocks for clustering; save strengths separately for the summary)

Each parsed finding must have: `file`, `lines` (start-end), `severity`, `category`, `description`, `evidence`, `suggested_fix`, `reviewer` (red/white/green).

If a reviewer's response does not follow the expected format, skip parsing for that reviewer and flag it as unparseable.

### 5b. Cluster Findings

Two findings belong to the same cluster if ALL of these conditions are met:

**Condition 1: Same file path**
Exact string match on file path.

**Condition 2: Overlapping or nearby line ranges**
Line ranges overlap OR are within 5 lines of each other.

Example: Lines 10-15 and Lines 18-20 -> same cluster (gap = 3, within 5).
Example: Lines 10-15 and Lines 25-30 -> different clusters (gap = 10, exceeds 5).

**Condition 3: Related category group**
The findings' categories belong to the same category group:

| Group | Categories |
|-------|------------|
| Security | security, assumption, hidden-assumption |
| Concurrency | race-condition, resource-leak, concurrency |
| Error Handling | error-handling, logic-error, error-handling-gaps |
| Performance | performance, algorithmic-complexity |
| Style | style, readability, consistency, code-quality |
| Testing | test-gap, test-coverage |
| Data Safety | breaking-change, data-integrity, data-safety |
| Architecture | architecture-fit, architecture, configuration |

If a category does not match any group, treat it as its own group (only clusters with exact category matches).

### 5c. Classify Clusters

For each cluster, count the number of distinct reviewers who contributed findings:

| Reviewers in Cluster | Classification | Action |
|----------------------|----------------|--------|
| 3 (red + white + green) | **Unanimous** | Auto-fix |
| 2 (any combination) | **Majority** | Post PR comment |
| 1 (severity >= MEDIUM) | **Significant Single** | Post PR comment |
| 1 (severity = LOW) | **Minor Single** | Skip (do not post) |

### 5d. Select Representative Finding

For each cluster, select the finding to use as the "primary" for fix/comment:

- **Auto-fix**: Use the White Reviewer's (Neutral Judge) suggested fix. It is the most balanced.
- **PR comment**: Include all reviewers' perspectives in the comment, but use White Reviewer's description as the primary.
- If the White Reviewer did not contribute to a cluster, use the Red Reviewer's finding as primary.

### 5e. Collect Green Reviewer Strengths

From the Green Reviewer's response, extract the top 3 `### Strength` blocks.
These are used in the summary comment (Step 8) and are NOT clustered with findings.

### Handling Edge Cases

- **Unparseable response**: Note in summary that reviewer's response could not be parsed. Include raw text excerpt. Do not use for clustering.
- **No findings from any reviewer**: Post summary comment stating all reviewers found no issues. Skip Steps 6-7.
- **All findings are unanimous**: Auto-fix all, no PR comments needed (except summary).
- **All findings are single/LOW**: Skip all, post summary noting only minor observations.

## Step 6: Auto-Fix Unanimous Findings

For each unanimous finding, in order:

1. Read the target file
2. Apply the Neutral Judge's (white-reviewer) suggested fix using the `Edit` tool
3. Run `make check` to validate the fix
4. If `make check` fails: revert the file with `git checkout -- {file_path}` and downgrade this finding to a PR comment instead
5. If the fix spans more than 20 lines: skip auto-fix, downgrade to PR comment

After all fixes are applied:
```bash
git add <list of fixed files>
git commit -m "fix: address unanimous review findings from /refactor"
git push
```

If `git push` fails, inform the user to push manually.

## Step 7: Post Inline PR Comments (Disagreements)

For each finding classified as "PR comment" (majority or significant single), post an inline comment using the appropriate template below.

Run:
```bash
gh api repos/{OWNER_REPO}/pulls/{PR_NUMBER}/comments \
  -f body='{FORMATTED_COMMENT}' \
  -f path='{FILE_PATH}' \
  -f line={LINE_NUMBER} \
  -f commit_id='{HEAD_SHA}' \
  -f side='RIGHT'
```

If the `gh api` call fails for a specific comment, log the error and continue with remaining comments. Note failures in the summary.

### Inline Comment Template: Majority (2/3 reviewers)

Use when 2 out of 3 reviewers flagged the same issue.

```markdown
**Code Review Debate** (2/3 reviewers flagged this)

:red_circle: **Devil's Advocate**: {red_description}
:white_circle: **Neutral Judge**: {white_description}
:green_circle: **Approval Advocate**: {green_perspective}

**Suggested Fix**: {neutral_judge_suggested_fix}
**Risk Level**: {severity} (Probability: {probability}, Impact: {impact})
```

Notes:
- For the reviewer who did NOT flag this issue, write their perspective as: "No concerns raised for this code."
- `{probability}` and `{impact}` come from the White Reviewer. If White Reviewer is not in the cluster, omit the parenthetical.
- `{neutral_judge_suggested_fix}` comes from White Reviewer. If White is not in cluster, use Red Reviewer's fix.

### Inline Comment Template: Single Reviewer (1/3, severity >= MEDIUM)

Use when only 1 reviewer flagged the issue but severity is MEDIUM or higher.

```markdown
**Code Review Note** (1/3 reviewers flagged this)

**{reviewer_role}**: {description}
**Other reviewers**: No concerns raised.
**Severity**: {severity} | **Category**: {category}

**Suggested Fix**: {suggested_fix}
```

Notes:
- `{reviewer_role}` is one of: "Devil's Advocate", "Neutral Judge", "Approval Advocate"
- Only include `Suggested Fix` if the finding includes one.

## Step 8: Post Summary Comment

Post a top-level PR comment using the template below:

```bash
gh api repos/{OWNER_REPO}/issues/{PR_NUMBER}/comments \
  -f body='{SUMMARY_BODY}'
```

### Summary Comment Template

```markdown
## /refactor Code Review Summary

### Results

| Classification | Count | Action |
|----------------|-------|--------|
| Unanimous (3/3) | {unanimous_count} | Auto-fixed |
| Majority (2/3) | {majority_count} | Inline comment |
| Single (>= MEDIUM) | {significant_single_count} | Inline comment |
| Single (LOW) | {minor_single_count} | Skipped |
| **Total findings** | **{total_count}** | |

### Auto-Fixed Issues
{If unanimous_count > 0, list each:}
- `{file_path}`: {short_description} (lines {start}-{end})

{If unanimous_count == 0:}
No issues were unanimously identified for auto-fix.

### Inline Comments Posted
{If comment_count > 0, list each:}
- `{file_path}:{line_number}`: {short_description} ({classification})

{If comment_count == 0:}
No inline comments were posted.

### Top Strengths (from Approval Advocate)
1. {strength_1_description}
2. {strength_2_description}
3. {strength_3_description}

### Reviewer Verdicts
- :red_circle: **Devil's Advocate**: {red_one_line_verdict}
- :white_circle: **Neutral Judge**: {white_one_line_verdict}
- :green_circle: **Approval Advocate**: {green_one_line_verdict}

---
*Generated by `/refactor` -- 3-agent code review debate*
```

Notes:
- Verdicts are one-line summaries from each reviewer. Derive these from the overall tone and key concern of each review.
- If a reviewer's response was unparseable, note: "{Role}: Response could not be parsed (raw text included below)"
- If `gh api` failed for any inline comment, add a section:
  ```
  ### Failed Comments
  - `{file_path}:{line}`: {error_reason}
  ```
- If `git push` failed after auto-fix, add:
  ```
  ### Note
  Auto-fix commit was created locally but could not be pushed. Run `git push` manually.
  ```

## Step 9: Cleanup Team

Send shutdown requests to all 3 agents:
```
SendMessage(type="shutdown_request", recipient="red-reviewer")
SendMessage(type="shutdown_request", recipient="white-reviewer")
SendMessage(type="shutdown_request", recipient="green-reviewer")
```

After all agents have shut down:
```
TeamDelete()
```

## Step 10: Report to User

Print a final summary to the console. No emojis. Include:
- Number of findings auto-fixed and committed
- Number of inline comments posted on the PR
- Number of findings skipped (low severity single reviewer)
- The PR URL for reference

Example output:
```
/refactor complete.

Auto-fixed: 3 findings (committed and pushed)
PR comments: 5 inline comments posted
Skipped: 2 low-severity findings

PR: https://github.com/owner/repo/pull/123
```

---

## Error Handling

| Scenario | Action |
|----------|--------|
| No PR found | Exit with message |
| Empty diff | Exit with message |
| Agent timeout (5 min) | Proceed with available results |
| `make check` fails after fix | Revert file, downgrade to PR comment |
| `gh api` comment fails | Log error, continue, note in summary |
| Agent response unparseable | Include raw text in summary, skip for clustering |
| `git push` fails | Inform user to push manually |