跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

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:

  1. Most bad reviews happen because the reviewer looks at the final diff in isolation and misses the why.
  2. Most over-engineered PRs happen because the contributor builds for imagined future requirements instead of the current problem.
  3. 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 changes
  • CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md if 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 sizeApproach
≤15 commits, ≤30 filesFull reconstruction — read every commit's --stat, inspect files of interest
16–40 commits or 31–80 filesSample — 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 filesShape-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:

CategoryDefinitionReview actions
PrimaryDirectly serves the PR's stated goalRead full file (Phase 4). Check correctness, edge cases, test coverage. Evaluate naming, error paths, and interaction with existing code.
SupportingNecessary plumbing for primary changesVerify it's the minimum change needed. Check: could the primary change work without this? Is the API surface minimal?
Opportunistic fixReal bug fix discovered along the wayConfirm the bug exists on main. Check the fix is correct. Flag for separate PR if it complicates revert.
Scope creepUnrelated improvement or refactorNote in findings. Don't block merge unless it creates risk. Suggest splitting.
ChurnAdded and reverted within the same PRRun 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

阅读完整来源 ↗