PR Descriptions Reviewers Actually Read

PR descriptions reviewers actually read are short, specific, and slightly pessimistic. They answer: what changed, why now, how you proved it, what might explode, and how to undo it. AI will happily write a five-paragraph essay that restates the diff. Reviewers skip that essay. This is the template we keep, the prompt that fills it from git diff, and the checks that stop a generated novel from shipping a secret or a fake test plan.

Key Takeaways:

• Lead with risk and proof, not with "this PR implements."
• Generate from the staged diff and ticket, then delete anything a reviewer cannot verify in five minutes.
• Include a rollback command and a metric or log field to watch — aligned with structured logging.
• Scan the branch for secrets with Ocherfort before you request review.
• If the PR is a teaching moment, capture it in a coding journal or a Cadensend curriculum — not in a 1,200-word description.

Table of Contents:

• Why Reviewers Stop Reading
• The Description Template
• Drafting With AI Without Fiction
• Tests, Evals, and Streaming Behavior
• Security and Secrets in the Diff
• Reviewer and Author Workflows
• Hotfix, Docs, and Migration Variants
• Frequently Asked Questions

Why Reviewers Stop Reading

Code review time is the scarce resource. Google's engineering practices emphasize that reviewers should understand the change. They cannot if the description is a changelog of every file or a product pitch.

AI made a new failure mode: fluent emptiness. "Improves reliability and maintainability across the payments flow" is a sentence that survives any diff. It helps no one.

Reviewers actually read:

• The ticket link and the user-visible behavior
• The blast radius (services, schemas, flags)
• How to run the test that would fail on main
• What you already know is ugly

They do not read:

• A restatement of the stack you always use
• "Generated with our assistant"
• A tutorial on HTTP

If your team preps standups with AI, reuse the same honesty: empty proof means empty yesterday. If you estimate tickets with AI, the PR should say which estimate slice this diff closes. If you debug production with AI, the hotfix PR should carry the trace id, not a mystery.

HinterBuild backend and API engineering reviews bounce PRs that change JSON without an OpenAPI delta in the description. That single rule kills a class of "reviewer had to discover the break."

The Description Template

Copy this. Make the model fill it. You still own it.

## Why
Ticket: PAY-441
User-visible: EU checkout no longer hangs 12s then 502s when inventory times out.
Flag: `payments.retry_v2` (default off)

## What
- Map inventory deadline to 504 + `retry_after`
- Do not retry client-closed requests

## Proof
- `go test ./internal/payments -run Timeout` fails on main, passes here
- Shadow: trace `4bf92f…` attached (redacted)

## Risk
- Clients that treat all 5xx as retryable may loop
- Metrics: `http_status=504` on `POST /v2/checkout`

## Rollback
- Disable flag, or `argo rollback payments-api`

## Docs
- OpenAPI: 504 added; runbook: inventory deadline

Docs belong here because reviewers of APIs are client authors. Generate them from spec as in AI for developer documentation. Watch fields that exist in observability dashboards, not vanity names.

If the change is a learning spike, say so and link the one-week framework notes. Do not dress a spike as a production hardening.

Drafting With AI Without Fiction

Use a terminal AI CLI workflow:

git diff --staged | ai ask --prompt-file prompts/pr.md

prompts/pr.md:

Fill the PR template. Use only the diff and the ticket text provided.
Do not invent tests, flags, metrics, or services.
If proof is missing, write "Proof: TODO" and stop.
Max 180 words excluding the template headings.

Word cap matters. Models love headings. Reviewers love fewer headings with content.

Do not attach the entire monorepo. If the assistant has MCP filesystem access, root it at the service directory. See MCP explained with real code and MCP tools for daily development. Compare OpenClaw vs Claude Code if you want this loop in a product CLI; compare local vs cloud if the diff includes customer fixtures.

Generated commit messages can feed the PR, but squash messages are not a description. The description is for humans who will not read 40 commits.

When the diff is docs-only, say that in the first line. When the diff is a revert, paste the original PR link and the reason, not a new novel.

Tests, Evals, and Streaming Behavior

"Proof" is the section AI fakes most. It will claim tests that do not exist. CI must be the source of truth; the description names the command and the gap.

For LLM features, name the eval suite or the fixture, not "the model looks better." If you stream tokens, say what happens on client abort — streaming LLM responses in production. If you added a tool, say whether it is read-only. Tool calling failures are their own article; the PR still needs a one-liner.

Load tests are optional. Contract tests are not, if you changed a response. HinterBuild backend API engineering treats consumer tests as proof.

If proof is an incident replay, redact. Link the trace in observability. Do not paste payloads. That is the debugging playbook again.

Mention log fields using the real keys from structured logging. "Check the logs" is not proof.

Security and Secrets in the Diff

Reviewers should not be the first secret scanners. Authors should run Ocherfort on the branch: local-first repo security CLI, builtin plus optional scanners, gates including config, pipeline, and agentic, evidence under .ocherfort/runs/. Green is deterministic. Orange explains stored findings; it should not invent them. It is not a cloud dashboard.

Put the gate result in the PR if it is not already a required check:

Ocherfort: deployable=pass (run 2026-09-21T18:12Z)

If the PR adds an MCP server or a prompt file, the agentic gate is in scope. If it adds CI, pipeline is in scope. If it prints env "for debugging," fail the PR.

Never put live tokens in the description "as an example." That is worse than in the diff, because descriptions are copied to Slack, email, and mobile notifications.

Prompt injection in test fixtures is a real issue if the reviewer or a bot will send the diff to a model. Keep untrusted content marked. See prompt injection defense.

Reviewer and Author Workflows

Authors: fill Why/Proof/Risk before the visual review. If you cannot, the PR is not ready. Use standup to say "PR up, waiting on risk review," not "PR up."

Reviewers: read the description first. If Proof is TODO, comment once and stop. Do not review 800 lines of a change that cannot state how it was tested.

Bots: a summary bot that restates the diff is noise. A bot that fails on missing Rollback for migrations is useful.

Teaching: a great risk section is a lesson. Copy it into the AI coding journal. If many PRs teach the same framework footgun, promote a Cadensend series — self-hosted, cited, no hosted signup — and learn-in-a-week labs. Do not turn every PR into a newsletter.

Estimates: if the description reveals a missing slice (docs, flag, scan), split or re-range using ticket estimation.

For help making this the default on an API platform, contact HinterBuild. About is the team; observability is the "what to watch" backend.

Keep MCP write tools away from "auto-approve PR" fantasies. Read-only git + tests is enough. MCP daily is the scoped version.

Hotfix, Docs, and Migration Variants

Not every PR is a feature. The template still holds; the emphasis moves.

Hotfix. Why is the symptom and blast radius from the debugging playbook. Proof is the reproducing request or the trace after canary. Risk is the thing you are not fixing. Rollback is a flag or a previous SHA, named. Do not let AI write a root-cause novel. Point at observability and the real log field from structured logging.

Docs-only. Why is the spec change. Proof is the snippet test or the link checker. Risk is "clients that cached the old error shape." Link AI for developer documentation. If the docs PR is really onboarding, consider a Cadensend series instead of a 2,000-word README.

Migration. Why includes downtime class. Proof includes a dry-run command. Rollback is not "revert the PR" if the migration already ran. Say so in the first screen of the description. HinterBuild backend and API engineering treats this as a blocking review comment when missing.

Assistant / MCP config. Why is the policy change (read-only root, new server). Proof is a denied $HOME read. Risk is prompt injection via README. Scan with Ocherfort. See MCP explained and local vs cloud if the host changed.

Learning spike. Why is the question you will kill or keep. Proof is the sample app README from learn a framework in one week. Do not request production review standards on a spike, but still scan secrets.

Draft these variants from the CLI — terminal AI CLI — with the same word cap. Mention the closed estimate slice so ticket estimation can learn. Mention it in standup as a link, not as a speech.

If streaming behavior changed, Proof must name abort. Streaming LLM responses is the engineering deep dive; the PR only needs the observable contract. If you taught the team a repeating footgun, copy Risk into the coding journal after merge, not into a second essay in GitHub.

OpenClaw vs Claude Code does not change the template. It changes whether the draft left the building. Private diffs: local profile.

Frequently Asked Questions

Can AI write the whole PR description?

It can draft from the diff. You must verify tests, flags, and rollback. If you cannot verify a sentence, delete it. That is how PR descriptions reviewers actually read stay short.

How long should a PR description be?

Usually under 200 words plus links. Migrations and incident hotfixes can be longer on Risk and Rollback, not on autobiography.

Should I include screenshots?

For UI, yes, with PII cropped. For APIs, a spec diff and a curl are better. For incidents, a redacted trace link.

What if the PR is one line?

Still say why and how you proved it. One-line changes to timeouts have shipped outages.

How do I mention AI use without looking sloppy?

You do not need a badge. You need a test command. If policy requires disclosure, one line is enough: "Drafted from staged diff; tests and risk edited by me."

When do I scan for secrets?

Before requesting review, and in CI. Ocherfort on the path that changed, especially .github/, env samples, and MCP configs.

Conclusion

• Template: Why, What, Proof, Risk, Rollback, Docs.
• Generate from the diff; cap words; forbid invented tests.
• Scan secrets; watch real metrics; keep teaching out of the PR body.
• Reviewers should stop when Proof is missing — that is a feature.

PR descriptions reviewers actually read are an interface, like OpenAPI. For the APIs and monitors behind that interface, see backend engineering, observability, contact, and about.