pr-suggestion — turn a review finding into a one-click applyable change

The spine, one question:

Is this finding a literal replacement of a line the PR already changed? If yes, post it as a suggestion so the author applies it with one click. If no, post a described comment — a suggestion here would be broken or wrong.

Posting gate (repo-wide rule, same as pr-review-kit): nothing in this skill is posted to GitHub without explicit human authorization. Prepare the payloads, show what will be posted and where, and call the API only on an explicit go.

A suggestion is a gift when it fits and a trap when it doesn't. A wrong or unappliable suggestion is worse than a clear description: the author clicks "Commit suggestion," gets a broken commit or a no-op, and learns to distrust your review. Match the tool to the finding.

The suggestability decision rule (run this before writing anything)

A finding is suggestable only if all three hold:

1. In-diff — the line(s) you'd replace are on the RIGHT side of the diff (added/changed in the PR head). Unchanged context lines cannot host a suggestion at all — the API rejects them.
2. Contiguous — the fix is one continuous line range, not edits scattered across the file. A suggestion replaces exactly the anchored range.
3. Literal replacement — you can write the full new text for that range. A suggestion is a verbatim swap, not a diff or an instruction.

If it fails the rule: post a normal described comment (or hand a git apply patch for larger structural/additive fixes). Do not force a suggestion.

What the comment around the fence says

A suggestion ships with prose above the fence, and that prose is the review. The fence says what to change; the sentence above it is the only place the author learns whether they have to, and why:

Every finding carries a severity tag whose merge impact is explicit, so the author never has to guess whether a comment is a gate or a thought:

Lead with the TL;DR in plain language, before any detail: what you found, whether it blocks, and what you would do. Burying the verdict under three paragraphs of trace makes the author read the whole comment to learn it was a nit.

Frame findings as questions rather than commands — "It looks like X — would it be worth considering Y?" rather than "You should do X." The imperative is only honest when you are certain, and you are certain less often than you feel; the question costs the same characters and leaves the author room to answer "no, because…" without it reading as defiance.

Every finding cites evidence: a file:line, another PR, a ticket, a doc URL, or the output of an experiment you actually ran. A finding with no citation is an opinion wearing a severity tag.

Never flag style, formatting, or naming. The formatter and the linter own those. A review that spends its first three comments there teaches the author to skim the rest of it.

Match the tone to the author. Someone senior in this code wants the mechanism and nothing around it; someone newer needs the why and a pointer to the pattern the codebase already uses. The finding is identical either way — only the scaffolding changes.

The severity tag matters more here than anywhere else, because a one-click "Commit suggestion" button reads as an instruction whatever the words say. A [Non-blocking] suggestion the author declines should cost them one click of "dismiss," not a justification.

Why gh can't, and what to use instead

gh pr review only sets a top-level body (--body/--comment) — no inline comments, no suggestions. Inline comments (suggestions included) go through the REST API:

• New review with suggestions: POST /repos/{owner}/{repo}/pulls/{N}/reviews with a comments[] array; each comment's body contains the fence.
• Turn an existing inline comment into a suggestion: PATCH /repos/{owner}/{repo}/pulls/comments/{comment_id} with a new body.

A suggestion is just an inline comment whose body is:

```suggestion
<the full replacement text for the anchored line(s)>
```

Procedure

1. Find the anchor (the RIGHT-side line number in the diff)

The line must be a changed line in the head commit. Discover it from the diff rather than guessing — line numbers drift:

gh pr diff <N> --repo <owner/repo> --patch | awk '
  /^diff --git/ { f=$3; sub(/^a\//,"",f) }
  /^@@/ { match($0,/\+[0-9]+/); rl=substr($0,RSTART+1,RLENGTH-1)+0; next }
  /^\+/ && !/^\+\+\+/ { print f":"rl": "substr($0,2); rl++; next }
  /^ / { rl++ }'    # context lines advance the RIGHT counter but are NOT anchorable

Only lines printed with a + by this walk are addable/changed and therefore anchorable. If your target isn't in the list, it's unchanged context → not suggestable (see the rule).

2. Build the payload with jq (never hand-escape)

The fence content has backticks, quotes, and newlines — assemble with jq --rawfile so escaping is correct. Write each comment body to a file first.

Single-line suggestion (replaces one line):

jq -n --rawfile s1 body1.md --rawfile summary summary.md '
{ event:"COMMENT", body:$summary, comments:[
  { path:"path/to/file.go", line:42, side:"RIGHT", body:$s1 }
]}' > payload.json
gh api repos/<owner>/<repo>/pulls/<N>/reviews --input payload.json

A comment body that IS a suggestion (body1.md):

Off-by-one: the cap is inclusive, so this should be `<=`.
```suggestion
	if requested <= maxPageSize {
```

Multi-line suggestion (replaces a range) — add start_line:

{ "path":"f.go", "start_line":40, "line":42, "start_side":"RIGHT", "side":"RIGHT", "body":"...fence..." }

The fence must contain the full replacement for lines 40–42 inclusive.

Addition-append trick (a suggestion can only replace, so to add a line, anchor to a real changed line and include it plus the new content):

```suggestion
	existingAddedLine := foo()
	if existingAddedLine == nil { return errX }   // the line you're adding
```

3. Choose the review event

• COMMENT — deliver suggestions without approving (default when unsure; never infer approval).
• APPROVE / REQUEST_CHANGES — only when the human said so. Suggestions attach to any event, including a later PATCH onto an existing review comment.

4. Verify it landed

gh api repos/<owner>/<repo>/pulls/<N>/comments \
  --jq '.[] | select(.user.login=="<me>") | "\(.path):\(.line)  \(.body[:60])"'

Confirm the comment shows the ```suggestion fence and sits on the intended line.

Automation — scripts/pr-suggest.sh

The mechanics above (anchor discovery → validate in-diff → build payload → post → verify) are deterministic and live in scripts/pr-suggest.sh. The script owns the mechanical half and enforces the in-diff gate — it refuses (nonzero exit) if --line is unchanged context, so an unappliable "Commit suggestion" button is impossible to post. What it does not decide stays with you: whether the finding is suggestable at all (the rule above), the replacement text, and whether to APPROVE.

# Preview (dry-run by default — posts nothing):
pr-suggest.sh --pr owner/repo#N --file path/f.go --line 42 \
    --replacement /tmp/fix.txt [--start 40] [--note /tmp/why.md]

# Post it (COMMENT review) once you've eyeballed the payload:
pr-suggest.sh --pr owner/repo#N --file path/f.go --line 42 \
    --replacement /tmp/fix.txt --note /tmp/why.md --post

Split of labor: the script is ~90% of this skill (the reproducible I/O + the enforceable gate); the prose above is the ~10% it can't decide — should this be a suggestion, and what should it say. Run --dry-run (the default) and read the payload before --post; the dry-run output is also the canonical example of a well-formed suggestion payload.

Gotchas

• Unchanged context is unanchorable. The single most common mistake: the ideal fix lives in code the PR didn't touch. You cannot suggest there. Anchor the comment to the nearest changed line that carries the same intent and describe the fix, or hand a patch.
• Stale head. A suggestion is bound to a commit; if the PR head moves, the suggestion (and any approval) may be dismissed. Post against the current head.
• Exact bytes matter for the surrounding code, not the fence. The fence is a replacement, so its indentation must match the file's (tabs vs spaces). Copy the leading whitespace from the target line.
• side defaults to RIGHT; only set LEFT to comment on a deleted line (you cannot suggest on a deleted line — there's nothing to replace).
• Don't batch unrelated suggestions into one giant review if the author is iterating round-by-round; small, per-line suggestions are easier to accept or reject individually.

Cross-references

• Upstream: structural-pr-review / pr-review-kit produce the findings; this skill is the posting mechanic their gated Phase-8 step can call for the findings that pass the suggestability rule.
• Sibling: for structural/additive findings that fail the rule, hand a verified git apply patch instead (build + test it first), or leave a described comment.