| name | write-pr-description |
| description | Write or improve a GitHub pull request description. Use when the user asks to "write a PR description", "improve the PR description", "update the PR body", or provides a PR URL and asks for a better description. Keywords: PR description, pull request summary, PR body, PR writeup.
|
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:
- Read the PR metadata — title, current description, author, branch name.
- Read the full diff — understand every file changed, every function added
or removed, every signature change. Do not skip files.
- 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.
- 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.
