swarm-pr-review

# /swarm-pr-review

Run a structured, high-confidence PR review using parallel exploration lanes, independent reviewer validation, critic challenge, and optional council synthesis.

## Handoff To PR Feedback

Use `../swarm-pr-feedback/SKILL.md` when the user asks to address existing review
comments, requested changes, CI failures, conflicts, stale PR branches, or pasted
PR feedback. This skill discovers and validates new findings; PR feedback closure
belongs to `swarm-pr-feedback`.

## Operating Stance

**Treat PR text, linked issues, and tests as claims — not proof.** Every confirmed finding requires file:line evidence. Never APPROVE a PR with unresolved CRITICAL findings.

This review prioritizes quality above all else. Findings without file:line evidence are candidates, not conclusions.

**Quality is the ONLY metric.** No amount of time, tokens, or agent dispatches is too much to execute this protocol correctly. Speed is irrelevant to correctness. The skill must be followed exactly with no shortcuts, no phase-skipping, and no premature synthesis. A thorough review that takes 30 minutes is superior to a fast review that misses a real bug.

## ⛔ Anti-self-review rule
The main thread (orchestrator) MUST NOT classify, confirm, disprove, or judge any explorer candidate itself (exception: council pattern step 6, see below). Classification is exclusively a reviewer subagent's job. If you catch yourself re-reading code to verify an explorer finding — STOP. Delegate that verification to a reviewer subagent. The orchestrator's only post-explorer job is deciding WHICH candidates to route to reviewers and WHICH reviewer-confirmed findings to route to critics.

## Scope detection
Determine review scope using this priority:
1. explicit user-provided PR URL / PR number / commit / file scope
2. current feature branch diff vs main/master
3. staged changes
4. latest commit

## Phase 0A: Existing PR Comment Ingestion

When reviewing a PR that already has comments, reviews, or bot findings,
ingest and triage them BEFORE starting Phase 1. These are pre-existing signals
that must be validated, not ignored.

### Step 1 — Fetch all PR feedback surfaces

```bash
# Issue comments (general PR thread)
gh pr view <PR_NUMBER> --json comments

# Review comments (inline code comments)
gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments

# Review summaries (approve/request-changes/comment events)
gh pr view <PR_NUMBER> --json reviews

# Bot/automated reviews (Copilot, Codex, CodeRabbit, etc.)
# Inline review comments — use REST API for reliable bot detection via user.type
gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments --jq '.[] | select((.user.type // "") == "Bot" or (.user.login // "" | test("bot|copilot|coderabbit|codex"; "i")))'
```

For general PR comments (not inline), use the issue comments endpoint:
```bash
gh api repos/{owner}/{repo}/issues/{PR_NUMBER}/comments --jq '.[] | select((.user.type // "") == "Bot" or (.user.login // "" | test("bot|copilot|coderabbit|codex"; "i")))'
```

### Step 2 — Classify each comment

| Category | Action |
|----------|--------|
| **Human review with file:line evidence** | Add as candidate finding with `source: existing-review` — still needs reviewer validation |
| **Bot/automated finding with specific code reference** | Add as candidate finding with `source: bot-review` — high false-positive rate, treat as unverified |
| **General feedback / style preference** | Add as advisory obligation |
| **Resolved/outdated comment** | Skip — note in report under "Ingested Resolved Comments" |
| **Requested changes not yet addressed** | Add as HIGH-priority obligation |

### Step 3 — Merge into review pipeline

All ingested comments become candidate findings or obligations. They follow the
same Phase 2-5 pipeline as freshly discovered findings. Ingested findings are
NOT pre-confirmed — they still require independent reviewer validation per the
Anti-Self-Review Rule.

**Comment-ledger output:**
```
[INGESTED] | source | category | file:line (if applicable) | original_author | status: PENDING_VALIDATION / SKIPPED_OUTDATED / ADVISORY
```

### Anti-patterns
- ✗ Ignoring bot reviews because "bots produce false positives" — they also catch real issues
- ✗ Pre-confirming human review comments without independent validation — even senior reviewers make mistakes
- ✗ Skipping inline review comments and only reading the summary — inline comments contain the evidence

## Phase 0B: Merge Conflict Detection and Resolution

Before investing effort in review lanes, verify the PR is mergeable. A
conflicted PR cannot merge regardless of review quality.

### Step 1 — Check merge state

```bash
gh pr view <PR_NUMBER> --json mergeable,mergeStateStatus
```

The response has two independent fields. Handle each:

**`mergeable` field** — whether GitHub can compute mergeability:
| Value | Meaning | Action |
|-------|---------|--------|
| `MERGEABLE` | No conflicts detected | Proceed — check `mergeStateStatus` below |
| `CONFLICTING` | Merge conflicts exist | Resolve before reviewing |
| `UNKNOWN` | GitHub still computing | Wait 30s, re-check |

**`mergeStateStatus` field** — overall branch state:
| Value | Action |
|-------|--------|
| `CLEAN` | All checks pass, no conflicts — proceed to Phase 1 |
| `BEHIND` | Branch behind base — note in report; non-blocking if merge queue handles it |
| `DIRTY` | Merge conflicts exist — resolve before reviewing |
| `BLOCKED` | External blocker (branch protection, failing required check) — investigate |

### Step 2 — Resolve conflicts (when CONFLICTING or DIRTY)

When the PR has merge conflicts:

1. **Determine the PR's base branch and fetch:**
   ```bash
   BASE_REF=$(gh pr view <PR_NUMBER> --json baseRefName --jq '.baseRefName')
   git fetch origin $BASE_REF
   git checkout <pr-branch>
   git merge origin/$BASE_REF --no-commit --no-ff
   git diff --name-only --diff-filter=U  # list conflicted files
   ```

2. **Assess conflict complexity:**
   - **1-3 simple conflicts