Skip to content

docs: name the three surfaces a PR's feedback can sit on #337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CybotTM merged 2 commits into from
Sep 20, 2026
Merged

docs: name the three surfaces a PR's feedback can sit on #337

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
02322c9
docs: name the three surfaces a PR's feedback can sit on
CybotTM Sep 20, 2026
e00a415
docs: cite GitHub's own placement rule for a committable suggestion
CybotTM Sep 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions skills/git-workflow/references/pull-request-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -984,6 +984,34 @@ it — the "new" case-sensitivity finding was a regression introduced by that
review's requested guards, and the real next step (re-review of the standing
blocker) surfaced only after posting.

### Feedback sits on three surfaces — query all of them

"Read the comments on this PR" is three separate API calls, and each one returns
an empty list when the feedback lives on another surface:

| Surface | Query | Holds |
|---|---|---|
| issue comments | `gh api repos/$R/issues/$PR/comments --paginate` | the plain comment box under the PR |
| reviews | `gh api repos/$R/pulls/$PR/reviews --paginate` | a review's own body, including `suggestion` blocks written there |
| review comments | `gh api repos/$R/pulls/$PR/comments --paginate` | the inline comments anchored to diff lines |

A maintainer can put a whole review — prose, reasoning, several `suggestion`
blocks — into the review **body** rather than onto a diff line. Both other
queries then return `[]`, and "there are no comments on this PR" is wrong while
a full review is waiting. Observed on
TYPO3-Documentation/TYPO3CMS-Reference-CoreApi#6992, 2026-09-18: issue comments
0, review comments 0, and one `COMMENTED` review carrying two suggestions.

Two consequences for the reply. The committable-suggestion control belongs to a
**line comment on the Files-changed tab** — GitHub's own instruction is "to
suggest a specific change to the line or lines, click [the suggestion icon],
then edit the text within the suggestion block"
([Commenting on a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request)).
A `suggestion` block typed into a review body is therefore ordinary fenced
code: the change is made by hand, and "I committed your suggestion" mis-states
what happened. And the review body is not a thread, so there is nothing to
resolve — answer with a PR comment citing the commit SHA.

### Subagent findings: verify line anchors against the diff you fetched

Inline comments anchor to diff positions. A file:line pair reported by a review
Expand Down
Loading