PR Descriptions

Writing PTE PR descriptions

Process

• Before gh pr create, run the static checks CI runs, from the worktree being pushed: pnpm check:format, pnpm check:lint, pnpm check:types, pnpm check:knip (repo root), plus the affected package's test:unit. These are cheap; run them all, every time. A green test run is not a green PR: lint enforces the house assertion style (see the writing-tests skill), and test:unit and check:types typecheck test files where stale API shapes surface.
• Browser tests: complement AGENTS.md's per-package baseline. A contained change may run just its own file (vitest run --project "browser (chromium)" tests/<file>.test.tsx); a change with general blast radius (engine, selection, input pipeline) runs the package's full test:browser:chromium.
• Always open as draft (gh pr create --draft); a maintainer marks it ready and merges. Never gh pr merge.
• Title = the main commit subject (conventional format).
• Use --body-file, never a heredoc with backticks inside $( ): backticks in the body survive intact.
• The repo has no PULL_REQUEST_TEMPLATE.md, so the body is prose, not a form to fill in.
• The description stands on its own: no internal context, ever. No issue-tracker ticket IDs, no customer or partner names, no support threads, no Slack discussions, no "a user reported" or "requested by". Describe the observable failure or need itself ("the floating comment button intermittently fails to appear on the first selection"), never who reported or requested it. Related work is referenced by PR number or by naming the mechanism ("tracked separately as a follow-up"); the linked issue links to the PR, never the reverse. Ticket and support context lives wherever the work is tracked and in support channels, not in the PR.

Shape

• User-facing PRs open with the changeset's prose, verbatim. The changeset is the calibrated consumer sentence (see the changesets skill), and it is what the reviewer actually reads; a body that buries it under paragraphs gets skipped whole. After it, the body adds only what changesets ban: a concrete example of the failure, one sentence naming the fix mechanism, any behavioral change or honest caveat. When the changeset alone carries the change, it is the whole body. This mirrors the changeset's prose; body sentences about the changeset ("a changeset rides along") remain banned.
• Fix/refactor PRs: heading-free narrative prose. After the changeset opening: diagnosis in code terms → fix → what was verified, compressed into the paragraph the budget below allows. Larger feature PRs may use ## What / ## Design notes.
• Lead with motivation (internal-only PRs, which have no changeset to open with): the pain that makes the change necessary, before the mechanism. The description stands on its own; explain the problem in terms of the code, not the PR graph, and reference another PR only when the reader cannot follow the description without it.
• Prose over bullets. Each design decision gets a paragraph carrying its own reasoning; bullets flatten the why out. A short bullet list is acceptable only for genuinely parallel items (e.g. "things I was careful about").
• No ## Tests section. A test inventory is listy and disconnected from the reasoning. Tests appear in the narrative next to the decision or claim they pin, "pinned" meaning a test that fails without the change ("pinned by a test expressing...").
• Justify each non-obvious decision inline, paired with the test that pins it.
• Fenced code examples when introducing API.
• Stacked or extracted PRs state why they are separate and what depends on them, referencing the other PR only when the reader needs it (#2777: "Extracted from #2772 because it changes behavior for all existing editor.on events ... #2772 stacks on this").
• No generated-by footers, no emoji banners.

Honesty

• Volunteer behavioral changes: one nobody would catch in review gets its own sentence, even a narrow one.
• Say what is not covered: an untested path, a case deliberately left out of scope.
• Perf numbers carry before/after and methodology (environment, run count, what was measured), never a bare percentage.
• No boilerplate self-assessment. "Type-only change", "no changeset needed" restate the diff; state something non-obvious about blast radius instead, or say nothing.

Length: the budget

• The body scales with the diff's blast radius, not the investigation's length. Default for a fix PR: the changeset's prose plus at most one short paragraph (~100 words): the concrete example, the mechanism, one honest caveat. The 3-4 paragraph, ~200-word shape (failure, design, blast radius with its pin, caveat) is earned only by PRs with a genuinely large blast radius; it is not the template.
• A trivial diff earns two sentences: a verdict, and a rider naming anything else the diff also does. Zero citations, zero mechanics.
• Everything cut must already live somewhere: mechanism in the commit bodies, diagnosis narrative and decisions on the linked issue, specifics in the tests. The body is a map, not the territory.
• When scope grows mid-PR, rewrite the body top to bottom: never append, and never patch just the sentences you remember; re-read the whole body and rewrite. Appended addenda are how walls form, and patching only the remembered sentences is appending's twin: both skip the whole-document read. After any commit lands on, leaves, or is reworded on a branch with an open PR, re-read the entire body against the tip before pushing; stale claims survive wherever you patch from memory.
• One-screen test: after one screen the reviewer knows what changed, why, and what to scrutinize. If not, cut until they do.