Pull request descriptions, a template that works, and what a sealed review adds
A pull request description template you can paste into GitHub today, the trade-offs of AI-generated descriptions, and how a PatchArc review fills the same sections from evidence instead of memory.
updated 2026-08-22 · competitor pricing and claims checked 2026-08-22 · PatchArc facts as of 0.2.0
A pull request description is the handoff most teams actually use. Written well it saves the reviewer twenty minutes; written at the end of a long change it is mostly what the author remembers. This page gives you a template that works, explains the trade-offs of generating descriptions, and shows how PatchArc produces the same sections from recorded evidence.
The template
Save this as .github/pull_request_template.md (GitHub also reads pull_request_template.md at the root or in docs/). It pre-fills the body; it enforces nothing.
## Goal
One sentence: what this change is for and who asked for it.
## What changed
- Bullet per meaningful change, not per file.
- Call out anything that moved or was renamed.
## Scopes
Which packages or services this touches. Mention cross-cutting changes (CI, lockfiles) separately.
## Verification
What you ran and what it showed. Paste counts, not adjectives.
## Decisions
Each choice that could reasonably have gone another way, and why it went this way.
## Risks
What you noticed and did not fix, and what a reviewer should look at hardest.
## Rollout
Flags, migrations, order of deploys, how to roll back.Six of these seven sections are the six sections of a PatchArc review. That is not a coincidence; the review was designed to be the description a careful engineer writes.
Why descriptions go wrong
- Written last. The decisions were made on Tuesday; the description is written on Friday from memory.
- Written from the diff. The author opens the diff and narrates it, so the description repeats what the reviewer can already see and omits what they cannot: the reverted attempt, the constraint that forced the design.
- Unverifiable. "All tests pass" is a claim. Nothing on the PR proves it was true at the time.
AI-generated descriptions
Tools such as CodeRabbit, Qodo's PR-Agent (/describe), Graphite, Sourcery, and Copilot will write the description for you from the diff. They are good at "what changed" and poor at "why", because the why is not in the diff. Graphite's own guide on AI-generated descriptions says accuracy can vary and insists on human review. Use them for the summary section; do not let them write your decisions.
What PatchArc changes
PatchArc records the inputs to the description while the work happens, so the description is computed rather than recalled:
| Template section | Where PatchArc gets it |
|---|---|
| Goal | The argument to patcharc start |
| What changed | Commits and touched files recorded by the observer |
| Scopes | Ten workspace detectors, or explicit scopes in config.yaml |
| Verification | Test results (not parsed in 0.2.0; record them with patcharc note) |
| Decisions | Every patcharc decision you ran, with its timestamp |
| Risks | Every patcharc risk, with its timestamp |
| Rollout | Not captured; write it |
At patcharc stop the review is sealed into a capsule with every commit's patch. Paste the ArcLink into the PR, or attach the .parc. A reviewer can run patcharc verify and know the record has not been edited since it was sealed; the cloud runs the same check before publishing the link.
$ patcharc start --detach "Rate-limit the device endpoint"
$ patcharc decision "Fixed window in KV, not sliding; good enough at 30/min"
$ patcharc risk "Fails open when KV errors; acceptable for auth, revisit for uploads"
$ patcharc stop
$ unzip -p .patcharc/capsules/arc_*.parc evidence/summary/review.json | jq '{goal, decisions, risks}'Honest limits in 0.2.0
- The Verification section is empty until test parsing ships; write the numbers in a note.
- The ArcLink page is minimal; the full review is in the capsule.
- Redaction is not applied at seal; read patches before sharing publicly.
Frequently asked questions
What should a pull request description include?
Goal, what changed, which scopes it touched, what was verified, the decisions that could have gone another way, the risks left open, and the rollout plan. The template above covers all seven.
Is there a GitHub pull request template?
GitHub reads pull_request_template.md from the repository root, docs/, or .github/, and supports multiple templates under .github/PULL_REQUEST_TEMPLATE/ selected with ?template=.
Can AI write my PR description?
Yes for the summary; several review bots do it from the diff. The decisions and risks are not in the diff, so write those yourself or record them as you go with patcharc decision and patcharc risk.
How can a reviewer verify the claims in a description?
They mostly cannot. A PatchArc capsule is the exception: it is signed, carries the commits and patches, and patcharc verify fails if any byte changed. It verifies the record, not the truth of your prose; see Trust model.
Does PatchArc post the description to GitHub for me?
Not in 0.2.0. There is no GitHub integration yet; paste the ArcLink or attach the capsule.