pr-description

PR Description Generator

Help the user turn the work on their current branch into a clean PR subject and a concise description they can paste into GitHub. The job is to read the branch's commits and code changes, understand the intent behind them, and express that clearly for a reviewer.

This skill is read-only with respect to git and GitHub: it inspects history and prints a result. It does not commit, push, or create/update any PR.

Workflow

1. Confirm you're in a usable repo

Check that the working directory is a git repository and the current branch has commits. If git rev-parse --is-inside-work-tree fails, tell the user this isn't a git repo and stop. Note the current branch name with git rev-parse --abbrev-ref HEAD.

2. Work out what to compare against, then confirm with the user

The description should cover only the commits unique to this branch, so you need the base branch it will merge into. Detect a sensible default rather than asking cold:

• Try the remote's default branch: git symbolic-ref refs/remotes/origin/HEAD (gives something like origin/main).
• If that isn't set, fall back to whichever of origin/main or origin/master exists (git rev-parse --verify). If neither exists, fall back to local main/master.
• Compute the merge base so you compare from where the branch diverged: git merge-base <base> HEAD.

Then count the commits with git rev-list --count <merge-base>..HEAD and tell the user what you're about to do, and ask them to confirm before generating. For example:

I'll compare feature/login-rework against origin/main (5 commits since they diverged). Sound right, or do you want a different base branch?

This confirmation matters because guessing the wrong base produces a description that's either missing changes or padded with unrelated ones — and the user knows their branching model better than any heuristic does. If they give a different base, recompute the merge base from it. Only proceed once they're happy.

3. Gather the material

With the confirmed base (use the merge base as <from>), collect both signals:

• Commit messages — the author's own narration of intent: git log <from>..HEAD --pretty=format:'%h %s%n%b'
• A map of what changed — git diff <from>...HEAD --stat
• The actual diff — git diff <from>...HEAD

Use commits and diff together. Commit messages tell you why; the diff tells you what actually changed and catches things the messages glossed over or omitted. If the diff is very large, lean on --stat plus reading the most significant hunks rather than dumping everything — you need enough to summarize accurately, not every line.

4. Write the subject and description

Subject — a single plain imperative line, like a good commit summary: "Add JWT-based login flow", "Fix race condition in cache eviction". No type prefixes (no feat: / fix:), no trailing period, roughly 50–70 characters. It should tell a reviewer the gist at a glance.

Description — keep it concise and narrative:

• One short paragraph (2–4 sentences) explaining what the change accomplishes and why, at a level a reviewer skims before diving into the diff.
• A short bulleted list of the key changes — the things worth a reviewer's attention. Group related edits into one bullet rather than mirroring the commit list one-for-one. Skip noise (formatting-only churn, generated files) unless it matters.

Aim for signal over completeness. A reviewer should finish the description knowing what to look for, not re-reading the whole diff in prose.

5. Output

Print the result in a copy-friendly block so the user can lift it straight into GitHub:

Subject:
<the subject line>

Description:
<summary paragraph>

- <key change>
- <key change>
- <key change>

Then it's the user's to paste wherever they like.

Example

For a branch that adds rate limiting to an API:

Subject:
Add per-client rate limiting to the public API

Description:
Introduces a sliding-window rate limiter on all /api/v1 endpoints to protect
against abuse from individual clients. Limits are configurable per route and
return a 429 with a Retry-After header when exceeded.

- Add RateLimiter middleware backed by Redis sliding-window counters
- Wire configurable per-route limits into the API gateway config
- Return 429 + Retry-After on limit breach, with tests covering the boundary