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.

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

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.

write-pr-description