PR Body

Lead with the problem or the capability, then the result and why this approach.

For a larger PR, end the Summary with a plain-language In short: line of two or three sentences for readers outside the module. It doubles as a check: if it makes no sense, the change probably doesn’t either.

For a stacked PR add a line such as Stacked on #480; only the last two commits belong to this PR.

Evidence by change type

A description conveys belief, not proof. Show the change working instead of saying it works. Put the matching proof in Verification (or a dedicated ## Evidence section for larger PRs).

• “Before” is what is live (base branch, production, last deploy), never a faked revert.
• Check every capture. Agents can confidently screenshot or measure the wrong thing.
• Use demo or sanitized data only.
• State what was not run, for example Not checked in a browser yet.
• Security fixes are the exception: keep the description short and delay exploit details until release.

Change map

Use when the diff touches several modules or moves responsibility between them. Rows are modules or boundaries, not files.

A short responsibility tree helps when the layout itself is the change:

Architecture and behavior

Use a diagram when it explains the change faster than prose. Keep node names tied to real modules or symbols and label arrows with calls, events, or data.

• Module flow (flowchart LR) for a cross-module feature or boundary move.
• Sequence diagram for changed ordering, async work, retries, cancellation, or cleanup. Match each alt branch to a code branch.
• State diagram for changed transitions or terminal states.

For a fix that changes flow or state, show a Before and After pair at the same abstraction level, then name the exact edge or step that changed so the reader does not have to diff the diagrams.

When a diagram would be expected but does not apply, say so: Not applicable: only renames a constant, no runtime flow changes.

Boundaries and risks

Use when the change has real failure modes, invariants, migrations, or external effects. Include only rows that matter.

Risk groups to scan: input validation and auth; failure mapping, retries, duplicates, concurrency, ordering, cleanup; schema changes, backfills, rollback; secrets in logs or error payloads; UI loading, error, empty, stale, and repeated-action states.

Write Not verified instead of turning a risk question into a claim.

Visual changes

Only for user-visible UI changes. Image row first, label row second. See visual-evidence for capture and attachment.

Use Absent for a new state and Removed for a deleted one.

Rollout and follow-up

Optional. Migrations, feature flags, staged rollout, monitoring, known gaps, required follow-up PRs. State whether each gap blocks merge.