Review Pull Request

Review a GitHub pull request end-to-end — from understanding the change through submitting structured feedback. Uses gh CLI for all GitHub interactions and produces severity-leveled review comments.

When to Use

A pull request is ready for review and assigned to you
Performing a second review after the author addresses feedback
Reviewing your own PR before requesting others' review (self-review)
Auditing a merged PR for post-merge quality assessment
When you want a structured review process rather than ad-hoc scanning

Inputs

Required: PR identifier (number, URL, or owner/repo#number)
Optional: Review focus (security, performance, correctness, style)
Optional: Codebase familiarity level (familiar, somewhat, unfamiliar)
Optional: Time budget for the review (quick scan, standard, thorough)

Procedure

Step 1: Understand the Context

Read the PR description and understand what the change is trying to accomplish.

Fetch PR metadata:

gh pr view <number> --json title,body,author,baseRefName,headRefName,labels,additions,deletions,changedFiles,reviewDecision

Read the PR title and description:
- What problem does this PR solve?
- What approach did the author take?
- Are there any specific areas the author wants reviewed?
Check the PR size and assess time required:

PR Size Guide:
+--------+-----------+---------+-------------------------------------+
| Size   | Files     | Lines   | Review Approach                     |
+--------+-----------+---------+-------------------------------------+
| Small  | 1-5       | <100    | Read every line, quick review       |
| Medium | 5-15      | 100-500 | Focus on logic changes, skim config |
| Large  | 15-30     | 500-    | Review by commit, focus on critical  |
|        |           | 1000    | files, flag if should be split       |
| XL     | 30+       | 1000+   | Flag for splitting. Review only the  |
|        |           |         | most critical files.                 |
+--------+-----------+---------+-------------------------------------+

Review the commit history:
```
gh pr view <number> --json commits --jq '.commits[].messageHeadline'
```
- Are commits logical and well-structured?
- Does the history tell a story (each commit a coherent step)?
Check CI/CD status:
```
gh pr checks <number>
```
- Are all checks passing?
- If checks are failing, note which ones — this affects the review

Expected: A clear understanding of what the PR does, why it exists, how big it is, and whether CI is green. This context shapes the review approach.

On failure: If the PR description is empty or unclear, note this as the first piece of feedback. A PR without context is a review antipattern. If gh commands fail, verify you're authenticated (gh auth status) and have access to the repository.

Step 2: Analyze the Diff

Read the actual code changes systematically.

Fetch the full diff:
```
gh pr diff <number>
```
For small/medium PRs, read the entire diff sequentially

For large PRs, review by commit:

gh pr diff <number> --patch  # full patch format

For each changed file, evaluate:
- Correctness: Does the code do what the PR says it does?
- Edge cases: Are boundary conditions handled?
- Error handling: Are errors caught and handled appropriately?
- Security: Any injection, auth, or data exposure risks?
- Performance: Any obvious O(n^2) loops, missing indexes, or memory issues?
- Naming: Are new variables/functions/classes named clearly?
- Tests: Are new behaviors covered by tests?
Take notes as you read, classifying each observation by severity

Expected: A set of observations covering correctness, security, performance, and quality for every meaningful change in the diff. Each observation has a severity level.

On failure: If the diff is too large to review effectively, flag it: "This PR changes {N} files and {M} lines. I recommend splitting it into smaller PRs for more effective review." Still review the highest-risk files.

Step 3: Classify Feedback

Organize observations into severity levels.

Classify each observation:

Feedback Severity Levels:
+-----------+------+----------------------------------------------------+
| Level     | Icon | Description                                        |
+-----------+------+----------------------------------------------------+
| Blocking  | [B]  | Must fix before merge. Bugs, security issues,      |
|           |      | data loss risks, broken functionality.             |
| Suggest   | [S]  | Should fix, but won't block merge. Better           |
|           |      | approaches, missing edge cases, style issues that   |
|           |      | affect maintainability.                            |
| Nit       | [N]  | Optional improvement. Style preferences, minor      |
|           |      | naming suggestions, formatting.                    |
| Praise    | [P]  | Good work worth calling out. Clever solutions,      |
|           |      | thorough testing, clean abstractions.              |
+-----------+------+----------------------------------------------------+

For each Blocking item, explain:
- What's wrong (the specific issue)
- Why it matters (the impact)
- How to fix it (a concrete suggestion)
For each Suggest item, explain the alternative and why it's better
Keep Nits brief — one sentence is enough
Include at least one Praise if anything positive stands out

Expected: A sorted list of feedback items with clear severity levels. Blocking items have fix suggestions. The ratio should generally be: few Blocking, some Suggest, minimal Nit, at least one Praise.

On failure: If everything seems blocking, the PR may need to be reworked rather than patched. Consider requesting changes at the PR level rather than line-by-line comments. If nothing seems wrong, say so — "LGTM" is valid feedback when the code is good.

Step 4: Write Review Comments

Compose the review with structured, actionable feedback.

Write the review summary (top-level comment):
- One sentence: what the PR does (confirm understanding)
- Overall assessment: approve, request changes, or comment
- Key items: list Blocking issues (if any) and top Suggest items
- Praise: call out good work

Write inline comments for specific code locations:

# Post inline comments via gh API
gh api repos/{owner}/{repo}/pulls/{number}/comments \
  -f body="[B] This SQL query is vulnerable to injection. Use parameterized queries instead.\n\n\`\`\`suggestion\ndb.query('SELECT * FROM users WHERE id = $1', [userId])\n\`\`\`" \
  -f commit_id="<sha>" \
  -f path="src/users.js" \
  -F line=42 \
  -f side="RIGHT"

Format feedback consistently:
- Start each comment with the severity tag: [B], [S], [N], or [P]
- Use GitHub suggestion blocks for concrete fixes
- Link to documentation for style/pattern suggestions

Submit the review:

# Approve
gh pr review <number> --approve --body "Review summary here"

# Request changes (when blocking issues exist)
gh pr review <number> --request-changes --body "Review summary here"

# Comment only (when unsure or providing FYI feedback)
gh pr review <number> --comment --body "Review summary here"

Expected: A submitted review with clear, actionable feedback. The author knows exactly what to fix (Blocking), what to consider (Suggest), and what went well (Praise).

On failure: If gh pr review fails, check permissions. You need write access to the repo or to be a requested reviewer. If inline comments fail, fall back to putting all feedback in the review body with file:line references.

Step 5: Follow Up

Track the review resolution.

After the author responds or pushes updates:

gh pr view <number> --json reviewDecision,reviews

Re-review only the changes that address your feedback:
```
gh pr diff <number>  # check new commits
```
Verify Blocking items are resolved before approving
Resolve comment threads as issues are addressed

Approve when all Blocking items are fixed:

gh pr review <number> --approve --body "All blocking issues resolved. LGTM."

Expected: Blocking issues verified as fixed. Review conversation resolved. PR approved or further changes requested with specific remaining items.

On failure: If the author disagrees with feedback, discuss in the PR thread. Focus on impact (why it matters) rather than authority. If disagreement persists on non-blocking items, yield gracefully — the author owns the code.

Validation Checklist

PR context understood (purpose, size, CI status)
All changed files reviewed (or highest-risk files for XL PRs)
Feedback classified by severity (Blocking/Suggest/Nit/Praise)
Blocking items have specific fix suggestions
At least one Praise included for positive aspects
Review decision matches feedback (approve only if no Blocking items)
Inline comments reference specific lines with severity tags
CI/CD checks verified (green before approval)
Follow-up completed after author's revisions

Common Pitfalls

Rubber-stamping: Approving without actually reading the diff. Every approval is an assertion of quality
Nit avalanche: Drowning the author in style preferences. Save nits for mentoring situations; skip them in time-sensitive reviews
Missing the forest: Reviewing line-by-line without understanding the overall design. Read the PR description and commit history first
Blocking on style: Formatting and naming are almost never blocking. Reserve Blocking for bugs, security, and data integrity
No praise: Only pointing out problems is demoralizing. Good code deserves recognition
Review scope creep: Commenting on code that wasn't changed in the PR. If pre-existing issues bother you, file a separate issue

Related Skills

review-software-architecture — System-level architecture review (complementary to PR-level review)
security-audit-codebase — Deep security analysis for PRs with security-sensitive changes
create-pull-request — The other side of the process: creating PRs that are easy to review
commit-changes — Clean commit history makes PR review significantly easier

review-pull-request