write-pr-description

---
name: "write-pr-description"
description: "Generate a structured PR description that explains why the change exists, not just what files were touched."
license: "Apache-2.0"
---

# Write PR Description

Generate a structured PR description that explains **why** the change exists,
not just what files were touched.

## When to use

- The user provides a PR URL and asks to write or improve its description.
- The user asks to draft a PR description for the current branch.
- An agent needs to open a PR and wants a high-quality description.

## Workflow

### Phase 1: Gather context

Collect all the information needed to understand the change:

1. **Read the PR metadata** — title, current description, author, branch name.
2. **Read the full diff** — understand every file changed, every function added
   or removed, every signature change. Do not skip files.
3. **Read surrounding code when needed** — if the diff modifies an interface or
   a struct, read the full file to understand how the change fits into the
   existing architecture.
4. **Check for linked issues or docs** — the PR or commit messages may
   reference issues, design docs, or RFCs that explain motivation.

### Phase 2: Analyze the change

Before writing, answer these questions internally:

- **What was the status quo before this PR?** What limitation, bug, or missing
  capability existed?
- **Why is this change needed now?** What concrete problem does it solve? Who
  benefits?
- **What are the key design decisions?** Why was this approach chosen over
  alternatives?
- **What is the new API surface?** Any new public types, functions, or
  configuration options?
- **What are the architectural changes?** How does the internal structure
  change? What moves where? What gets refactored?
- **Are there behavioral changes?** If not, say so explicitly — this reassures
  reviewers.

### Phase 3: Write the description

Use the structure defined in `.github/PULL_REQUEST_TEMPLATE.md` as the
template. The tone should be direct and technical. Write for a reviewer who is
familiar with the codebase but has not seen this change before.

**Key principles:**

- **Lead with why, not what.** The diff already shows the what. The description
  should explain the reasoning that is not visible in the code.
- **Be specific.** Instead of "improves extensibility", say "allows internal
  tools to compose their own auth chain from individual credential strategies".
- **Name things.** Reference actual types, functions, files, and config fields.
  Use backticks for code references.
- **State non-changes explicitly.** If the PR is a refactor with no behavioral
  change, say "No behavioral changes. Existing users are unaffected." This is
  valuable information for reviewers.
- **Keep the summary to one or two sentences.** It should be scannable.
- **Use the motivation section to tell a story.** What was the problem? Why
  couldn't it be solved before? What does this PR unlock?

### Phase 4: Update the PR

Use the GitHub MCP tools or `gh` CLI to update the PR body with the new
description. Confirm with the user before pushing if unsure.