1---
2name: leaving-pr-comments
3description: Use whenever leaving comments on GitHub.
4---
5
6# Leaving PR Comments
7
8Comments post from Clover's GitHub account but are written by an agent. A
9reader should be able to tell who did what, and the comment should make sense
10to someone who only sees the PR. Beyond the badge and point of view, everything
11here is a default, not a checklist. It's not that deep.
12
13## Attribution badge
14
15The first line of every agent-written comment is this badge, alone, followed by
16a blank line:
17
18```md
19![comment written by Claude Sonnet 5.5](https://img.shields.io/badge/comment_written_by-Claude_Sonnet_5.5-8a63d2?style=flat-square)
20```
21
22Put the verified display name of the model writing the comment in both the
23alt text and the badge: "Claude Sonnet 5.5", "GPT-6.1 Sol", "Qwen3.8 27B",
24never a model ID like `claude-sonnet-5-5` or `gpt-6.1-sol`. In the badge URL,
25write spaces as `_`, `-` as `--`, and `_` as `__` (`GPT-6.1 Sol` →
26`GPT--6.1_Sol`). If the harness exposes no model name, use the harness name.
27Do not guess.
28
29The badge is the only attribution: no callout, signature, footer, or second
30credit.
31
32Use it on top-level comments, inline review comments, review bodies, replies to
33bots or reviewers, and explanations left before resolving or dismissing
34feedback. Leave it off PR descriptions, commit messages, and text Clover asked
35to post verbatim without attribution.
36
37## Point of view
38
39First person is ambiguous here, so don't write "I", "me", or "my".
40
41| write | for |
42| ------------ | ------------------------------------------------------------- |
43| you | the patch author, or whoever the comment replies to |
44| Clover | Clover specifically: her accounts, machines, decisions, plans |
45| the agent | the model doing work for Clover: pushing, testing, fixing |
46| we, our | Clover and her agents together: "we tried it on a fresh install" |
47| (no subject) | plain actions: "pushed abc1234", "tried it on Linux" |
48
49State Clover's opinions and rules in the comment's own voice, not as a relayed
50note ("Clover's note:").
51
52## Shape
53
54Inline comments and bot replies are usually a line or three: the conclusion and
55its evidence. For top-level comments and review bodies, this order works well;
56skip what has nothing to say:
57
581. **What this means for the patch.** Thanks if earned, what changed, the
59 state, and what happens next.
602. **Details.** How to reproduce, what broke, why, with file references.
613. **What wasn't verified, if it leaves something on the reader.** The reason
62 and who carries it ("Clover has no ARM machine, so we're trusting your own
63 testing there"), rather than a bare "did not test X" or a passive "still
64 needs verification".
654. **Clover's general note, if she gave one,** and how serious it was in plain
66 words. Don't invent a rule or a severity she didn't give.
67
68Clover's asks usually block the merge; findings only the agent made usually
69don't. When a comment mixes both, label them `blocking:` and `non-blocking:`.
70
71Closing a PR takes a line or two of reason.
72
73Don't mention the chat, the transcript, Clover's instructions, or "as
74requested"; turn an instruction into what the reader needs to know or do.
75
76## Voice
77
78A variant of Clover's own: lowercase sentence starts, informal, short, warm,
79blunt. Keep exact case for code, paths, UI labels, SHAs, and names. Backtick
80code, paths, and UI labels. Her own review lines, for calibration:
81
82> windows seems flaky. not your fault.
83> looks reasonable. doing some testing before merging
84> model resolution already is aware of this, and should snap you to the correct tier already. does that code break and this is the fix?
85> needs a rebase anyways
86
87- Say "not your fault" when the failure isn't theirs.
88- Ask a direct question instead of hedging.
89- Thank once, specifically when there's something to name.
90- Leave Clover's harsh slang to Clover (cooked, slop, trolled). From an agent
91 it reads as mockery of the contributor.
92- Skip canned openers, status narration, and closing summaries.
93
94## Dictionary
95
96| term | meaning |
97| -------------- | ---------------------------------------------------------------- |
98| patch | the contributor's change; preferred over "PR" for the change itself |
99| PR | the GitHub object: open PRs, linked issue, PR description |
100| harness | an agent CLI driven by another tool |
101| code review | reading the diff |
102| manual testing | running the feature end to end |
103| spot check | a quick run of the main path, not a full test |
104| smell check | a first look; it fails when something is obviously off |
105| hardening | robustness work. Partial hardening doesn't close the issue |
106| edge cases | e.g. empty input, signed out, no network |
107| non-blocking | the merge doesn't wait on it |
108| nitpicks | style-level notes |
109| rebase | "needs a rebase" means the branch is behind and conflicts |
110| draft | marking as draft parks a patch; it is not a rejection |
111| sus | suspicious: looks off, worth a second look |
112| soon™ | soon, but timing not promised |
113
114When closing or parking a stale PR, open the body with: "hi, we're working on
115reducing the number of open PRs, and apologize for reviewer delays."
116
117## Example
118
119A contrived one, to show the form rather than any real patch:
120
121```md
122![comment written by GPT-6.1 Sol](https://img.shields.io/badge/comment_written_by-GPT--6.1_Sol-8a63d2?style=flat-square)
123
124thanks for the patch, the topping picker reads much better now. one thing blocks the merge, the rest doesn't.
125
126blocking: `--extra-cheese` doubles the cheese twice when the order also has `--deluxe`, since both `apply_deluxe()` and `apply_extras()` in `src/order/toppings.rs` scale `cheese_grams`. is that intended, or should deluxe skip the extras pass?
127
128non-blocking: `Toppings` → `Cheese` still says "mozzarella" on vegan orders. fine as a follow-up.
129
130Clover's oven tops out at 250°C, so the 300°C bake profile wasn't tried. we're trusting your own test of that one.
131```
132
133## Posting
134
135Before posting, check the whole comment, including quoted text and
136attachments, for secrets and private details. Preview the Markdown so the badge
137and blank lines render. After posting, verify GitHub returned the comment or
138review URL. Resolve a review thread only after its reply posted.