| 1 | --- |
| 2 | name: leaving-pr-comments |
| 3 | description: Use whenever leaving comments on GitHub. |
| 4 | --- |
| 5 | |
| 6 | # Leaving PR Comments |
| 7 | |
| 8 | Comments post from Clover's GitHub account but are written by an agent. A |
| 9 | reader should be able to tell who did what, and the comment should make sense |
| 10 | to someone who only sees the PR. Beyond the badge and point of view, everything |
| 11 | here is a default, not a checklist. It's not that deep. |
| 12 | |
| 13 | ## Attribution badge |
| 14 | |
| 15 | The first line of every agent-written comment is this badge, alone, followed by |
| 16 | a blank line: |
| 17 | |
| 18 | ```md |
| 19 |  |
| 20 | ``` |
| 21 | |
| 22 | Put the verified display name of the model writing the comment in both the |
| 23 | alt text and the badge: "Claude Sonnet 5.5", "GPT-6.1 Sol", "Qwen3.8 27B", |
| 24 | never a model ID like `claude-sonnet-5-5` or `gpt-6.1-sol`. In the badge URL, |
| 25 | write 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. |
| 27 | Do not guess. |
| 28 | |
| 29 | The badge is the only attribution: no callout, signature, footer, or second |
| 30 | credit. |
| 31 | |
| 32 | Use it on top-level comments, inline review comments, review bodies, replies to |
| 33 | bots or reviewers, and explanations left before resolving or dismissing |
| 34 | feedback. Leave it off PR descriptions, commit messages, and text Clover asked |
| 35 | to post verbatim without attribution. |
| 36 | |
| 37 | ## Point of view |
| 38 | |
| 39 | First 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 | |
| 49 | State Clover's opinions and rules in the comment's own voice, not as a relayed |
| 50 | note ("Clover's note:"). |
| 51 | |
| 52 | ## Shape |
| 53 | |
| 54 | Inline comments and bot replies are usually a line or three: the conclusion and |
| 55 | its evidence. For top-level comments and review bodies, this order works well; |
| 56 | skip what has nothing to say: |
| 57 | |
| 58 | 1. **What this means for the patch.** Thanks if earned, what changed, the |
| 59 | state, and what happens next. |
| 60 | 2. **Details.** How to reproduce, what broke, why, with file references. |
| 61 | 3. **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". |
| 65 | 4. **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 | |
| 68 | Clover's asks usually block the merge; findings only the agent made usually |
| 69 | don't. When a comment mixes both, label them `blocking:` and `non-blocking:`. |
| 70 | |
| 71 | Closing a PR takes a line or two of reason. |
| 72 | |
| 73 | Don't mention the chat, the transcript, Clover's instructions, or "as |
| 74 | requested"; turn an instruction into what the reader needs to know or do. |
| 75 | |
| 76 | ## Voice |
| 77 | |
| 78 | A variant of Clover's own: lowercase sentence starts, informal, short, warm, |
| 79 | blunt. Keep exact case for code, paths, UI labels, SHAs, and names. Backtick |
| 80 | code, 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 | |
| 114 | When closing or parking a stale PR, open the body with: "hi, we're working on |
| 115 | reducing the number of open PRs, and apologize for reviewer delays." |
| 116 | |
| 117 | ## Example |
| 118 | |
| 119 | A contrived one, to show the form rather than any real patch: |
| 120 | |
| 121 | ```md |
| 122 |  |
| 123 | |
| 124 | thanks for the patch, the topping picker reads much better now. one thing blocks the merge, the rest doesn't. |
| 125 | |
| 126 | blocking: `--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 | |
| 128 | non-blocking: `Toppings` → `Cheese` still says "mozzarella" on vegan orders. fine as a follow-up. |
| 129 | |
| 130 | Clover'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 | |
| 135 | Before posting, check the whole comment, including quoted text and |
| 136 | attachments, for secrets and private details. Preview the Markdown so the badge |
| 137 | and blank lines render. After posting, verify GitHub returned the comment or |
| 138 | review URL. Resolve a review thread only after its reply posted. |