From 02322c9f9a00948dddc4aca851ad9f1c4896cc24 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Sun, 20 Sep 2026 10:28:29 +0200 Subject: [PATCH 1/2] docs: name the three surfaces a PR's feedback can sit on Reading the comments on a pull request is three API calls, and the reference documented each endpoint separately without stating that all three have to be read. A maintainer can put a whole review, `suggestion` blocks included, into the review body instead of onto a diff line. Both other queries then return an empty list, so "there are no comments" is reported while a full review waits. Observed on TYPO3-Documentation/TYPO3CMS-Reference-CoreApi#6992: issue comments 0, review comments 0, one COMMENTED review carrying two suggestions. The new subsection also states the two consequences for the reply: a suggestion in a review body has no apply button, and the body is not a thread, so the answer is a PR comment citing the commit SHA. Assisted-by: claude-code:claude-opus-5 Agent-Session: https://claude.ai/code/session_01NnQTMiCugD4XCP1kptR2BE Agent-Host: 0493f0 Signed-off-by: Sebastian Mendel --- .../references/pull-request-workflow.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/skills/git-workflow/references/pull-request-workflow.md b/skills/git-workflow/references/pull-request-workflow.md index ecddbe0..815d738 100644 --- a/skills/git-workflow/references/pull-request-workflow.md +++ b/skills/git-workflow/references/pull-request-workflow.md @@ -984,6 +984,30 @@ 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. A `suggestion` block in a review body has **no +"Apply suggestion" button** — that control belongs to inline review comments — +so 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 From e00a415eaffeb527ede306e57aacceefb34ff854 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Sun, 20 Sep 2026 11:41:18 +0200 Subject: [PATCH 2/2] docs: cite GitHub's own placement rule for a committable suggestion The paragraph asserted that a suggestion block in a review body carries no apply button without naming a source. GitHub documents the control as part of a line comment on the Files-changed tab, so the sentence now quotes that instruction and links the page instead of stating the consequence bare. Assisted-by: claude-code:claude-opus-5 Agent-Session: https://claude.ai/code/session_01NnQTMiCugD4XCP1kptR2BE Agent-Host: 0493f0 Signed-off-by: Sebastian Mendel --- .../references/pull-request-workflow.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/skills/git-workflow/references/pull-request-workflow.md b/skills/git-workflow/references/pull-request-workflow.md index 815d738..a8289b2 100644 --- a/skills/git-workflow/references/pull-request-workflow.md +++ b/skills/git-workflow/references/pull-request-workflow.md @@ -1002,11 +1002,15 @@ 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. A `suggestion` block in a review body has **no -"Apply suggestion" button** — that control belongs to inline review comments — -so 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. +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