/reviewing-pr-description

name: reviewing-pr-description
description: Evaluates a PR's title and description for readability — do they clearly and concisely convey what changed and why to a reviewer? Produces findings with concrete proposed rewrites; the caller decides whether to apply them or present them as feedback. Use when finalizing a PR or reviewing PR metadata. For code comments, docstrings, and naming, use reviewing-readability instead.

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.