Skip to main content
AI/MLWaterplanAI

gh-pr-review

Reviews GitHub PRs with multi-agent orchestration for comprehensive validation. Triggers on keywords: PR review, review PR, GitHub PR review, pull request review

Stars
31
Source
WaterplanAI/agentic-config
Updated
2026-05-25
Slug
WaterplanAI--agentic-config--gh-pr-review
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/WaterplanAI/agentic-config/HEAD/plugins/ac-qa/skills/ac-qa/gh-pr-review/SKILL.md -o .claude/skills/gh-pr-review.md

Drops the SKILL.md into .claude/skills/gh-pr-review.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

GitHub PR Review

Review the GitHub pull request with comprehensive validation using multi-agent orchestration.

Inputs

  • PR_LINK: $1 (GitHub PR URL, e.g., https://github.com/owner/repo/pull/123)
  • EXPECTED_CHANGES: $2 (Brief description of expected changes)
  • REPORT_PATH: $3 (Optional; defaults to tmp/mux/{date}-{uuid}/PR-{PR_NUMBER}-{UUID}.md)

Pre-Flight

  1. Extract PR number from URL: $1
  2. Generate UUID for this review session
  3. Create output directory: tmp/mux/{date}-{uuid}/

Step 1: Fetch PR Data

Use gh CLI to gather PR information:

gh pr view <PR_NUMBER> --json title,body,author,state,baseRefName,headRefName,files,additions,deletions,commits
gh pr diff <PR_NUMBER>
gh pr view <PR_NUMBER> --json comments,reviews
gh pr checks <PR_NUMBER>

Store PR metadata for agent context.

Step 2: Launch Review Agents (PARALLEL)

Use the Task tool to spawn 5 agents in parallel. Each agent writes findings to its output file.

Agent 1: Expected Changes Validation

Subagent type: general-purpose Task: Compare PR diff against expected changes: $2

  • Identify missing expected changes
  • Identify unexpected/out-of-scope changes
  • Report alignment score (1-10) and gaps
  • Write summary to: {OUTPUT_DIR}/01_expected_changes.md

Agent 2: Security Review

Subagent type: general-purpose Task: Security review of PR diff

  • Check for hardcoded secrets/credentials
  • Check for SQL injection, command injection, XSS vulnerabilities
  • Check for insecure dependencies
  • Check for permission/auth issues
  • Reference OWASP Top 10
  • Write summary to: {OUTPUT_DIR}/02_security.md

Agent 3: Code Quality Review

Subagent type: general-purpose Task: Code quality review of PR diff

  • Validate against project conventions (if documented)
  • RUN project-configured linters and type checkers on changed files from PR diff
  • REPORT any NEW violations introduced by this PR (ignore pre-existing issues)
  • REPORT any pre-commit hook failures with remediation guidance (if hooks are configured)
  • Check type annotations present and correct
  • Check error handling (re-raise, no silent failures)
  • Check function complexity and readability
  • Check naming conventions and import organization
  • Write summary to: {OUTPUT_DIR}/03_code_quality.md

Agent 4: Test Discovery & Execution

Subagent type: general-purpose Task: Discover and run tests from PR

  • Find test files in diff
  • Find CLI configurations (test.json, cli.py patterns)
  • Execute discovered tests with pytest
  • Report pass/fail with output
  • Write summary to: {OUTPUT_DIR}/04_tests.md

Agent 5: Logic & Bug Risk Analysis (CRITICAL)

Subagent type: general-purpose Model: opus (requires deep reasoning) Task: Critical evaluation of logic changes and bug introduction risk

Logic Correctness Review

  • Intent vs Implementation: Does the code actually achieve what it's supposed to?
  • Edge Cases: Identify unhandled edge cases (nulls, empty collections, boundary values)
  • State Management: Check for race conditions, stale state, improper state transitions
  • Control Flow: Verify branching logic, loop terminations, early returns are correct
  • Data Flow: Trace data through the change - are transformations correct?

Bug Introduction Risk

  • Behavioral Regressions: Changes that might break existing functionality
  • Silent Failures: Paths where errors could be swallowed or ignored
  • Type Coercion Issues: Implicit conversions that might lose data or precision
  • Off-by-One Errors: Index/range calculations
  • Null Reference Risks: Accessing properties on potentially null/undefined values
  • Resource Leaks: Unclosed connections, file handles, memory allocations

Logic Smell Detection

  • Inverted Conditions: Logic that does the opposite of what variable names suggest
  • Dead Code Paths: Unreachable branches introduced by the change
  • Contradictory Logic: Conditions that can never be true together
  • Missing Validation: Input assumptions not validated
  • Inconsistent Handling: Similar cases handled differently without reason

Impact Analysis

  • Downstream Effects: What other components rely on changed code?
  • Contract Violations: Does the change break implicit contracts with callers?
  • Assumption Changes: Are assumptions about data/state still valid?

Output Format

For each issue found:

[SEVERITY] - [Category]
Location: file:line
Issue: [description]
Why it's a bug: [reasoning]
Fix suggestion: [if applicable]
  • Write summary to: {OUTPUT_DIR}/05_logic_bugs.md

Step 3: Aggregate Results

After ALL agents complete:

  1. Read all agent summaries from {OUTPUT_DIR}/*.md
  2. Synthesize findings into consolidated report

Step 4: Generate Review Report

Create report at: $3 or tmp/mux/{date}-{uuid}/PR-{PR_NUMBER}-{UUID}.md

Report Template

# PR Review: #{PR_NUMBER}

**URL**: {PR_URL}
**Title**: {PR_TITLE}
**Author**: {AUTHOR}
**Branch**: {HEAD} -> {BASE}
**Review Session**: {UUID}
**Date**: {TIMESTAMP}

---

## Executive Summary

{Overall assessment: APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION}

### Scores
| Category | Score | Status |
|----------|-------|--------|
| Expected Changes Alignment | X/10 | {emoji} |
| Logic & Bug Risk | X/10 | {emoji} |
| Security | X/10 | {emoji} |
| Code Quality | X/10 | {emoji} |
| Tests | X/10 | {emoji} |

---

## Detailed Findings

### Expected Changes
{From Agent 1}

### Logic & Bug Risk (CRITICAL)
{From Agent 5 - This section requires careful review}

#### Logic Issues Found
{List of logic correctness problems}

#### Potential Bugs Introduced
{List of bug risks with severity and reasoning}

#### Impact Assessment
{Downstream effects and contract changes}

### Security
{From Agent 2}

### Code Quality
{From Agent 3}

### Test Results
{From Agent 4}

---

## PR Review Comments

| File | Line | Severity | Comment |
|------|------|----------|---------|
| path/file.py | 42 | ERROR | Issue description |

---

## PR Review Message

{Copy-paste ready message for GitHub PR comment}

### Recommendation
- APPROVE: Ready to merge
- REQUEST_CHANGES: Must address before merge
- COMMENT: No blocking issues

---

## Next Steps
{Actionable recommendations}

Step 5: Present Results

Output summary to user:

PR REVIEW COMPLETE

PR: #{PR_NUMBER} - {TITLE}
Report: {REPORT_PATH}

Top Issues:
{Critical findings}

Proposed Actions:
1. Post review: gh pr review {PR_NUMBER} --comment --body-file {REPORT}
2. Request changes: gh pr review {PR_NUMBER} --request-changes
3. Approve: gh pr review {PR_NUMBER} --approve

Which action?

Safety

  • READ-ONLY GitHub operations (no automatic posting)
  • All review comments require USER CONFIRMATION before posting
  • Tests run in local environment only
  • Sensitive data redacted from reports