# Pr Description Writer

> Use when the user asks to write, draft, or improve a pull request description, PR summary, or PR body — turns the actual branch diff into a complete, reviewer-ready description. Triggers on "write a PR description", "describe this PR", "PR summary", "fill out the PR template".

- Skill: `naksalone/pr-description-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add naksalone/pr-description-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/naksalone/pr-description-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: NakSAlone (https://skillmd.com/u/naksalone)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/naksalone/pr-description-writer

---


# PR Description Writer

Write a pull request description a reviewer can act on in 30 seconds — grounded in the **real diff**, not a guess. A good PR description answers three questions before the reviewer has to ask: *What changed? Why? How do I know it's safe?*

## Preflight — gather the ground truth

Do not write anything until you have read the actual change. Run, in order, and stop degrading gracefully if a command is unavailable:

1. Determine the base branch. Try `git symbolic-ref refs/remotes/origin/HEAD` → strip to name; fall back to `main`, then `master`. If the user named a base, use it.
2. `git diff --stat <base>...HEAD` — the shape of the change (files, insertions/deletions).
3. `git log <base>..HEAD --format='%s%n%b'` — the commit narrative (intent lives here).
4. `git diff <base>...HEAD` — the actual change. For large diffs (>~600 lines), read the full stat, then read the diff of the highest-signal files (source over lockfiles/generated) and sample the rest.
5. If `gh` is available: check for a repo PR template (`.github/pull_request_template.md` or `.github/PULL_REQUEST_TEMPLATE/`). **If one exists, fill it out — do not invent your own structure.**

## Procedure

1. **Classify the PR** into one primary type: feature / fix / refactor / perf / docs / chore / revert. This sets the emphasis (a fix leads with the bug; a refactor leads with "no behavior change").
2. **Find the "why."** Look in commit bodies, linked issue numbers (`#123`, `JIRA-456`), and code comments touched by the diff. If the why is genuinely unrecoverable from the material, write a `> TODO(author): why?` line rather than fabricating a rationale.
3. **Summarize what changed** as an ordered list keyed to *reviewer impact*, not file order. Group by subsystem. Call out anything a reviewer would otherwise miss: new dependencies, config/env changes, migrations, feature flags, public API/signature changes.
4. **Surface risk explicitly.** Note backward-incompatible changes, data migrations (reversible?), performance-sensitive paths, and security-relevant edits (auth, input handling, secrets).
5. **State how it was verified.** Read the diff for added/changed tests and name them. If none exist for non-trivial logic, add a `> No tests added — reviewer: is this intentional?` note. Never claim testing that isn't in the diff.
6. **Link issues** using the host's closing keywords (`Closes #123`) only when the diff plausibly resolves the issue.

## Edge cases
- **Squash-merge repos:** commit messages may be throwaway ("wip", "fix"). Lean on the diff, not the log.
- **Monorepo:** prefix the title with the affected package/scope (`web:`, `api:`).
- **Generated/vendored files** (lockfiles, `dist/`, `*.pb.go`, snapshots): acknowledge in one line ("regenerated lockfile"), don't itemize.
- **Revert PRs:** state what is being reverted and why, and whether a forward-fix is planned.
- **Huge PR:** if the diff spans unrelated concerns, say so and suggest splitting — a reviewer-honest description beats a tidy lie.
- **Secrets:** if the diff appears to add a credential/API key, **stop and warn the user prominently** instead of describing it.

## Quality bar
- Title: <70 chars, imperative mood, scoped. Bad: "Updates". Good: "api: retry failed webhook deliveries with backoff".
- A reviewer who never saw the code knows what to look at first.
- Zero invented facts. Every claim is traceable to the diff or commits.
- No filler ("This PR makes some changes"). No restating the diff line-by-line.
- Risk and testing sections are never silently omitted — if empty, say why.

## Output template
```markdown
## Summary
<1–3 sentences: what this does and why, in plain language>

## Changes
- <change grouped by subsystem, reviewer-impact order>
- <new deps / config / migrations / flags called out here>

## Why
<the motivating problem or goal; link the issue>

## Risk & compatibility
- <breaking changes, migrations, perf/security-sensitive paths — or "None: internal refactor, no behavior change">

## How this was verified
- <tests added/updated by name; manual steps; or an honest gap note>

## Related
Closes #<n>  ·  <links>
```
Output the description in a fenced block ready to paste. If a repo PR template exists, fill that instead and mention you did.