reviewing-pr-description

# Reviewing PR Description Review a PR's **title and description** for readability: do they clearly and concisely tell a reviewer what changed and why? Focus on the prose — checking the *format* (title pattern, required template sections) is a secondary, lighter concern. This skill only evaluates: it produces findings with concrete proposed rewrites and does **not** apply them. The caller decides whether to apply the rewrites or present them as feedback. ## Audience The reader is a **reviewer or teammate skimming the PR to understand what changed and why**. They may not know the implementation context, and later readers will find this text via the commit log or changelog. The title and description should stand on their own. ## Principles 1. **Lead with the change and its purpose** — the first sentence should state what changed and why, not setup, process, or a description of the problem area. 2. **Explain intent, not mechanics** — say what the change enables or why it was made; don't narrate the diff step by step. 3. **Cut what the diff already shows** — omit routine, obvious changes (added tests, updated types, fixed lint). Call out only what's non-obvious or decision-worthy. 4. **Concise wins** — fewer, denser bullets beat many thin ones. If a bullet restates the title or another bullet, drop it. 5. **Explain non-obvious decisions** — deprecations, unit choices, fallback behavior, and trade-offs deserve a sentence on *why*. 6. **Avoid jargon without context** — spell out internal terms or acronyms a newcomer wouldn't know. 7. **Active voice; name the actor** — "Deprecates `use_container_width`" or "The server now rejects oversized uploads" reads more directly than passive or vague phrasing. 8. **The title stands alone** — it should convey the change on its own in a commit list or changelog, without the body. 9. **No meta-commentary** — cut "This PR...", "We have...", "I added..."; state what changed directly. ## Evaluation Process 1. **Gather** the PR title and description (`gh pr view <n> --json title,body`). 2. **For each, ask**: - Does the title convey the change on its own, or does it need the body to make sense? - Does the description lead with the main change and its purpose, or bury it under context/mechanics? - Does it explain *why* for non-obvious decisions, or only list *what*? - Is there jargon or an acronym a newcomer wouldn't understand? - Could it be shorter — are there obvious or duplicated points to cut? - Is it in passive or vague voice where naming the actor would read more directly? - Is there meta-commentary that adds no information? 3. **Also confirm the format** briefly (secondary): title matches `[type] Description` within ~63 chars, and the required template sections from `.github/pull_request_template.md` are present. For the full standards, see `creating-pull-requests` and `wiki/pull-requests.md`. 4. **Report** the findings per the Output Format below. ## Common Patterns to Flag - A title that only makes sense alongside the body (e.g. "[fix] Fix the bug") - A description that opens with context or process instead of the change itself - Bullets that restate the diff (added tests, updated types) instead of explaining intent - Non-obvious decisions (deprecations, fallbacks, unit choices) stated without the *why* - Internal jargon or acronyms with no expansion - Passive or actor-less phrasing where naming the actor reads more directly - Meta-commentary ("This PR...", "I added...") that could be cut - More bullets than the change warrants, or bullets that duplicate each other ## Output Format For the title and for the description, give the issue and a concrete proposed rewrite.