PR Description Skill

SKILL.md

name	pr-description
description	Generate a reviewer-first pull request description from the current Git branch, formatted for GitHub or Bitbucket Cloud. Use this whenever the user asks to write, draft, generate, or update a PR description, PR summary, merge request description, or asks "what should I put in the PR". Also use when the user asks to summarize a branch's changes or a diff for a reviewer.

PR Description

Generate a pull request description that helps a reviewer approve and merge with confidence — not a restatement of the diff.

Step 1: Determine branches

• Default: current branch → develop (or main/master if develop doesn't exist).
• If the user names a target branch, use that instead.
• If unsure which branch is "current," ask — don't guess on something this cheap to confirm.

Step 2: Gather evidence

Run these before writing anything:

git rev-parse --abbrev-ref HEAD                    # confirm source branch
git merge-base <source> <target>                   # find divergence point
git log <target>..<source> --oneline                # commit history for context
git diff <target>...<source>                        # the actual change
git diff <target>...<source> --stat                  # which files, how much

Also check, if present: linked ticket/ID in branch name or commits, CHANGELOG.md, migration files, feature-flag config, .env.example changes.

Read the full diff, not just the stat. Ignore formatting-only, lockfile, and generated-file changes unless they affect behavior. If the diff is large, prioritize reading files most likely to matter for review: public API surfaces, migrations, auth/permissions, config, anything touching money, PII, or external calls.

If git isn't available or the diff can't be determined, say so plainly and ask for the changes instead of fabricating a description.

Step 3: Write the description

Audience: the reviewer, plus PMs/tech leads skimming for impact. They want, in order: what changed, whether it's safe to merge, what to look at closely, how it affects rollout/usage.

Ordering rule: everything is sorted by what a reviewer needs first, not by file order or chronology.

Two sections, two different jobs — this is what prevents duplication:

• TL;DR is the outcome, as short as a changelog line. What changed, for whom, under what condition. No mechanism, no resolution order, no edge cases. If you can't say it in one or two sentences, you're including mechanism — move that part to Key Facts.
• Key Facts has exactly one inclusion test: would a reviewer be surprised by this, or fail to infer it from the TL;DR alone? Breaking changes, non-obvious fallback/resolution logic, edge cases, hidden dependencies, review hotspots, rollout gotchas — all qualify because none of them are guessable from the one-line outcome. If a candidate bullet is just the TL;DR restated with more words, it fails the test and gets cut, not kept.

Applying the test to a fact is binary, not a matter of how much detail to include: either the TL;DR already implies it (leave it out of Key Facts) or it doesn't (state it fully, once, in Key Facts — don't pre-summarize it in the TL;DR too).

Output structure

## TL;DR

- 1-3 bullets. Outcome only. Reads like a changelog entry, not a design doc.

## Key Facts
*(omit entirely if nothing passes the surprise test — don't pad this section)*

- Only things a reviewer would NOT infer from the TL;DR: breaking
  changes, migrations, feature flags, non-obvious fallback/resolution
  logic, security/perf implications, compatibility, rollout notes,
  review hotspots
- Each bullet is a fact, not a hedge — if you're not sure something is
  true, say what you're unsure of rather than omitting the uncertainty

## How to use
*(omit if not applicable)*

Short, practical. Config, flags, new API/CLI usage, migration steps —
whatever a reader needs to actually exercise the change.

## Caveats
*(omit if not applicable)*

Known limitations, deliberate trade-offs, follow-ups, non-obvious
behavior. Never invent one to fill the section.

Use this exact heading structure and order. Skip a section entirely — no heading, no "N/A" — when it has nothing real to say. A description with only a TL;DR is correct if that's all there is.

Formatting for GitHub / Bitbucket Cloud

Both render standard Markdown, so stick to the common subset and it'll look right on either:

• ## headings, - bullets, backticks for code/paths/flags, fenced code blocks with a language tag.
• Tables are fine for small before/after or endpoint comparisons — don't force one where bullets read better.
• Avoid GitHub-only syntax reviewers might read on Bitbucket: no <details> collapsibles, no @mentions unless intentional, no issue auto-linking syntax (#123) unless you've confirmed the target tracker uses it — write the ticket ID as plain text instead (JIRA-1234).
• No emoji, no badges, no horizontal rules as decoration.
• Keep line length reasonable; don't wrap manually inside bullets.

Voice

• State facts. Let the reader draw conclusions you haven't spelled out for them — don't over-explain.
• If something in the diff is unclear or looks unintentional (e.g., a stray file, a debug flag left on, a TODO that reads like it should block merge), say so directly as a question or flag rather than silently describing it as intended. This is more useful to a reviewer than confident silence.
• If you're not confident about why a change was made, say what changed and note the reasoning isn't clear from the diff — don't invent a motivation.
• Prefer plain declarative sentences over adjectives. "Adds retry with 3 attempts, 2s backoff" beats "adds robust retry handling."
• One idea per bullet. If a bullet needs "and" twice, split it.

Never write

Filler openers: "This PR aims to...", "This PR introduces...", "The purpose of this PR is...", "This change improves..." — just say what changed.

Empty adjectives: robust, clean, simple, powerful, comprehensive, seamless, various, several, significant, enhanced, streamlined.

Also avoid: restating the diff line-by-line, marketing language, apologizing for the PR, hedging you don't need ("this should hopefully..."), a Caveats or How to use section with nothing in it.

Before returning, check

• Does the first bullet tell a reviewer the single most important thing?
• Does every Key Facts bullet pass the surprise test — genuinely not inferable from the TL;DR? Cut any that don't.
• Does every TL;DR bullet stay at outcome level, with zero algorithm/resolution-order detail?
• Would a PM understand the TL;DR without reading code?
• Would a senior engineer find Key Facts genuinely useful, not filler?
• Did you flag anything odd in the diff instead of staying silent on it?
• Is every empty/inapplicable section actually removed?

Output

Return only the finished Markdown PR description — no preamble, no code fence wrapper, no explanation of how you produced it, no "Let me know if you'd like changes."