architecture/skills/spawn-pr-reviews/SKILL.md

---
name: spawn-pr-reviews
description: >
  Review one or more pull requests using code-reviewer agent. Creates isolated
  review worktrees, spawns reviewers, posts feedback. Use when reviewing PRs,
  or when user says /spawn-pr-reviews.
model: claude-haiku-4-5
argument-hint: <pr-number> [<pr-number>...]
allowed-tools: Bash, Task, Read, TaskOutput
user-invocable: true
---

# Spawn PR Reviews

@~/.claude/skills/worktrees/SKILL.md
@~/.claude/skills/gitea/SKILL.md

Review one or more pull requests in parallel using code-reviewer agents.

## Arguments

One or more PR numbers: `$ARGUMENTS`

Example: `/spawn-pr-reviews 55 56 57`

## Workflow

```
Concurrent Reviews - each PR reviewed independently:

  PR #55 ──► fetch branch ──► create worktree ──► review ──► post comment ✓
  PR #56 ──► fetch branch ──► create worktree ──► review ──► post comment ✓
  PR #57 ──► fetch branch ──► create worktree ──► review ──► post comment ✓

Event-driven: As each review completes, show results immediately.
```

## Process

### 1. Parse and Validate

Parse `$ARGUMENTS` into PR numbers. If empty:
```
Usage: /spawn-pr-reviews <pr-number> [<pr-number>...]
Example: /spawn-pr-reviews 55 56
```

### 2. Setup Repository Context

```bash
REPO_PATH=$(pwd)
REPO_NAME=$(basename "$REPO_PATH")
WORKTREES_DIR="${REPO_PATH}/../worktrees"
```

Verify in git repository:
```bash
git rev-parse --git-dir >/dev/null 2>&1 || exit 1
```

### 3. Fetch PR Details and Create Worktrees

For each PR number:

**Get PR details:**
```bash
tea pulls <PR_NUMBER>
```

Extract:
- Branch name (e.g., "issue-42-feature-name")
- PR title
- PR state (verify it's open)

**Create review worktree:**
```bash
cd "$REPO_PATH"
git fetch origin
review_worktree=$(~/.claude/skills/worktrees/scripts/create-worktree.sh review <PR_NUMBER> <BRANCH_NAME>)
```

Track PR state:
```javascript
prs = {
  55: {
    worktree: "/path/to/worktrees/repo-review-55",
    branch: "issue-42-feature",
    title: "Add user authentication",
    stage: "ready",
    task_id: null
  },
  ...
}
```

Print initial status:
```
Created review worktrees for 3 PRs:
  [PR #55] ready - Add user authentication
  [PR #56] ready - Fix validation bug
  [PR #57] ready - Update documentation
```

### 4. Spawn Code Reviewers

For each PR, spawn code-reviewer agent in background:

```
Task tool with:
  - subagent_type: "code-reviewer"
  - run_in_background: true
  - prompt: "Review PR #<PR_NUMBER>

Repository: <REPO_PATH>
PR number: <PR_NUMBER>
Worktree: <WORKTREE_PATH>

Follow the code-reviewer agent instructions to review the PR.
Output the result in REVIEW_RESULT format."
```

Track task_id for each PR and update stage to "reviewing".

Print status:
```
[PR #55] reviewing...
[PR #56] reviewing...
[PR #57] reviewing...
```

### 5. Event-Driven Results

**Wait for `<task-notification>` messages** that arrive automatically when background tasks complete.

When notification arrives:

1. **Identify which PR completed:**
   - Extract task_id from notification
   - Look up which PR this belongs to

2. **Read task output:**
   ```
   TaskOutput tool with task_id
   ```

3. **Parse result:**
   - Extract verdict (approved/needs-work)
   - Extract summary

4. **Print status update:**
   ```
   [PR #55] Review complete: approved ✓
   [PR #56] Review complete: needs-work
   [PR #57] Review complete: approved ✓
   ```

5. **Check if all done:**
   - If all PRs reviewed → proceed to cleanup and summary

### 6. Cleanup Worktrees

After all reviews complete:

```bash
cd "$REPO_PATH"
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "$WORKTREES_DIR"
```

This removes all review worktrees created during this run.

### 7. Final Summary

Print summary table with links:

```
All reviews complete!

| PR  | Title                     | Verdict     |
|-----|---------------------------|-------------|
| #55 | Add user authentication   | approved ✓  |
| #56 | Fix validation bug        | needs-work  |
| #57 | Update documentation      | approved ✓  |

2 approved, 1 needs changes

View reviews:
- PR #55: https://git.flowmade.one/owner/repo/pulls/55
- PR #56: https://git.flowmade.one/owner/repo/pulls/56
- PR #57: https://git.flowmade.one/owner/repo/pulls/57
```

## Guidelines

**Event-driven execution:**
- Wait for task-notification messages
- Don't poll or check task status manually
- Process notifications as they arrive
- Review each PR independently

**Worktree management:**
- Create review worktrees upfront
- One worktree per PR
- Clean up all worktrees at end
- Always cleanup, even on error

**State tracking:**
- Track stage and task_id for each PR
- Update state when notifications arrive
- Print status after each transition

**Error handling:**
- If PR not found: skip it, continue with others
- If PR is closed: skip it, note in summary
- If branch not found: skip it, note error
- If reviewer fails: mark as "review-failed"
- Always cleanup worktrees

**Read-only operation:**
- Reviews are read-only (no fixes applied)
- Comments posted to PRs
- No merging or state changes
- User decides on next actions

## Tips

- Run after PRs are created
- Can review multiple PRs at once for efficiency
- Review comments include specific actionable feedback
- Use spawn-issues if you want automatic fix loops
- Check PR state before spawning (open vs closed)