| name | github-commenting |
| description | How to post clean, rich, deduplicated GitHub PR review comments — suggestion blocks, multi-line anchors, markers, formatting rules. Load before posting or fixing any PR comment. |
Clean GitHub PR commenting
Before posting anything
- List the existing review comments AND issue comments on the pull request first.
- Every comment you post starts with an invisible marker line:
<!-- yama:<stable-finding-id> -->. If a marker for the same finding already exists, do NOT post it again — update that comment if it needs fixing, otherwise leave it alone.
Inline comments
- Anchor to the exact file and line in the DIFF. A line that is not part of the diff cannot hold a comment — anchor to the nearest changed line and say so.
- Multi-line ranges:
start_line is the first line, line is the last; side / start_side are RIGHT for added lines and LEFT for deleted ones.
- Tool shapes differ: some GitHub MCP servers post an inline comment in one call; the hosted server may require the pending-review lifecycle (create review → add comments → submit). If a pending review is opened it MUST be submitted — both or neither, never half.
Suggestion blocks — a fix the author applies in one click
Explain the issue in one or two sentences ABOVE the block, then:
```suggestion
the replacement for the entire anchored line range
```
- The block's body replaces the WHOLE
start_line..line range — include every line of the range, exactly indented.
- If the replacement itself contains triple backticks (markdown files, code fences), use a four-backtick outer fence (
````suggestion) so GitHub does not close the block early.
- Prefer a suggestion block whenever you propose a concrete code fix - it is the fix the author applies in one click, and an inline comment about a code change should normally carry one. Fall back to prose only when the right code is genuinely uncertain.
Formatting for humans
- One finding per comment: severity (CRITICAL / MAJOR / MINOR), what breaks, why it matters here, and the fix.
- Cite rulebook ids where they apply.
- Evidence longer than ~10 lines goes in a collapsible section:
<details><summary>evidence</summary>…</details>.
- Prefer short headers, tables and task lists over walls of prose. No emoji noise.
The one summary comment
Post exactly ONE summary comment (an issue comment on the PR), marker <!-- yama:summary -->:
- verdict at the top (APPROVE or NEEDS_WORK), one sentence of rationale,
- a short table of findings — severity,
file:line, one-line description,
- what was checked and found clean, so silence is distinguishable from absence.
If a comment with that marker already exists, UPDATE it — never add a second summary.
