Have the Agent Write the PR Body

An agent PR body is not “a PR was opened.” It is text that lets a reviewer see intent, scope, and verification on the first screen. Give the agent a fixed template, diff-summary rules, and a reviewer checklist, and you get fewer empty descriptions and file-dump PRs.

Adjacent posts stay on other axes. multi-agent-pr-workflow is branch ownership, parallelism, merge gates. linear-to-agent-pr is the Linear issue packet → delegation → when to request review. This post is body writing only. No pricing, plans, or affiliate links. Grounded in GitHub Creating a pull request and gh pr create.

What template?

One-line answer: Put a PR template (or agent markdown) in the repo and tell the agent to fill every section, then submit with --body-file / gh pr create. Title = one-line outcome; body = intent, verification, risk.

GitHub fills new PR bodies from .github/pull_request_template.md (or PULL_REQUEST_TEMPLATE/) on the default branch. The CLI can enforce the same shape with gh pr create --title "…" --body-file path.

Minimum sections for the agent:

Section	Agent fills	Forbidden
Summary	What/why in 2–4 bullets	Path dumps only
Motivation	One line: issue, bug, request	Full Slack threads
Changes	Groups by concern (API/UI/CI)	“Touched many files”
Test plan	Commands actually run + results	The word “tested” alone
Risk / rollback	Data, API, flags	Empty section
Out of scope	What this PR did not do	Silence
Reviewer notes	Hotspots, tradeoffs	“Please LGTM” only

Instruction snippet:

Write the PR body from this template. Fill every section.
Do not invent Test plan results — only commands you ran.
Do not paste secrets, tokens, or raw PII.
Title: <ticket-or-type>: <outcome in one line>
Then open PR with gh pr create --body-file <path> (or paste body).
Do not request reviewers until the human says so.

Example template (repo-wide in .github/pull_request_template.md, or copy to docs/pr-body-agent.md for agents):

## Summary
-

## Motivation / linked issue
-

## Changes (by concern)
-

## Test plan
- [ ] `<command>` → result:
- [ ] Manual:

## Risk & rollback
- Risk:
- Rollback:

## Out of scope
-

## Notes for reviewers
-

If the team uses Conventional Commits or ticket IDs, align the title (fix(auth): … / ENG-1234: …) and keep the body sections the same. Need Linear-specific slots? Use linear-to-agent-pr, but reuse this post’s Summary · Test · Risk rules.

How to summarize the diff?

One-line answer: Tell the agent to read git diff <base>...HEAD and summarize by concern—not line counts or file dumps—covering intent, boundaries, and contracts that can break.

Signals of a good diff summary:

Signal	Example
Intent first	“Raise login retry limit 3→5 to cut flaky auth”
Concern groups	API contract / UI copy / test fixtures
Contracts called out	New response field, default, error code
Non-changes stated	“No schema migration”
Evidence linked	Issue, failing CI, redacted screenshot

Bad summaries (ban these):

1. Only src/a.ts, src/b.ts, … file lists.
2. Unobservable “refactored / cleaned up.”
3. Features in Summary that are not in the diff (hallucination).
4. Claiming “all green” while tests failed.

Agent workflow sketch:

1. git fetch && git diff origin/main...HEAD --stat
2. git diff origin/main...HEAD  (or path allowlist only)
3. Group hunks by concern (not by file path alone)
4. Fill Summary + Changes from those groups
5. List contracts touched (API, flags, migrations)
6. Paste only commands you actually ran into Test plan

Pick one team standard: gh pr diff or local git diff. For large PRs, keep Changes at module/package granularity and put 1–3 hotspot paths in Notes. Parallel agents and path locks belong in multi-agent-pr-workflow—here only summary quality for one PR body.

Diff summary rules for the agent:
- Lead with why / outcome
- Group by concern (max ~5 bullets)
- Call out breaking or behavioral changes
- Never claim tests you did not run
- If unsure, write "Unknown — needs human" in Notes

What reviewer checklist?

One-line answer: Put a checklist the reviewer can use immediately in the body; the agent only does draft + self-check. Approve and merge stay with humans (or CODEOWNERS).

Example reviewer checklist (in Notes for reviewers or its own section):

Reviewer checklist (human):
[ ] Intent matches linked issue / AC
[ ] Scope matches allowlist — no surprise paths
[ ] Contracts (API/flags/migrations) called out above
[ ] Test plan commands are reproducible
[ ] Secrets / PII / debug dumps absent from diff
[ ] Rollback path is believable
[ ] Out of scope is honest (or follow-up linked)

Agent self-check (right before opening the PR):

Item	Pass criterion
Empty template slots	Summary · Test · Risk are not bare -
Test plan	Exact commands run appear in the body
Diff ↔ Summary	No large diff hunks missing from Summary
Secrets	No .env, keys, or token strings
Review request	No auto --reviewer before a human says so

Ops tips:

1. Keep the checklist to the team’s minimum. Extra boxes → agents fill the form, not the substance.
2. CODEOWNERS and required checks do not replace the body—they compress where to look.
3. Ban agent phrases that imply self-Approve. Draft quality ≠ approval authority.
4. If CI is red, add one line: why / safe to ignore? Silence is expensive.

Bottom line: Fix slots with a template, summarize intent and contracts from the diff, leave human review points in a checklist. Different axis from branch-parallelism and Linear-handoff posts.

FAQ

We already have a PR template—why agent instructions too?

Yes, both. The UI template supplies empty slots; agent instructions supply fill rules (diff summary, bans, --body-file). Quality stabilizes when both exist.

How do Summary and Changes differ?

Summary = why/outcome (2–4 bullets). Changes = where, grouped by concern. Do not put a file tree in Summary.

vs multi-agent-pr and linear-to-agent-pr?

multi-agent-pr-workflow = branches, paths, merge gates. linear-to-agent-pr = issue packet and when to request review. This post is PR body writing (template · diff summary · reviewer checklist) only.

May the agent auto-assign reviewers?

Even with default reviewers, wait until the body is filled and a human OKs. Empty body + auto review request is noise.

Sources

• Creating a pull request — create and describe PRs
• Creating a pull request template — .github/pull_request_template.md
• gh pr create — --title, --body, --body-file
• Adjacent: multi-agent-pr-workflow (branches/parallel), linear-to-agent-pr (issue handoff)