Pr Review

PR Review

Overview

This skill enables comprehensive, objective-driven PR reviews. Given a GitHub PR URL, it:

1. Clones/checks out the repository to the correct branch
2. Validates the PR has linked issues (GitHub or Jira) for context
3. Reads the linked issue to understand the PR's objective
4. Discovers any review standards or agents defined in the repository
5. Analyzes code changes against the objective and standards
6. Runs tests and analyzes GitHub Actions for failures
7. Posts inline comments on critical issues
8. Provides a structured summary

Key principle: Reviews are objective-driven. Every critical issue is framed against the stated goal from the linked issue, and suggestions are non-blocking (we bias toward shipping).

Prerequisites

Quick Check: Run the prerequisite checker to verify your environment is ready:

python3 scripts/check_prerequisites.py

This validates:

• ✅ Python 3.6+
• ✅ Git 2.0+
• ✅ GitHub CLI (gh) with authentication
• ✅ gh pr-review extension
• ✅ Standard Python library modules
• ✅ Optional: uv (Python runner for faster execution)
• ✅ GitHub API access

Manual Prerequisites:

• gh CLI installed and authenticated: gh auth status
• gh pr-review extension: gh extension install agynio/gh-pr-review
• Git: git --version
• Python 3.6+: python3 --version
• Read/write access to target repositories

Recommended (optional but faster):

• uv (Python runner): https://docs.astral.sh/uv/ — Enables 10x faster script startup

For detailed setup instructions, see references/prerequisites.md.

PR Review Workflow

See references/workflow.md for the complete decision tree and multi-step process.

Summary:

1. Parse PR URL → Extract owner, repo, PR number
2. Clone & checkout → Repository ready at ~/{owner}/{repo}/
3. Validate issue link → 🚨 Flag if missing
4. Understand objective → Read linked GitHub issue or Jira ticket
5. Discover standards → Find .github/agents/*.md, .claude/agents/*.md, etc.
6. Analyze code → Diff against objective
7. Check for critical issues → Security, breaking changes, architectural violations
8. Run tests → Capture failures and errors
9. Analyze GitHub Actions → Deep-dive into workflow failures
10. Post comments → Inline comments for critical issues + summary

Key Scripts

All scripts output JSON for easy parsing. They handle error cases gracefully.

Running scripts: Use ./scripts/run_script.sh wrapper (automatically uses uv if available, falls back to python3):

./scripts/run_script.sh  [args...]

Or run directly with python3:

python3 scripts/ [args...]

check_prerequisites.py

Validates all prerequisites are installed and configured correctly.

./scripts/run_script.sh check_prerequisites.py
# Or: python3 scripts/check_prerequisites.py --verbose
# Output: JSON with status of all checks
# Exit code: 0 if ready, 1 if missing prerequisites

parseprurl.py

Extracts owner, repo, and PR number from a GitHub PR URL.

./scripts/run_script.sh parse_pr_url.py "https://github.com/owner/repo/pull/123"
# Output: {"owner": "owner", "repo": "repo", "pr_number": 123, "url": "..."}

cloneandcheckout.py

Clones (or updates) the repository and checks out the PR's actual branch.

./scripts/run_script.sh clone_and_checkout.py owner repo 123
# Output: {"checkout_dir": "~/owner/repo", "branch_name": "feature-xyz", "commit_sha": "abc123..."}

checklinkedissue.py

Validates and fetches linked GitHub issues and Jira keys from the PR.

./scripts/run_script.sh check_linked_issue.py owner repo 123 --repo-dir ~/owner/repo
# Output: {"linked_issues": [...], "has_linked_issues": true, "jira_issues": ["PROJ-123"], ...}

findreviewagents.py

Searches the repository for review agents or standards in .github/agents/*.md, .claude/agents/*.md, etc.

./scripts/run_script.sh find_review_agents.py ~/owner/repo
# Output: {"found_agents": [{path, name, content_preview, ...}], "count": 2, ...}

run_tests.py

Auto-detects test framework (pytest, go test, npm test, cargo, terraform test) and runs tests.

./scripts/run_script.sh run_tests.py ~/owner/repo
# Output: {"framework": "pytest", "status": "passed|failed", "exit_code": 0, "stdout": "...", ...}

analyzegithubactions.py

Fetches recent GitHub Actions workflow runs for the PR branch and identifies failures.

./scripts/run_script.sh analyze_github_actions.py owner repo 123 --repo-dir ~/owner/repo
# Output: {"branch": "feature-xyz", "workflow_runs": [{number, status, jobs, ...}], ...}

Code Review Standards

See references/review-criteria.md for:

• What constitutes a critical issue (vs. non-blocking suggestions)
• Security review checklist
• Architecture and design checklist
• Language-specific considerations (Terraform, Python, Go, TypeScript, SQL)
• Review bias: We favor shipping over perfection

Inline Comments & CI/CD Integration

See references/gh-pr-review.md for:

• How to post inline comments using gh pr-review CLI
• Batch comment patterns
• Error handling and troubleshooting
• Integration with the review workflow

Execution Strategy

When executing a PR review, follow this structure:

Step 0: Verify Prerequisites

# Check all prerequisites before starting
./scripts/run_script.sh check_prerequisites.py

# Should show all checks passing (except gh pr-review if not installed)
# If not, follow the installation instructions

Step 1: Setup

cd ./skills/pr-review

# Parse URL (using uv if available, else python3)
metadata=$(./scripts/run_script.sh parse_pr_url.py "$PR_URL")
owner=$(echo $metadata | jq -r .owner)
repo=$(echo $metadata | jq -r .repo)
pr_number=$(echo $metadata | jq -r .pr_number)

# Clone/checkout
checkout=$(./scripts/run_script.sh clone_and_checkout.py $owner $repo $pr_number)
repo_dir=$(echo $checkout | jq -r .checkout_dir)
branch=$(echo $checkout | jq -r .branch_name)

Step 2: Issue & Standards

# Validate linked issue
issue_check=$(./scripts/run_script.sh check_linked_issue.py $owner $repo $pr_number --repo-dir $repo_dir)

# Find repo-defined review standards
agents=$(./scripts/run_script.sh find_review_agents.py $repo_dir)
# Load and read any found agents to understand review standards

Step 3: Code Analysis

• Get the full diff: git diff origin/main..HEAD
• Analyze against the linked issue objective
• Identify critical issues using references/review-criteria.md

Step 4: Testing & CI/CD

# Run tests
tests=$(./scripts/run_script.sh run_tests.py $repo_dir)

# Analyze GitHub Actions
actions=$(./scripts/run_script.sh analyze_github_actions.py $owner $repo $pr_number --repo-dir $repo_dir)

Step 5: Post Comments

For each critical issue identified:

gh pr-review ${owner}/${repo}#${pr_number} \
  --comment "Issue description" \
  --file relative/path/to/file.go \
  --line 42

Then post a summary comment with overall findings.

Practical Example

cd ./skills/pr-review
PR_URL="https://github.com/ORG/my-terraform-repo/pull/33"

# 0. Check prerequisites (first time only)
./scripts/run_script.sh check_prerequisites.py

# 1. Parse
./scripts/run_script.sh parse_pr_url.py "$PR_URL"
# → owner: ORG, repo: terraform-aws-MSKServerless, pr_number: 33

# 2. Clone & checkout
./scripts/run_script.sh clone_and_checkout.py ORG my-terraform-repo 33
# → repo at ~/ORG/my-terraform-repo/, branch: 8-vpc-authorization-patterns

# 3. Check for linked issue
./scripts/run_script.sh check_linked_issue.py ORG my-terraform-repo 33 \
  --repo-dir ~/ORG/my-terraform-repo
# → If no linked issue: 🚨 FLAG

# 4. Find review agents (if any)
./scripts/run_script.sh find_review_agents.py ~/ORG/my-terraform-repo
# → Check .github/agents/, .claude/agents/, etc.

# 5. Analyze code diff manually
cd ~/ORG/my-terraform-repo
git diff origin/main..HEAD --stat
git diff origin/main..HEAD | head -200  # first 200 lines of diff

# 6. Run tests (with automatic framework detection)
cd ./skills/pr-review
./scripts/run_script.sh run_tests.py ~/ORG/my-terraform-repo

# 7. Check GitHub Actions
./scripts/run_script.sh analyze_github_actions.py ORG my-terraform-repo 33

# 8. Post inline comments for critical issues
gh pr-review ORG/my-terraform-repo#33 \
  --comment "Hardcoded secret detected. Move to environment variable." \
  --file variables.tf \
  --line 15

# 9. Post summary
gh pr-review ORG/my-terraform-repo#33 \
  --comment "## Summary
...findings..."

Note: All ./scripts/run_script.sh calls automatically use uv if available, otherwise fall back to python3.

Review Quality

The quality of a review depends on:

1. Clarity of the objective — Is the linked issue well-defined?
2. Context of changes — Does the diff make sense in isolation?
3. Reproducibility — Can you verify test failures?
4. Actionability — Are comments specific and solvable?

Limitations & Notes

• No line-level commenting on unmodified lines — The gh pr review CLI can only comment on lines in the diff
• Test execution depends on environment — If tests require special setup (databases, keys, etc.), results may be incomplete
• GitHub Actions deep-dive is async — Workflow logs are read-only; fixing requires PR author's actions
• Review agents are optional — Not all repos document standards; default to references/review-criteria.md
• Bias toward action — We call out blockers, not style issues; we want code to ship

Troubleshooting

Quick Diagnosis

Always start with the prerequisite checker:

./scripts/run_script.sh check_prerequisites.py

This will identify most issues and provide installation commands.

Common Issues

| Issue | Solution | |-------|----------| | Prerequisites failing | Run ./scripts/run_script.sh check_prerequisites.py for detailed diagnosis | | gh: command not found | Install GitHub CLI: brew install gh or https://cli.github.com/ | | gh auth shows "not authenticated" | Run gh auth login and follow prompts | | gh pr-review not found | Install extension: gh extension install agynio/gh-pr-review | | uv not available (slow startup) | Optional but recommended: https://docs.astral.sh/uv/ | | Git clone fails | Verify GitHub access and network | | No linked issue | Add GitHub issue link to PR, then retry | | Tests not detected | Repo may not have tests; continue with code review | | Workflow analysis incomplete | Check if workflows have been run yet on this branch | | Comments won't post | Verify write access: gh repo view owner/repo |

Getting Help

1. Check references/prerequisites.md for detailed setup instructions
2. Run prerequisite checker: ./scripts/run_script.sh check_prerequisites.py --verbose
3. See references/gh-pr-review.md for inline comment issues

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shalomb
• Source: shalomb/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.