# Pr Review Pr

> Review a PR description against gold-standard patterns

- Skill: `tony/pr-review-pr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tony/pr-review-pr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tony/pr-review-pr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tony (https://skillmd.com/u/tony)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tony/pr-review-pr

---


# Review PR Description

Evaluate an existing PR description against gold-standard patterns and suggest concrete improvements.

Target PR: $ARGUMENTS

---

## Procedure

### 1. Fetch the PR

- If `$ARGUMENTS` contains a PR number (e.g., `#42`, `42`) or URL, use it directly
- If `$ARGUMENTS` is empty, detect the current branch's PR:
  ```
  gh pr view --json number,title,body,url
  ```
- Fetch the full PR details:
  ```
  gh pr view <number> --json title,body,url
  ```

### 2. Fetch the Diff Context

- Get the PR diff to understand the scope of changes:
  ```
  gh pr diff <number>
  ```
- Count files changed and estimate the magnitude (small fix, medium feature, large overhaul)
- This context is needed to judge whether the description is **proportional** to the change
- If the user's message names a PR template, read it and use its sections as the structural baseline for the evaluation below. Use it silently — this command reports findings and never raises template questions

### 3. Evaluate Against Quality Patterns

Check each applicable dimension. Not every dimension applies to every PR — a one-line typo fix doesn't need a Design Decisions section.

| Dimension | What to check |
|---|---|
| **Structure** | Does it use `## Summary`, `## Changes`, `## Test plan` headings where appropriate for the change size? |
| **Proportionality** | Is the detail level proportional to the diff size? Small fix shouldn't have 20 bullets; large feature shouldn't be one sentence. |
| **Bold impact labels** | Do summary bullets open with **bold verbs** (Fix, Add, Remove, Replace, Migrate)? |
| **Tables** | Are comparison-heavy sections using tables instead of prose? (renames, parameter maps, file inventories, environment matrices) |
| **Code blocks** | One command per block? No comments inside blocks? Explanatory text outside? |
| **Test plan** | Does it have a checklist with `- [x]` or `- [ ]` items? Are items descriptive (what is validated), not just commands? |
| **Design decisions** | For non-trivial changes, are trade-offs explained with rationale? |
| **Verification** | Are there copyable `rg`/`grep` commands proving the change is complete? |
| **Negative assertions** | For removal/migration PRs: "verify zero matches for X" items? |
| **Cross-references** | Companion PRs, related issues, tracking links where relevant? |
| **Before/After** | For behavioral changes, are both states shown in labeled code blocks? |
| **No brittle details** | Does the description avoid test counts, SHAs, line numbers, or file/line-changed counts? These duplicate what the reviewer sees in the diff. |
| **No branch-internal narrative** | Does the description avoid rename history, "no longer X" / "previously Y" phrasing, and `### Fixes` framing for behavior that never appeared in a published release? See `AGENTS.md` § *The Published-Release Test*. |
| **Whole-branch perspective** | Does it describe the net shipped result, or does it narrate the branch's commit-by-commit evolution? |

### 4. Report

Structure the report as:

**What the PR description does well:**
- List specific strengths — reinforce good patterns so the author knows to keep doing them

**Suggested improvements:**
- List specific improvements with **concrete markdown snippets** — not vague advice like "add more detail"
- If a section is missing that the diff warrants, draft it as a ready-to-paste suggestion
- If a section exists but could be improved, show the improved version

**Overall assessment:**
- One sentence summary: is this description adequate, good, or gold-standard?
- For "adequate" or "good" descriptions, identify the single highest-impact improvement

---

## Rules

- **Never** modify the PR — only report findings
- **Never** run destructive git or gh commands
- Suggestions must be **concrete markdown snippets**, not abstract advice
- Evaluate **proportionally** — don't penalize a one-line fix for missing a Design Decisions section
- Recognize and reinforce good patterns — the report should be balanced, not just a list of criticisms
- Check for **brittle details** (test counts, SHAs, line numbers, file-changed counts) — flag them as concrete improvements
- Check for **commit-diary style** — if the description narrates the branch's internal evolution instead of the net result, suggest rewriting to whole-branch perspective


## Portability notes

- `$ARGUMENTS` — the text the user passed when invoking this skill. If your host does not substitute it, read it as the user's request in the current turn, and ask when there is none.