Review a GitHub pull request by summarizing its diff and key design decisions. Use when the user wants to review a PR, understand changes in a branch, or get a code review summary. Trigger keywords - review PR, review pull request, summarize PR, summarize diff, code review, review branch, PR summary, diff summary.
Summarize a GitHub pull request diff, highlighting key design decisions and notable code snippets.
gh CLI must be authenticated (gh auth status)The user will provide either a PR number (e.g., #123 or 123) or a branch name. Determine which input was given and resolve it to a PR.
Strip any leading # and use the numeric ID directly. Proceed to Step 2.
Look up the open PR whose head branch matches:
gh pr list --head "<branch>" --state open
Retrieve the PR metadata:
gh pr view <number> --json title,body,state,headRefName,baseRefName,labels,author
Record the title, body, headRefName, and baseRefName for use in later steps.
Fetch the diff via the GitHub CLI:
gh pr diff <number>
If this succeeds, use this diff and proceed to Step 4.
If no PR exists (branch-only case) or the gh diff command fails, fall back to a local diff:
# Ensure both branches are available locally
git fetch origin <target-branch> <source-branch>
# Generate the diff
git diff origin/<target-branch>...origin/<source-branch>
If the user provided a branch name and no PR was found, diff against main:
git fetch origin main <branch>
git diff origin/main...origin/<branch>
If the diff output is very large (thousands of lines), use the Task tool to process it in chunks. Summarize each chunk independently, then merge the summaries. Do not skip or truncate parts of the diff — accuracy depends on reading all of it.
Read through the full diff (and the PR description if available). Produce a summary with the following sections. Keep every section as concise as possible — brevity is a priority.
## PR Review: <title>
**PR:** [#<number>](<url>) <- only if a PR exists
**Author:** <author>
**Branch:** `<source>` -> `<target>`
### Overview
<1-3 sentences describing what this PR does and why>
### Key Design Decisions
- <decision 1 with file:line reference>
- <decision 2 with file:line reference>
- ...
### Notable Code
<short fenced code snippets that illustrate the most important changes -- max 3 snippets>
### Potential Concerns <- omit if none
- <risk or issue worth discussing>
Guidelines for the summary:
file_path:line_number references. Examples: choice of algorithm, new abstraction introduced, API contract change, migration strategy.Print the summary directly in the chat as formatted markdown.
If the user requests it, also save the summary to a file:
# Default path
reviews/<number>-review.md
# Or for branch-only reviews
reviews/<branch-name>-review.md
| Command | Description |
|---|---|
gh pr list --head <branch> | Find PR by head branch |
gh pr diff <number> | Get PR diff |
gh pr view <number> --json ... | Get full PR metadata |
git diff origin/<target>...origin/<source> | Local diff between branches |
User says: "Review PR #456"
gh pr diff 456User says: "Review branch feature/add-pagination"
gh pr list --head "feature/add-pagination"