|
| 1 | +--- |
| 2 | +description: > |
| 3 | + Write or improve a GitHub pull request description. Use when the user asks |
| 4 | + to "write a PR description", "improve the PR description", "update the PR |
| 5 | + body", or provides a PR URL and asks for a better description. |
| 6 | + Keywords: PR description, pull request summary, PR body, PR writeup. |
| 7 | +allowed-tools: [Read, Glob, Grep, Bash, ToolSearch] |
| 8 | +--- |
| 9 | + |
| 10 | +# Write PR Description |
| 11 | + |
| 12 | +Generate a structured PR description that explains **why** the change exists, |
| 13 | +not just what files were touched. |
| 14 | + |
| 15 | +## When to use |
| 16 | + |
| 17 | +- The user provides a PR URL and asks to write or improve its description. |
| 18 | +- The user asks to draft a PR description for the current branch. |
| 19 | +- An agent needs to open a PR and wants a high-quality description. |
| 20 | + |
| 21 | +## Workflow |
| 22 | + |
| 23 | +### Phase 1: Gather context |
| 24 | + |
| 25 | +Collect all the information needed to understand the change: |
| 26 | + |
| 27 | +1. **Read the PR metadata** — title, current description, author, branch name. |
| 28 | +2. **Read the full diff** — understand every file changed, every function added |
| 29 | + or removed, every signature change. Do not skip files. |
| 30 | +3. **Read surrounding code when needed** — if the diff modifies an interface or |
| 31 | + a struct, read the full file to understand how the change fits into the |
| 32 | + existing architecture. |
| 33 | +4. **Check for linked issues or docs** — the PR or commit messages may |
| 34 | + reference issues, design docs, or RFCs that explain motivation. |
| 35 | + |
| 36 | +### Phase 2: Analyze the change |
| 37 | + |
| 38 | +Before writing, answer these questions internally: |
| 39 | + |
| 40 | +- **What was the status quo before this PR?** What limitation, bug, or missing |
| 41 | + capability existed? |
| 42 | +- **Why is this change needed now?** What concrete problem does it solve? Who |
| 43 | + benefits? |
| 44 | +- **What are the key design decisions?** Why was this approach chosen over |
| 45 | + alternatives? |
| 46 | +- **What is the new API surface?** Any new public types, functions, or |
| 47 | + configuration options? |
| 48 | +- **What are the architectural changes?** How does the internal structure |
| 49 | + change? What moves where? What gets refactored? |
| 50 | +- **Are there behavioral changes?** If not, say so explicitly — this reassures |
| 51 | + reviewers. |
| 52 | + |
| 53 | +### Phase 3: Write the description |
| 54 | + |
| 55 | +Use the structure defined in `.github/PULL_REQUEST_TEMPLATE.md` as the |
| 56 | +template. The tone should be direct and technical. Write for a reviewer who is |
| 57 | +familiar with the codebase but has not seen this change before. |
| 58 | + |
| 59 | +**Key principles:** |
| 60 | + |
| 61 | +- **Lead with why, not what.** The diff already shows the what. The description |
| 62 | + should explain the reasoning that is not visible in the code. |
| 63 | +- **Be specific.** Instead of "improves extensibility", say "allows internal |
| 64 | + tools to compose their own auth chain from individual credential strategies". |
| 65 | +- **Name things.** Reference actual types, functions, files, and config fields. |
| 66 | + Use backticks for code references. |
| 67 | +- **State non-changes explicitly.** If the PR is a refactor with no behavioral |
| 68 | + change, say "No behavioral changes. Existing users are unaffected." This is |
| 69 | + valuable information for reviewers. |
| 70 | +- **Keep the summary to one or two sentences.** It should be scannable. |
| 71 | +- **Use the motivation section to tell a story.** What was the problem? Why |
| 72 | + couldn't it be solved before? What does this PR unlock? |
| 73 | + |
| 74 | +### Phase 4: Update the PR |
| 75 | + |
| 76 | +Use the GitHub MCP tools or `gh` CLI to update the PR body with the new |
| 77 | +description. Confirm with the user before pushing if unsure. |
0 commit comments