tony 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
$ARGUMENTScontains a PR number (e.g.,#42,42) or URL, use it directly - If
$ARGUMENTSis 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.