| name | pr-writing |
| description | Write or revise pull request descriptions for squash-merge review, focusing on the final net change against the merge base rather than branch history. |
Write the PR for a squash-merge review. Describe the final net change against
the merge base (main) only.
A pull request description should explain the system change, not just enumerate
file changes. It must give a reviewer enough context to understand the
architecture, runtime behavior, key technologies, and integration boundaries
without already knowing the branch history. Name the primary mechanisms and
tools involved, explain how data flows through the feature, and describe what
existing behavior changed. A reviewer should be able to answer "what is this?",
"how does it work?", "what are the important moving parts?", and "why was it
built this way?" from the PR itself.
Assume the reviewer sees only the final squashed delta and has no
knowledge of the development timeline. Focus on what exists in the final
code/spec/test changes, grouped by shipped behavior, architecture, validation,
and important decisions. Do not frame the PR around the latest incremental
changes or the sequence of development work.
Or in short: write PRs for a capable reviewer who has not lived inside the
branch.
Apply cold-reader policy
A PR reviewer is a cold reader. They see the squash diff against main and
the current state of main. They do not see your intermediate commits, the
design conversation that produced the change, abandoned implementations,
renames you reverted, or alternatives you considered along the way.
Apply the cold-reader policy (cold-reader/SKILL.md) when writing the PR.
The policy and its self-audit grep apply directly. In the PR context, the
practical rules are:
- Comparisons against
main are valid. "Removed flag --foo" works when
--foo exists in main — the reviewer sees both sides in the diff.
- Comparisons against unshipped alternatives are not. "Library X is used
instead of library W" is invalid if W never landed in the branch or in
main. The reviewer has nothing to compare against.
- Forward-looking rationale is fine. "Library X is used because it gives
us Y" describes the chosen design without pulling in the closet.
Run the cold-reader self-audit grep before publishing.
Anti-patterns specific to PR writing
- a list of changed files masquerading as an explanation for what changed
- cursory descriptions of "implements new feature X" that do not actually
enumerate what was modified or added to the system architecture, the
design of affected modules, new tooling/dependencies, why things were done
this way, etc.
- history-oriented PR narration / archaeological branch-work summaries
- focusing on the most recent incremental changes instead of the full final
delta against
main
- describing replacements of code that is not present in the squashed diff
(covered by cold-reader policy — the reviewer cannot see what was replaced
if the replacement isn't in the diff)
Useful inclusions
- Why a design decision was made, framed forward-looking. Include only when
the reviewer will plausibly wonder.
- Cross-file architectural notes the diff alone would not make obvious — how
data flows, what invariants hold across modules, where the integration
boundaries are.
If a design rationale only makes sense by contrasting against an alternative
that lived during development but is not in the final diff, the rationale
belongs in commit messages or design docs, not the PR body.
Writing correctly to GitHub APIs
When updating long-form PR text, treat the PR body as publication content, not
shell content and not patch content. Draft it in a plain temporary markdown
file exactly as you want reviewers to read it, with no diff markers, no patch
prefixes, and no shell interpolation. Then send that file to GitHub through a
file-based API path, and verify the stored PR body afterward. Never compose PR
prose inline inside shell commands, and never reuse patch-formatted text as PR
content.
