A PR Comment Carries What the Page Cannot Render
Promoted from the always-loaded pr-comment-vs-ui-affordances.md portfolio
rule, whose stub keeps the gate line.
GitHub renders most of a pull request's state on the page: merge status, check names and outcomes, review rollup, branch names, diff size, labels. A comment that restates any of it is not merely redundant. It explains GitHub to someone who maintains a repository on GitHub. It buries the one or two sentences that carry new information. And it makes a short reply look long, so the reader skims and misses the part that mattered.
The law: before writing a sentence into a PR or issue comment, ask whether the reader is looking at that fact already. If the page renders it, cut it. The comment's job is the part of the story the page cannot show.
When to Use This Skill
| Use this skill when... | Use something else when... |
|---|---|
| Replying to a maintainer on a PR or issue | Register and structure once content is decided → communication-plugin:ticket-drafting-guidelines |
| Running a cold-read gate over a comment | The text goes to a context-free reader (an issue body, docs) → agent-patterns-plugin:cold-read-gate |
| Writing a PR description or a status update comment | Choosing the PR title → git-plugin:github-pr-title |
What the page renders (measured, not assumed)
Captured 2026-09-02 from Comfy-Org/ComfyUI_frontend#13280 as a signed-in
maintainer would see it. This is an inventory to check against, not a claim
that GitHub's layout is frozen — re-capture if a comment hinges on it.
| Region | Renders |
|---|---|
| Header, no scrolling | State (Open/Merged/Closed); author; wants to merge N commits into <base> from <head> with both branch names; tab counts for Conversation / Commits / Checks / Files changed; the +N −M diff stat |
| Sidebar | Each reviewer with their state (approved / pending); At least 1 approving review is required to merge this pull request; assignees; labels; project; milestone |
| Merge box, foot of the Conversation tab | Review rollup (Changes approved, 1 approval, 1 pending review); 17 workflows awaiting approval — This workflow requires approval from a maintainer, with a help link; counts of pending / skipped / successful checks; every check by name, each badged Required where it is; This branch is out-of-date with the base branch / Changes can be cleanly merged, with an Update branch button; conflict state when conflicting |
Do not write, in a comment:
- Check names, counts, or states; whether CI passed, failed, or has not run.
- That workflows await approval, or how the fork-PR approval gate works.
- Mergeable / conflicting / out-of-date status.
- Branch names, commit counts, file counts, diff size.
- Who reviewed, who is assigned, which labels are set.
- That you lack write access — the
<fork>:<branch>header already says so.
Write instead the things that exist nowhere on the page:
- What you did that leaves no diff: what you verified, on which commit, and what that verification does not cover.
- Why you chose one approach over another.
- A claim about code the reader would otherwise have to go find, with the path.
- A check that produced no change (
mainhas not touched this file since your base) — absence is invisible by construction. - A decision you need from them that no button can ask for.
The canonical break (2026-09-02, #13280)
Replying to a maintainer who had rebased the PR, I wrote a closing paragraph
explaining that a force-push re-arms the fork-PR gate, that 17 runs sat in
action_required, and naming four of them. The merge box directly below the
comment said "17 workflows awaiting approval / This workflow requires
approval from a maintainer", linked GitHub's own explainer, listed all four
required checks by name, and offered the button. The paragraph was a worse copy
of the box, addressed to the only person who could press it.
An earlier draft of the same comment also restated merges clean onto current main; the box renders Changes can be cleanly merged.
Why a cold-read gate pushes you toward this mistake
agent-patterns-plugin:cold-read-gate is the right instrument for outward-bound
text and the wrong one to apply naively here, because its reader is
context-free by construction while a PR reader is surrounded by rendered
state. The gate asks, correctly for a stranger and wrongly for a maintainer,
what the fork-PR gate is, whether the four named workflows are all of them, and
what the merge status is. Answering those inflates the comment with exactly the
duplication above.
Two consequences:
- Brief the reader with what the surrounding UI shows. Put it in the
prompt's
Ignore:list: "the reader can see the merge box, the check names, the review state, and both branch names; do not ask for those." Otherwise, its findings and this skill pull in opposite directions. - A gate verdict is about sentences, never about whether a paragraph should
exist. In the break above, the round-one readers returned
needs-revisionpartly because of the verification hedging; the fix that followed made the comment longer. Both a prose linter and a cold reader score what is on the page. Only a human asked the question that removed 58% of it.
Related
documentation-plugin:docs-single-source— link, don't duplicate. This is that law with the rendered UI as the single source.agent-patterns-plugin:cold-read-gate— the instrument this skill scopes.communication-plugin:ticket-drafting-guidelines— register and structure once the content is decided; this skill decides the content.- The labels, assignees, and reviewers the UI renders are set through a
metadata-hygiene checklist at PR creation (
git-plugin:git-pr).