PR Description Writer
Write the description a reviewer wishes they had. Every claim must trace to the diff.
Procedure
- Determine the base branch. Use the one the user names. Otherwise try
git merge-base HEAD mainthenmaster. State which base you used. - Collect the change set:
git diff <base>...HEAD --statfor the file summary.git diff <base>...HEADfor the substance.git log <base>..HEAD --pretty=format:'%h %s'for the commit list.
- Identify the purpose. Read the diff, not just the commit subjects. If the purpose is not evident, write what the change does and mark the intent as "unclear" rather than inventing a motivation.
- Find the test evidence. Look for changed or added test files, and for commands in CI config, Makefile, package.json scripts, or the README. Report only tests that exist in the repo.
- Note risk. Flag changes to public interfaces, config keys, database schema, authentication, or anything without test coverage.
Output template
Use this structure. Drop a section only when it would be empty; never leave placeholder text.
## Summary
One or two sentences: what this changes and why.
## Changes
- `path/to/file`: what changed and why
- `path/to/other`: what changed and why
## How to test
1. Step a reviewer can run
2. Expected result
## Risk and rollback
- Risk: what could break, or "Low, isolated to <area>"
- Rollback: how to revert safely
## Notes for reviewers
Anything that needs context: a tricky trade-off, a follow-up, a part that is intentionally out of scope.
Rules
- Group the change list by intent (feature, refactor, tests, docs), not by file order, when the diff is larger than about ten files.
- Never write "This PR does X" without a line in the diff that shows X.
- Keep the summary under four lines. Reviewers read it first and often only it.
- Do not invent test steps. If there are no tests, write "No automated tests; manual check: ".
- Do not add an AI-authorship footer unless the user asks.
Supporting file
references/pr-template.md holds a longer annotated template for large or multi-part changes. Read it when the diff touches more than about fifteen files.