| name | gh-pr-review |
| description | Reviews GitHub PRs with multi-agent orchestration for comprehensive validation. Triggers on keywords: PR review, review PR, GitHub PR review, pull request review |
| project-agnostic | true |
| allowed-tools | ["Bash","Read","Write","Grep","Glob","Task","WebFetch"] |
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
- Extract PR number from URL:
$1
- Generate UUID for this review session
- 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:
- Read all agent summaries from
{OUTPUT_DIR}/*.md
- 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
