review-pr

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

```bash
git remote -v
```

**GitHub (primary path):**

```bash
gh pr view <N> --json baseRefName,headRefName,title,body,commits,files,statusCheckRollup,reviews
```

**Fallback (no `gh` CLI or non-GitHub remote):**

```bash
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

```bash
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

```bash
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

```bash
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:**

```bash
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. |

From jcottam/agent-resources, MIT.

More from jcottam/agent-resources