PR Commit Message

PR Commit Message Skill

Write a historical record, not a diff summary. A future maintainer should be able to recover what changed, why it mattered, what failed or constrained the design, why this approach was chosen, and where the supporting evidence lives without reopening the PR.

Optimize for durable understanding, not assistant-response brevity. Remove repetition and development chronology, but preserve every independently useful root cause, design decision, compatibility rule, limitation, and proof point.

Non-negotiable evidence contract

PR prose and early commit bodies often preserve useful history, but they can also preserve stale constraints, mistaken link interpretations, and superseded absolutes. Prevent those high-cost failures before drafting:

• Count the private ledger's material topics. With two or more topics, the final draft must have the same number of named topic sections; do not count the overview, and do not let a continuous narrative or overview stand in for those sections.
• For each candidate reference, privately record the target's actual entity type, title, and exact relationship after opening it. Omit the reference when that relationship is not supported, even when the PR description labels or explains it.
• For each candidate universal, bound, count, or inequality, privately record the complete search universe and check it for counterexamples. Proof over a subset cannot support a claim about the whole API, repository, platform set, or generated surface. One outlier means the quantified wording must be narrowed or removed. When that universe is a family of similar artifacts such as workflows, projects, targets, or packages, list its members and the dimension being generalized, then read that dimension on each member. Families that look uniform usually are not, and reading two of five is how a false universal ships.
• Inspect human discussion on the current PR and every related or superseded PR whose work or feedback is carried forward. Adopted feedback needs source-backed attribution or a required Missing context: line when the contributor's email cannot be verified.
• Establish the old side of every change from the PR base, not from an earlier commit in the same PR. Before using move, replace, remove, extract, migrate, or centralize, verify that the departing component or behavior existed at the base. When both the source and destination were introduced on the branch, describe the final net addition instead; the intra-PR refactor is development chronology unless it explains a lasting constraint.

Workflow

1. Gather first-party evidence

Inspect at least:

1. the current PR title, body, URL, closing issues, commits, reviews, inline comments, complete changed-path list, and every substantive current-head diff hunk
2. linked issues, related or superseded PRs, required companion PRs, compare links, failure logs, repro steps, validation runs, and relevant release or API documentation; for carried-forward PRs, inspect their issue comments, reviews, and inline comments too
3. commit bodies and adopted review feedback that explain non-obvious final code
4. recent target-repository merge messages for subject, reference, section, bullet, and wrapping conventions

Useful commands include:

gh pr view <number> --json number,title,body,url,commits,files,comments,reviews,closingIssuesReferences
gh api repos/<owner>/<repo>/pulls/<number>/comments --paginate
gh api repos/<owner>/<repo>/issues/<number>/comments --paginate

Use the final diff and current head as the strongest evidence for shipped behavior. Use the PR base or a specific referenced revision for the old side of a before/after claim. Treat PR prose, commit bodies, review comments, and code comments as leads that still need verification.

For dependency or submodule pointers, separate the parent PR's intent from the range the pointer happens to cross. A required companion change or intentionally adopted dependency behavior can be relevant. Unrelated intervening commits are not parent-PR topics merely because the new pointer includes them; preserve the range with a compare link instead of narrating it.

2. Build one private evidence ledger

Use these definitions before classifying the diff:

• Material topic: an independently searchable causal or design unit with both its own why boundary (motivation, failure, root cause, constraint, compatibility consequence, or decision) and at least one decisive anchor not derived from another topic.
• Explicit decision: a non-trivial correction, exception, safety rule, or design choice that shares a material topic's root cause and lacks independent search intent. It remains a named sub-point under that topic.
• Mechanical derivative: generated output, lock or compiled artifacts, repeated documentation, ordinary verification, or iterative fixups that only implement or repeat a parent topic.

Walk every changed path and substantive hunk once. Map each coherent change to exactly one material topic, explicit decision under a named topic, or mechanical derivative under a named topic. A hunk is substantive when it changes runtime, build, packaging, test, or workflow behavior; an API or design decision; an emitted artifact; or rationale needed to maintain one of those. Build, project, packaging, workflow, and configuration changes are candidate topics just like source code.

For each material topic, record:

• need or user-visible symptom
• root cause or triggering condition
• chosen correction or design
• important tradeoff, compatibility rule, limitation, or rejected alternative
• verification evidence
• decisive anchors and their exact sources: errors, symbols, predicates, fallback order, counterexamples, measurements, revisions, or review-found semantic corrections
• related issue, PR, run, compare view, or commit

Then perform one history-only pass over the parent PR's commits, reviews, linked context, validation notes, and specifically adopted upstream changes. Capture information the final tree cannot explain by itself: the original failure, a rejected obvious alternative, a regression that changed the design, a compatibility exception, a review-found correction, or a measurement that governs how evidence should be read. Do not walk an entire traversed dependency range. Verify useful historical facts before adding them to the ledger.

Apply these boundary rules:

• Sharing a subsystem, umbrella feature, or final goal does not merge topics with different why boundaries or corrections.
• Do not split a topic merely because its implementation crosses files, commits, workflow stages, generated outputs, or tests.
• Multiple manifestations of one root cause remain one topic only when they share the same correction and compatibility rules.
• A feature's public programming model is a topic when its API, lifetime, interoperability, or compatibility design itself meets the material-topic definition; when it does, the overview is not a substitute for its section.
• Tests or benchmarks become a topic when they correct misleading prior evidence, introduce a distinct validation architecture, or independently establish a performance or compatibility decision. Ordinary verification stays with its parent.
• Correctness or equivalence evidence and performance evidence are separate topics when each independently justifies safe adoption.
• Review-found correctness or safety changes remain explicit decisions, or become topics when they have independent search intent.
• A shared mechanism, guard, or contract that several topics route through is itself a topic when it carries a guarantee, invariant, or safety rule that none of its consumers own. It is easy to mistake for plumbing precisely because it appears everywhere; distributing it as a sentence inside each consumer leaves that guarantee without a home and hides why the consumers became uniform.
• A removal, replacement, or move belongs to the topic that performs it, but the departing component still needs its name, the behavior that left with it, and where that responsibility now lives. This message is the only thing a future search for the deleted name will find.

Use a counterfactual independence test before collapsing any candidate: if its correction were reverted while the proposed parent remained, would a distinct failure, constraint, or maintenance question return? If so, keep it as a material topic. A path is not a derivative merely because it supports the same feature; it must share the parent's why and correction. A shared goal or symptom category is not a shared root cause. Do not demote a candidate that passes the material-topic definition merely to shorten the message. If the returning problem shares the parent's why and lacks independent search intent, keep it as an explicit decision rather than promoting it.

After collapsing derivatives, choose the shape:

• Mechanical change: subject only or one short explanatory paragraph.
• One material topic: focused causal narrative; no forced section heading.
• Two or more material topics: overview followed by exactly one named section per topic. In SkiaSharp, use the established ~~ Topic ~~ syntax.

Every topic, explicit decision, and marked anchor gets one visible home. A section preserves its causal chain; naming a file or category is not coverage. Collapsing a derivative removes its separate heading, not useful evidence it contributes to the parent.

Use a counterfactual anchor test: retain the smallest observed fact that shows why the chosen design is necessary, why an obvious alternative is unsafe, or what made the evidence credible. Compress repetition, not the condition, counterexample, scope, or measurement that carries the proof.

3. Draft in the repository's voice

Prefer the repository's established subject form:

• [Area] Imperative summary (#PR)
• Area: imperative summary (#PR)
• Imperative summary (#PR) when no area prefix is established

Use an imperative verb, identify the real subsystem when useful, preserve the established area spelling, and avoid vague subjects such as Fix review comments or Misc changes.

Start the body with verified references. Use labels only for the relationship they express:

• Fixes: for an issue the PR closes
• Context: for related issues, PRs, runs, announcements, documentation, URLs, or exact commit SHAs
• Requires: for the immediate companion PR or dependency this change is built on and cannot merge without. In a stack, that is the parent you actually build on; an earlier ancestor in the same stack explains context but is not what this change requires, so it belongs under Context:
• Changes: for dependency compare views or upstream ranges
• another label only when recent repository history establishes both its spelling and use

Fetch every target. Do not convert a PR URL to an issue URL, call a related PR an issue, claim a PR is completed without evidence, or attach a correct URL to the wrong relationship.

Preserve the content expected for the kind of change:

• Bug fix: symptom, investigation evidence, root cause, and correction
• Dependency or submodule bump: repository and revision, compare link, and only the upstream changes relevant to this repository
• Release or platform update: capability gap or release trigger, compatibility impact, project response, and authoritative links
• Public API: programming model, ownership or lifetime rules, native dependency, and platform limitations
• Configuration or policy split: each context, the value it receives, and the reason the difference is deliberate. An undocumented split reads as an inconsistency, and the next reader unifies it and reintroduces the failure it was preventing
• Removal or migration: the removed component by name, the behavior that left with it, and where that responsibility now lives

For multiple topics, use this shape:

<imperative subject>

<verified reference lines>

<overview: what changes, why it matters, and the governing design>

~~ <material topic or failure mode 1> ~~

<symptom/need -> cause/constraint -> chosen change -> evidence>

  * <optional explicit decision with cause, consequence, and anchor>

~~ <material topic or failure mode 2> ~~

<symptom/need -> cause/constraint -> chosen change -> evidence>

<trailers>

Name sections after the actual problem or decision, not Changes or Implementation. A component, file, or artifact category is not the decision either; prefer the boundary, failure, or rule the section resolves. Lead the overview with the governing design rather than with provenance or scope bookkeeping — where the work was extracted from is one fact the message can state, not the reason the change exists. Use bullets for explicit decisions inside a topic, not as a substitute for topic sections. Keep exception snippets, logs, reference lists, and bullets in-family for the target repository.

Hard-wrap ordinary prose with literal newline characters at the width observed in recent target-repository merge messages; SkiaSharp's established cap is 80 columns. Code fences and commit-message renderers do not add this formatting, so visual wrapping in a UI is not a substitute. Preserve constructs that should remain on one line: the subject when reasonable, reference and compare URLs, section markers, code or log lines, and attribution trailers. Indivisible tokens may exceed the cap. Reflow bullet continuations using the repository's established indentation.