review-pr
Forensic, stage-aware pull request review. Reconstructs the commit narrative, tests architectural premises against project reality, detects over-engineering, and produces a ready-to-post review comment. Use when the user says "review PR", "review this PR", "review PR #N", "is this PR ready to merge", "review the diff", or any variation of wanting to critically evaluate a pull request for merge readiness. Do NOT use for branch summaries or "what does this PR do" questions — those are explanation tasks, not reviews.
jcottam · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jcottam/agent-resources --skill review-pr技能说明
name: review-pr description: >- Forensic, stage-aware pull request review. Reconstructs the commit narrative, tests architectural premises against project reality, detects over-engineering, and produces a ready-to-post review comment. Use when the user says "review PR", "review this PR", "review PR #N", "is this PR ready to merge", "review the diff", or any variation of wanting to critically evaluate a pull request for merge readiness. Do NOT use for branch summaries or "what does this PR do" questions — those are explanation tasks, not reviews. license: MIT metadata: author: jcottam version: "4.0.0"
Review PR
Forensic, stage-aware pull request review. Reconstructs the commit narrative, tests the PR's architectural premises against project reality, and produces a review comment the user can post directly.
Three core insights:
- Most bad reviews happen because the reviewer looks at the final diff in isolation and misses the why.
- Most over-engineered PRs happen because the contributor builds for imagined future requirements instead of the current problem.
- Most shallow reviews happen because the reviewer catalogs file-level findings without first understanding what the change means for the product. Think about the product impact before diving into the code.
Phase 1 — Orientation
Before reading any code, establish context.
1. Get PR metadata
git remote -v
GitHub (primary path):
gh pr view <N> --json baseRefName,headRefName,title,body,commits,files,statusCheckRollup,reviews
Fallback (no gh CLI or non-GitHub remote):
git log --oneline <base-branch>..<pr-branch>
git diff --stat <base-branch>...<pr-branch>
Use the resolved base/head branch names for all subsequent commands.
2. Read project conventions
Before forming opinions, read the project's own rules:
AGENTS.md— architecture, boundaries, "always do / never do" lists.cursor/rules/— workspace rules that apply to all changesCONTRIBUTING.md,.github/PULL_REQUEST_TEMPLATE.mdif present
If none of these exist, infer conventions from the existing codebase: look at 2–3 files in the same directory as the PR's primary changes. Match naming, error handling patterns, test structure, and abstraction level already established.
These are the standards the PR should be measured against, not generic best practices.
3. Read the PR description and commit messages
git log <base-branch>..<pr-branch> --reverse --format="%h %s%n%n%b"
Extract what the PR claims to do. Do not treat claims as fact until the diff confirms them. Form your own judgment of scope and risk before reading existing review comments or the user's opinion.
4. Check CI status
If checks are failing, lead with that.
5. Get the shape
git diff --stat <base-branch>...<pr-branch>
Flag anything unexpected: utility files touched by a feature PR, large line counts unrelated to the stated goal, test files present or absent.
Phase 2 — Timeline Reconstruction
git log <base-branch>..<pr-branch> --reverse --oneline
Scaling strategy
| PR size | Approach |
|---|---|
| ≤15 commits, ≤30 files | Full reconstruction — read every commit's --stat, inspect files of interest |
| 16–40 commits or 31–80 files | Sample — read first commit, last commit, and any commit whose message signals a pivot ("revert", "actually", "try different approach"). Focus on the 5 highest-churn files. |
| >40 commits or >80 files | Shape-only — read --stat for all commits but only inspect the 3–5 files with the largest net diff. Note in findings that full reconstruction was not feasible. |
Reconstruction
For each commit in scope, read git show <sha> --stat and inspect files of
interest.
Build a timeline: what was attempted first, were there course corrections, did the contributor fix their own mistakes within the branch?
Reversals and churn — commit N adds something, commit N+M removes it. Normal and healthy. Flag only if intermediate complexity survives in the final state.
Net diff is ground truth:
git diff <base-branch>...<pr-branch>
Individual commits explain why; the net diff is what lands.
Phase 3 — Categorize Changes
For each file in the net diff:
| Category | Definition | Review actions |
|---|---|---|
| Primary | Directly serves the PR's stated goal | Read full file (Phase 4). Check correctness, edge cases, test coverage. Evaluate naming, error paths, and interaction with existing code. |
| Supporting | Necessary plumbing for primary changes | Verify it's the minimum change needed. Check: could the primary change work without this? Is the API surface minimal? |
| Opportunistic fix | Real bug fix discovered along the way | Confirm the bug exists on main. Check the fix is correct. Flag for separate PR if it complicates revert. |
| Scope creep | Unrelated improvement or refactor | Note in findings. Don't block merge unless it creates risk. Suggest splitting. |
| Churn | Added and reverted within the same PR | Run git diff <base>...<head> -- <file> to confirm net-zero. If not net-zero, reclassify. |
Shared utility changes get extra scrutiny: is the API change justified by more than one caller? Could the same result be achieved without modifying the shared surface?
Phase 4 — Read the Current State
For files categorized as Primary, read the full file on the PR branch:
git show <pr-branch>:<path/to/file>
Diffs show what changed but hide whether the result is coherent. Check for leftover artifacts, naming consistency, dead imports. Understanding the full file prevents forming architectural opinions from incomplete context — a diff that looks over-engineered may match patterns already established in the file.
For large files (>500 lines), read at minimum the 50 lines surrounding each change hunk
阅读完整来源 ↗