write-descriptionlisted

# Writing PR Descriptions ## The one rule A PR description carries **only what the diff cannot show**: the *why*, the *shape* of the change, and *what to look at first*. The reviewer reads the code for the *how*. Every sentence that restates the implementation is noise; cut it. Write for a reviewer scanning in fifteen seconds. Short is the target, not a constraint. Size to the number of distinct ideas, not the file count: a 50-file rename is one idea and earns a tiny description. ## Pre-flight (before writing a word) Read the change: `git diff <base>...HEAD` and `git log <base>..HEAD`. Every path, name, and count in the description must match what you just read. That is what keeps it from going stale. ## The shape Lead with a **visual when the change has one**, then the four sections. Most are one line. ### Visual first (when it applies) - The change is a **mapping, rename, enumeration, or set of values** -> show a **table**. - The change is a **flow, topology, lifecycle, or state machine of 3+ parts** -> show a **diagram** (`mermaid`; an inline `A -> B -> C` for a plain 3-box chain). - Neither -> skip this; no decorative diagram. Draw the data once, here. The sections below must not re-narrate what the visual already shows. ### 1. TL;DR One sentence: `<what changed at the system level> so that <why it matters>`. The why is required. The PR title is the conventional-commit summary; the TL;DR is the sentence version, not a copy of it. ### 2. Goal One line, firs