PR description

Write for a teammate who knows the product, hasn't followed the work, and is reading between other tasks. After one quick read they should know what changed and what to check. A dense description goes unread even when it's accurate.

Establish the behavior before drafting

Read the diff and its affected callers. Compare the base and head behavior before choosing the summary. For a change spanning several types, roles, states or delivery channels, identify the relevant cases and establish each one's before and after. Separate stored data from what people see, and distinguish surfaces such as an in-app pop-up and a desktop notification.

Include unchanged cases when readers could reasonably assume they changed. For a rule that selects cases, check its exceptions and its default for unrecognized cases. Group cases only when their baseline, outcome and conditions match; name the members when a broad label would hide the scope.

This comparison is preparation, not a required published inventory or separate artifact. Investigate the affected behavior, not the whole system. Mark unknowns and distinguish source inspection from observed behavior. Don't invent motivation or claim verification you haven't done.

Picture first

Include a picture when it makes the change easier to assess than the text or diff alone. Put it above the first heading.

• Visible behavior or layout: use an actual-product before-and-after image from pr-screenshot-comparison. Capture with seeded or test data and crop out customer names and contact details. If a useful capture is unavailable, state that verification gap under Tests.
• A flow, contract or state change: use a Mermaid diagram when it clarifies the changed behavior. If both appearance and flow need explanation, put the screenshot first and the diagram second.
• A copy-only fix: the text diff can be enough. Capture the product when layout, wrapping, truncation or interaction also changes. Apply the same usefulness test to dependency bumps, renames and comment-only changes.