Write a pull request description from the git diff
A useful PR body is a map for the reviewer, not a polished retelling of commit messages. Choose the correct diff, ground the file list in Git, explain the purpose and review path, and state testing exactly as it happened.
Use git diff --cached for staged work or git diff BASE...HEAD for the branch change GitHub will review. Read --name-status for the exact file list. Write the purpose, approach, and observable result only when the diff supports them. Name the files or areas that deserve attention. List tests that actually ran, separate checks still needed, and say when screenshots do not apply. Finish by reviewing the diff for accidental files, secrets, dependency changes, permissions, workflows, and other risk-bearing surfaces.
Description path
1. Choose the diff the reviewer will actually see
Start by naming the base and head. GitHub defines the base branch as the destination and the head branch as the proposed change. Its pull-request Files changed view uses a three-dot comparison: the merge base of both branches compared with the current head.
# Exact staged change
git diff --cached
git diff --cached --name-status
# Branch pull request change
git diff BASE...HEAD
git diff --name-status BASE...HEADDo not substitute a two-dot branch comparison without understanding the difference. A three-dot diff focuses on what the topic branch introduces since the branches diverged. If the repository uses a base other than main, use the real branch name.
2. Separate author intent from diff evidence
Recent commit messages can explain why the work started, but they can also include abandoned directions, merges, and unrelated history. Use them as context. Use the selected diff as evidence for what the pull request contains.
| Statement | Required evidence | Safer fallback |
|---|---|---|
| Why | Issue, ticket, user problem, incident, or author-provided context. | Ask for the missing purpose instead of inferring business impact. |
| What | Changed behavior and files visible in the selected diff. | Describe the mechanical change without inventing an outcome. |
| Result | Test output, screenshot, benchmark, or reproduced behavior. | Label it as expected behavior or verification still needed. |
| Risk | Dependencies, data, auth, permissions, workflows, APIs, or migration changes. | Point reviewers to the affected surface without claiming it is safe. |
GitHub recommends context that explains the problem, approach, and result, plus guidance about where reviewers should pay attention. If the diff cannot supply the problem or result, leave a clear placeholder for the author.
3. Turn the file list into a review map
Preserve Git's status and paths
Build the changed-file inventory from --name-status. Keep additions, modifications, deletions, and rename pairs exactly as Git reports them.
Group by reviewer concern
Summarize related files under behavior, tests, documentation, configuration, dependencies, data, or release work. Do not list every generated line as a separate accomplishment.
Name the review order
When the change spans layers, identify the file or concept to read first. GitHub notes that review-order guidance is useful when a PR touches many files.
Example change map
M src/session.ts- rejects expired sessions before the account lookup.M tests/session.test.ts- adds an expired-session case and preserves the valid-session case.M docs/auth.md- documents the expiry response and recovery path.
4. Write an honest test plan
Separate completed evidence from work still needed. An unchecked template item is not proof, and a suggested command is not a test result.
| Status | Good wording | Avoid |
|---|---|---|
| Ran | npm test -- session - 12 tests passed locally on Node 20. | Tests pass. |
| Not run | Not run; CI will execute the full suite after the branch is pushed. | Should be fine. |
| Manual | Created an expired test session and confirmed the sign-in screen appears with no account data. | Manually tested. |
| Needed | Reviewer: confirm the session-expiry copy in Safari before merge. | Verify edge cases. |
If no test evidence exists, say so. That gives the reviewer a real decision instead of a false sense of completion.
5. Tell the reviewer where risk lives
Review your own pull request before requesting review. GitHub specifically recommends checking for accidental changes and confirming relevant builds or tests. Pay extra attention when the diff changes dependencies, authentication, permissions, workflows, or sensitive-data handling.
- Call out the first file or behavior to review.
- Link the issue or decision record that supplies the missing why.
- State whether the PR is ready, draft, blocked, or waiting on a named check.
- Include screenshots for UI changes; otherwise say why they do not apply.
- Inspect the diff for secrets, local paths, generated files, debug output, and unrelated formatting churn.
- Keep the PR focused; split independent purposes when review becomes ambiguous.
Repository templates can prompt authors for purpose, linked issues, testing notes, and checklists. A generated description should fill those expectations from evidence, not merely reproduce the headings.
6. Treat an empty diff as evidence, not a writing prompt
If the selected diff is empty, do not use nearby commits to fabricate a change list. State that no staged changes or branch differences were found. Then check whether the user intended a different base, head, or staging mode.
## Summary
- No code changes were detected in the selected diff.
## Changes
- No files changed in the selected diff.A structurally valid empty template is more useful than a confident description of work the reviewer will not see.
Generate the structure without guessing the files
PR Template GeneratorA focused SKILL.md workflow that reads a staged or three-dot branch diff, recent commits, and Git's exact name-status list, then returns Summary, Changes, Test Plan, Screenshots, and Checklist sections. It remains useful on an empty diff and does not create the pull request.See the PR description skill →Common questions
What should a pull request description include?
Include the purpose, a grounded summary of what changed, the exact changed-file scope, tests actually run or still needed, screenshots or an explicit not-applicable note, risks or review focus, and links to relevant issues.
Which git diff should I use for a pull request description?
Use git diff --cached for the exact staged change. For a branch pull request, use a three-dot comparison such as git diff BASE...HEAD because GitHub's Files changed view compares the merge base with the head branch.
Should recent commit messages control the PR summary?
No. They can explain intent, but the selected diff is the evidence for what the pull request contains. Omit or label commit context that the diff does not support.
What should I write when tests were not run?
Say that tests were not run and list the checks still needed. Do not turn a suggested command or unchecked box into a claim that verification passed.
What if the selected git diff is empty?
Do not invent a summary or changed files. State that the selected staged or branch diff is empty, keep the template structurally valid, and check whether the wrong base, head, or staging mode was selected.