Skip to main content
skill CX Codex

bug-review — Claude Code skill: multi-pass PR bug review

bug-review is a Claude Code skill that runs five parallel passes over a PR diff, selects findings by majority vote, then checks them with a separate Opus validator. It finds bugs before the merge.

MIT 264 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill bug-review -a claude-code
Open on GitHub

What bug-review does

The skill takes a PR number, URL or branch name, pulls the diff and surrounding context with scripts/fetch-pr.sh and scripts/gather-context.sh, then spreads the work across five review agents. Each one gets a differently shuffled diff and its own angle: logic and edge cases, security and data integrity, error handling and API contracts, concurrency and state, data flow. A finding reaches the table only if at least three of the five passes flagged it, and category weights from config.json move its score up or down.

Next comes a validator running on Opus that never saw the passes. It receives the surviving findings and the code, returns KEEP or DISCARD, and scales the score by its own confidence. Anything below 0.5 is shown with a low-confidence warning. Before posting, the skill compares against earlier [bug-review] comments in the same PR by file and line, so one bug is not reported twice.

Autofix is opt-in per finding: the smallest possible edit, a git diff --stat check that the change stays within 20 lines and one file, the test suite, one commit per fix, no force-push. After merge, /bug-review:resolve <PR> classifies which findings were fixed and /bug-review:report prints the stats. You need an authenticated gh (gh auth status), jq, bc and a git repo with a GitHub remote. Without gh auth there is no diff to review.

What it helps with

  • run five review angles over a PR diff and keep only what most passes agree on
  • filter out false positives with a validator that never saw the review
  • get findings as a table with file, line, severity and vote count
  • apply a minimal autofix and let the test suite decide
  • measure how many findings were actually fixed by merge time

Example prompts for the agent

  • Run /bug-review 142 and show me the findings table.
  • Classify /bug-review:resolve 142 — which findings were fixed before merge?
  • Give me the resolution stats with /bug-review:report.

How to install bug-review

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill bug-review -a claude-code

2Manually: put the files in place

~/.claude/skills/bug-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bug-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bug-review

How do I install bug-review in Claude Code?

Run npx skills add pproenca/dot-skills --skill bug-review -a claude-code. The skill ends up at ~/.claude/skills/bug-review/SKILL.md.

What does bug-review do?

It reviews a pull request diff in five parallel passes with different focus areas, keeps findings that reach majority vote, and passes them through a separate validator. Then it posts inline PR comments and can generate autofix commits.

What does bug-review need to run?

An authenticated gh (check with gh auth status), jq and bc installed, plus a git repository with a GitHub remote in the current directory.

Source text

SKILL.md · MIT
---
name: bug-review
description: Multi-pass PR bug review — 5 parallel passes, majority voting, independent Opus validation, and resolution rate tracking. Trigger on PR review, bug finding, code review, "review this PR", "check for bugs", "find issues in this PR", or /bug-review. Also trigger on /bug-review:resolve to classify whether findings were fixed at merge time, and /bug-review:report for resolution rate stats. Even if the user just says "review this" while on a PR branch, trigger this skill.
---
# Bug Review v2

Multi-pass PR review agent with 5 parallel review passes, majority voting, independent Opus validation, and resolution rate learning. Posts inline PR comments and optionally generates autofix commits. Tracks whether findings get resolved at merge time and uses that signal to improve future reviews.

## When to Apply

- User asks to review a pull request for bugs or correctness issues
- User runs `/bug-review <PR-number-or-URL>`
- User runs `/bug-review:resolve <PR>` to classify resolutions after merge
- User runs `/bug-review:report` for resolution rate statistics
- User asks for code review focused on logic errors, edge cases, or security
- User wants to find bugs in a diff or set of changes

## Setup

On first run, verify:
- `gh` CLI is installed and authenticated (`gh auth status`)
- Current directory is a git repo with a GitHub remote
- `jq` is installed (for JSON processing)
- `bc` is installed (for resolution rate calculations; pre-installed on most systems)

Read [config.json](config.json) for configuration (passes, vote threshold, models, category weights).

## Workflow Overview

```
/bug-review <PR>
  |
  v
Fetch PR context + gather-context.sh
  |
  v
5 parallel passes (shuffled diffs, Sonnet) --> Aggregate & vote (3/5 majority)
  |
  v
Independent Opus validator --> Dedup --> Present findings --> Post + store
  |
  (later, after merge)
  v
/bug-review:resolve <PR> --> Classify resolutions --> Update category weights
```

## Command: /bug-review <PR>

### Step 1: Parse Input & Fetch Context

1. Parse the PR identifier (number, URL, or branch name)
2. **Check cache**: Look for `${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/` — if cache exists for the same head commit, offer to resume from the last checkpoint
3. Run `scripts/fetch-pr.sh <pr-identifier>` to get PR diff + metadata as JSON
4. Save the diff to a temp file for shuffling
5. Run `scripts/gather-context.sh <changed-files-json>` to get prioritized context (callers, types, tests, repo rules)
6. Read `.bug-review.md` from repo root if it exists
7. **Save checkpoint**: Write context to `${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/context.json`

### Step 2: Run 5 Parallel Review Passes

For each pass (1-5), prepare a shuffled diff:
```bash
scripts/shuffle-diff.sh <pass-number> < pr.diff > pass-<N>.diff
```

Launch **5 Agent subprocesses in parallel**. Read [review-passes.md](references/review-passes.md) for the exact prompt for each pass.

- **Pass 1**: Logic & Edge Cases (seed 1)
- **Pass 2**: Security & Data Integrity (seed 2)
- **Pass 3**: Error Handling & API Contracts (seed 3)
- **Pass 4**: Concurrency & State (seed 4)
- **Pass 5**: Data Flow & Contracts (seed 5)

Use `model` from config.json `agent_model` (default: `"sonnet"`).

Each agent returns a JSON array of findings.

**Save checkpoint**: Write all pass results to `${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/pass-results.json`

### Step 3: Aggregate & Vote

1. Collect findings from all 5 passes
2. Group findings by similarity: same file + line within +/-5 + same or related category
3. Count votes per group
4. **Keep only findings with 3+ votes** (majority of 5, configurable via `vote_threshold`)
5. Apply **category weights** from config.json: `final_score = votes × severity_weight × category_weight`
6. Categories with weight < 0.1 are suppressed entirely
7. Rank by final_score descending

If only 1-2 passes found bugs and the others found none, present findings but note they lack consensus.

**Save checkpoint**: Write voted findings to cache.

### Step 4: Independent Validation (Opus)

Launch a **separate Agent** using `validator_model` from config.json (default: `"opus"`).

This agent has NOT seen the review passes. It receives only the voted findings and the original code. Read the Validator section in [review-passes.md](references/review-passes.md) for the prompt.

For each finding, the validator outputs: `{id, verdict: "KEEP"|"DISCARD", confidence, reasoning}`

Remove DISCARDed findings. Multiply each finding's score by the validator's confidence.

Compute each finding's final `confidence` field:
```
confidence = (votes / total_passes) × validator_confidence
```

Findings with confidence < 0.5 are shown with a "low confidence" warning.

**Save checkpoint**: Write validated findings to cache.

### Step 5: Dedup Against Prior Reviews

Run `scripts/dedup.sh <pr-number>` to get existing `[bug-review]` comments.
Match by location proximity (file + line within +/-10) and category — not text similarity.

### Step 6: Present Findings to User

Display a table:

| # | Severity | Confidence | File | Line | Title | Votes |
|---|----------|------------|------|------|-------|-------|

For each finding, show full description, trigger scenario, suggested fix, and validator reasoning.

Ask the user (using AskUserQuestion with multiSelect):
- Which findings to **post as PR comments** (default: all)
- Which findings to **autofix** (default: none)

If no findings survived voting + validation: "No bugs found across 5 review passes. The changes look clean."

### Step 7a: Post PR Review

Write approved findings to a temporary JSON file, then run:
```bash
scripts/post-review.sh <pr-number> <findings-json-file>
```

Then persist findings for resolution tracking:
```bash
scripts/store-findings.sh <pr-number> <findings-json-file> <head-commit-sha>
```

### Step 7b: Autofix (User-Selected Findings)

For each finding selected for autofix:
1. Read the file and understand surrounding context
2. Generate a **minimal fix** (smallest possible change)
3. Apply the fix using the Edit tool
4. **Scope check**: Run `git diff --stat` — verify only the finding's file was modified and diff is under 20 lines. If exceeded, revert and warn.
5. Run existing tests if available (`npm test`, `go test ./...`, `pytest`, etc.)
6. If tests pass: commit with `fix: {title} [bug-review]`
7. If tests fail: revert the fix (`git checkout -- <file>`) and report to user
8. After all fixes: push to the PR branch

Safety: one commit per fix, run tests between fixes, never force-push, scope-validate every fix.

## Command: /bug-review:resolve <PR>

Run after a PR is merged to classify whether findings were resolved.

1. Run `scripts/classify-resolutions.sh <pr-number>`
   - Loads stored findings from `${CLAUDE_PLUGIN_DATA}/bug-review/findings/pr-{N}.json`
   - Checks if PR is merged
   - For each finding: diffs code between review commit and merge commit
   - Classifies each as RESOLVED, UNRESOLVED, or INCONCLUSIVE
   - Updates the stored findings file with resolution data
2. Display resolution summary to user
3. If enough data accumulated (10+ findings, 3+ PRs): run `scripts/update-weights.sh` to adjust category weights

## Command: /bug-review:report

Display resolution rate statistics across all tracked PRs.

Run `scripts/resolution-report.sh` which outputs:
- Overall resolution rate
- Resolution rate by severity
- Resolution rate by category (sorted worst-first to highlight noisy categories)
- Suppressed categories (weight < 0.1)

## Repo-Specific Rules (.bug-review.md)

Teams can create `.bug-review.md` at their repo root:

```markdown
## Focus Areas
- Pay special attention to authentication flows
- Check all database queries for SQL injection

## Ignore
- Don't flag issues in generated files (*.generated.ts)
- Ignore style-only concerns

## Invariants
- All API endpoints must check req.user before accessing user data
- Database migrations must be reversible

## Severity Overrides
- Treat any auth bypass as CRITICAL regardless of category default
```

## How to Use

Read [workflow.md](references/workflow.md) for detailed step-by-step with error handling.
Read [review-passes.md](references/review-passes.md) for all 5 review pass prompts and the validator.
Read [categories.md](references/categories.md) for bug categories and learned weights.

## Related Skills

- Consider creating a **Runbook** skill for investigating bugs found by this review
- Consider creating a **CI/CD** skill to run this review automatically on PR open

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Code review and refactoring →

From the same set139

The whole set →
swift-data Guidance for building a SwiftData data layer in modular iOS 26 apps using Swift 6.2. Use it when shaping models, repositories, persistence, or sync flows. CX Codex +1 275installs ios-chaos-monkey ios-chaos-monkey is a Claude Code skill with crash-hunting rules and TDD patterns for finding crashes and data races in Swift 6.2 iOS apps. CX Codex +1 274installs nginx-c-module-perf The nginx-c-module-perf skill guides performance and reliability work on nginx C modules. Use it when tuning buffers, connections, caching, or error handling. CX Codex +1 267installs react-native-elements This skill guides React Native Elements setup, component choices, theming, and list performance. Use it while building or reviewing a React Native app with RNE. CX Codex +1 265installs effect-ts A skill providing patterns and reference guides for Effect-TS: typed error channels, Effect.gen flows, Layers, and fiber concurrency. CX Codex +1 263installs nginx-c-module-debug The nginx-c-module-debug skill guides diagnosis of nginx C module crashes, memory faults, and request-flow problems. Use it for GDB, core dumps, and tracing. CX Codex +1 260installs rust-write-tests rust-write-tests guides coding agents in writing deep Rust tests that target invariants, isolate test files, and systematically eradicate flaky async test runs. CX Codex +1 257installs rails-application-ui-blocks rails-application-ui-blocks is a Claude Code skill that assembles UI blocks in Ruby on Rails ERB views while preserving Turbo, Stimulus, and accessibility hooks. CX Codex +1 257installs

Project sponsors

Companies that keep this analytics open