pr-description

PR Description

Write a PR as durable engineering context, not a narrated diff. The reader should understand the problem, the argument for the chosen mechanism, the contract it relies on, and the evidence without knowing this part of the codebase.

Use plain technical English. Name the actual object — a function, type, flag, file, or parameter — instead of an abstract noun that stands in for it; a noun ending in -ion, -ity, -ment, -ance, or -ence that could be replaced by the real identifier it refers to is a tell. Give each sentence one job: a sentence that states a cause, a qualification, and a scope boundary at once should become two sentences. Plain does not mean vague, casual, or stripped of necessary detail — qualify claims to their evidence and keep the one term the reader needs; just say it plainly.

Avoid: "This makes provider selection, the lifecycle instance type, and the dependency implicit." Write: "Callers must now choose the provider and lifecycle instance explicitly; nothing infers them."

Use assets/pr-description-template.md as the output skeleton. For source-grounded calibration facts while drafting, load references/pr-writing-calibration.md; use it to decide what to say, not how to phrase it, and do not reuse its vocabulary unless the repository's own conventions already use it. Load the deeper analysis in references/react-pr-findings.md and the criterion-by-criterion references/pr-description-rubric.md only to grade a draft before delivery or when the user asks for a review — their denser register is calibration for review, not a drafting voice to imitate.

Never do this

• Never start with a file list or a past-tense edit summary. It makes the reviewer reconstruct the motivation from the diff and leaves no durable explanation in git history.
• Never invent a test result, benchmark, issue, design decision, or baseline. If evidence is unavailable, say what remains unrun or unknown; a plausible number is worse than no number.
• Never state a performance claim without provenance. Name the metric, workload or fixture, hardware or environment, sample size when relevant, and the command, report, or CI run that produced it.
• Never make a conditional bet sound settled. State the decision rule and what observation would falsify the bet before reporting its result.
• Never present a scaffold, experiment, or theoretical performance claim as production-complete. State its status, remaining evidence gap, and the containment mechanism that exists today.
• Never make safety, compatibility, or fallback behavior discoverable only in review comments. If the change touches global state, platform behavior, hydration, serialization, or interoperability, state what changes, what remains invalid or untouched, and what happens in restricted or failure environments.
• Never use a heading with only a restated diff bullet beneath it. The diff already records filenames and edits.
• Never paraphrase a signature, call pattern, or exact wording in prose when the literal form is available and the reader needs to see it. A quoted span is evidence; a sentence describing it is not a substitute.
• Never turn a small fix into an essay. A sentence or short paragraph is sufficient when the behavior, reason, bound, and evidence fit there.
• Never omit an important scope boundary. Say which similar-looking behavior is deliberately unchanged and where a necessary follow-up belongs.
• Never override the repository's PR template, contribution rules, or title convention. Their required fields and placement win; use this skill's prose inside that structure.
• Never use merge-commit subjects, messages, or inherited target-branch history as PR narrative evidence. A git pull origin <target> merge may appear in branch history, but the PR title and body must describe only branch-authored non-merge history and the net changes in the three-dot diff.