pr-review

What this skill does

# PR Review Skill

This skill provides a structured approach to reviewing pull requests using **parallel specialized agents** for thorough coverage, with confidence scoring to minimize false positives.

**Important**: Any text comment you post must be prefixed with:
```
[AUTOMATED]
```
This is important because you are using the Github CLI with the account of your beloved human, and you want to make it clear that the comment is not coming from the human.

---

## Review Workflow

### Step 1: Pre-Review Validation

Before starting, launch a **haiku agent** to check if review should proceed:

```
Check if any of the following are true for the PR:
- The PR is closed
- The PR is a draft
- The PR is trivial (automated, obviously correct single-line change)

If any condition is true, stop and explain why.
```

If validation fails, do not proceed with the review.

### Step 2: Gather Context

Launch **two haiku agents in parallel**:

**Agent A - PR Summary**:
```
Fetch PR details using: uv run scripts/gh_pr.py files owner/repo <number>
If there's a linked issue, fetch it: uv run scripts/gh_pr.py issue owner/repo <issue>
Return a brief summary of:
- What the PR does
- Files changed
- Author's stated intent — based on code and eventual linked issue
```

**Agent B - Guidelines Discovery**:
```
Find all relevant guideline files:
- Root CLAUDE.md (if exists)
- CLAUDE.md files in directories containing modified files
- Any project-specific style guides

Return the file paths and key rules that apply to changed files.
```

### Step 3: Parallel Review Agents

Launch **4 specialized agents in parallel** to review the changes. Each agent should receive:
- PR title and description
- Relevant guideline summaries (from Step 2)
- The diff (via `uv run scripts/gh_pr.py files owner/repo <number> --raw`)

**Agent 1: Bug Hunter (opus)**
See `agents/bug-hunter.md`. Focus on actual bugs and security issues.

**Agent 2: Bug Hunter (opus)**
Same as Agent 1, run twice for coverage. Different agents may catch different issues.

**Agent 3: Guideline Compliance (sonnet)**
See `agents/guideline-compliance.md`. Check CLAUDE.md and project convention adherence.

**Agent 4: Error Handling Auditor (sonnet)**
See `agents/error-handling-auditor.md`. Hunt for silent failures and poor error handling.

**CRITICAL**: We only want **HIGH SIGNAL** issues:
- Objective bugs that will cause incorrect behavior at runtime
- Clear, unambiguous guideline violations with quoted rules
- Silent failures that hide errors from users

We do NOT want:
- Subjective concerns or suggestions
- Style preferences not explicitly required
- Potential issues that "might" be problems
- Anything requiring interpretation or judgment

### Step 4: Issue Validation

For each issue found with confidence >= 80, launch a **validation subagent**:

See `agents/issue-validator.md`. The validator independently verifies:
- Bug reports are real (trace code, check for defensive handling)
- Guideline violations actually apply (rule exists, no exceptions)
- The severity assessment is accurate

Use **opus** subagents for bug validation, **sonnet** for guideline validation.

### Step 5: Filter Results

Only keep issues that:
1. Had original confidence >= 80
2. Were validated in Step 4
3. Are not duplicates

This gives us our final list of high-signal issues.

### Step 6: Post Review

#### If NO issues found:

Post a summary comment (if requested):
```bash
gh pr comment <number> --body "[AUTOMATED]

## Code Review

No issues found. Checked for bugs, guideline compliance, and error handling."
```

#### If issues found:

Use the batched review workflow to post all comments at once.

---

## The Core Standard

**Approve changes that improve code health, even if imperfect.**

- The goal is continuous improvement, not perfection
- Don't block progress over minor issues - use "Nit:" prefix for non-blocking suggestions
- Reject only when the change worsens overall code health or is fundamentally unwanted

### Decision Hierarchy

When opinions conflict:
1. Technical facts and data override opinions
2. Style guides are authoritative
3. Design decisions require principle-based reasoning, not preference
4. Consistency with existing code (when it maintains health)

---

## What to Look For

### Design
- Is the overall architecture sound?
- Do code interactions make sense?
- Does this belong here, or in a library/different module?
- Does it integrate well with existing systems?

### Architectural Consistency
- **Identify existing abstractions** - What patterns does this codebase already have?
- **Check for pattern reuse** - Is new code following established patterns or reinventing them?
- **Look for duplicated abstractions** - Is the PR reimplementing existing helpers?
- **Look for useless abstractions** - Is complexity being added unnecessarily?

**Key question**: *"How do similar features in this codebase solve this problem?"*

### Functionality
- Does the code do what the author intended?
- Watch for: edge cases, race conditions, concurrency bugs

### Complexity
- Can you understand the code quickly?
- Is it over-engineered for hypothetical future needs?
- **Principle**: Solve the problem that exists now

### Tests
- Are there appropriate tests?
- Will tests actually fail when the code breaks?
- Are test cases meaningful, not just coverage padding?

---

## Writing Effective Comments

### Severity Labels
- **Nit:** Minor issue, should fix but won't block approval
- **Optional/Consider:** Suggestion worth considering, not required
- **FYI:** Information only, no action expected

### Tone
- Be kind - critique code, never the person
- Explain the reasoning behind suggestions
- Acknowledge when the author knows more than you

---

## Specialized Agents Reference

Additional agents available for targeted analysis:

### Test Analyzer
See `agents/test-analyzer.md`. Use when:
- PR adds significant new functionality
- You want to verify test coverage quality
- User asks about test thoroughness

### Full Agent List

| Agent | Focus | Model | When to Use |
|-------|-------|-------|-------------|
| bug-hunter | Bugs & security | opus | Default parallel review |
| guideline-compliance | CLAUDE.md adherence | sonnet | Default parallel review |
| error-handling-auditor | Silent failures | sonnet | Default parallel review |
| test-analyzer | Test coverage | sonnet | On request or for new features |
| issue-validator | Verify findings | inherit | Validation step |

---

## Scripts Reference

This skill includes Python scripts in `scripts/` that wrap GitHub API operations. Run them with `uv`:

### Available Commands

| Command | Description |
|---------|-------------|
| `files` | Get PR files with status and patch info |
| `comments` | Get review comments (supports `--unresolved`, `--pending` filters) |
| `reviews` | List all reviews on a PR |
| `post` | Post a batched review from JSON file |
| `reply` | Reply to a specific review comment |
| `resolve` | Resolve or unresolve a review thread |
| `head` | Get the head commit SHA for a PR |
| `checkout` | Create a worktree to review PR locally |
| `cleanup` | Remove a PR worktree |
| `init-review` | Initialize a review JSON file |
| `issue` | Fetch issue details (title, description, labels, assignees) |

### Usage Examples

```bash
# Fetch issue details
uv run scripts/gh_pr.py issue owner/repo 42

# Get PR files and diff
uv run scripts/gh_pr.py files owner/repo 123

# Get raw JSON for agent processing
uv run scripts/gh_pr.py files owner/repo 123 --raw

# Get unresolved review comments
uv run scripts/gh_pr.py comments owner/repo 123 --unresolved

# Initialize review file
uv run scripts/gh_pr.py init-review owner/repo 123

# Post batched review
uv run scripts/gh_pr.py post owner/repo 123 /tmp/pr-review-owner-repo-123.json
```

---

## Posting the Code Review

### Workflow Overview

Reviews are posted in a single batch to avoid spamming notifications. During the review process, accumulate feedback in a transient JSON fi