PR Description Writer

# PR Description Writer The description's job is to let a reviewer approve confidently in one pass. Write it from the diff, not from memory. ## Process 1. Read the actual diff first: `git diff main...HEAD --stat`, then the full diff. Also read the commit messages — they often contain "why" that belongs in the description. 2. Identify the one-sentence purpose. If you need "and" twice, the PR should probably be split — say so before polishing prose. 3. Fill the template below. Every claim about behavior must be something you verified, not something you intended. ## Template ```markdown ## What One short paragraph: the user-visible or system-visible change. Bullet the noteworthy implementation points (3-6 bullets max) — the decisions a reviewer can't infer from the diff alone. ## Why The problem or requirement, with a link (issue, incident, thread). If you chose between approaches, one line on the rejected alternative and why. ## How tested - [ ] Unit/integration tests added or updated: name the key cases. - [ ] Manual verification: exact steps you ran and what you observed. - [ ] Not tested: anything you knowingly didn't cover, and why. ## Risk & rollout - Blast radius: what breaks if this is wrong. - Migrations/flags/config: ordering requirements, default states. - Rollback: revert-safe, or does it need steps? Spell them out. ## Review guide - Start with <file> — it's the core change; the rest follows from it. - <file/dir> is mechanical (rename/generated/formatting), skim it. - Open question for reviewer, if any. ``` Delete sections that genuinely don't apply (a docs-only PR needs no rollout plan) — but "How tested" never gets deleted, even if its content is "rendered the page locally". ## Rules - **Screenshots/recordings for anything visual.** Before/after side by side for changes; one shot for new UI, including empty and error states if they changed. For CLI changes, paste terminal output in a code block. - **The "Not tested" line is mandatory honesty.** Reviewers calibrate their attention on it; an empty risk section reads as "didn't think about it", not "no risk". - **Call out the scary part yourself.** If there's a tricky concurrency change or a query rewrite, point the reviewer at it. Hiding it in mechanical noise is how bugs get approved. - **Size guidance for the reviewer beats apologies for size.** If the PR is large, the Review guide section ("90% is the codegen in /gen; the real change is 60 lines in router.ts") is what makes it reviewable. - Title follows the repo's commit convention (`feat(auth): magic-link expiry`), since it usually becomes the squash commit. - No fabricated checkboxes. An unchecked box with a reason is fine; a checked box that didn't happen is not. ## Final pass - [ ] A reviewer with no context could state the purpose after the first paragraph. - [ ] Every test claim corresponds to something that actually ran. - [ ] Visual change → image attached; behavior change → test named; risky change → risk named. - [ ] Links resolve (issue, design doc, incident).