Merge pull request #2273 from modelcontextprotocol/v2/docs/2254-inline-review-replies

docs: reply to each review comment in its own thread, not in a rollup comment

.claude/skills/pr-flow/SKILL.md

@@ -279,11 +279,39 @@ arrive late (see step 8).
 
 - It is **not** necessary to implement every suggestion. Implementing one a
   different way, or declining it with a reason, is fine.
-- After making the changes, **respond to each comment** with what was done, or
-  why it was ignored.
-- ⚠️ **Inline replies go hidden once the fix is pushed** (the threads become
-  outdated), so **mirror each round at PR level** as a summary comment, and always
-  read the "Suppressed comments" block.
+- After making the changes, **reply to each review comment in its own thread**
+  with what was done, or why it was declined. That inline reply is the primary
+  response and it is not optional — each review comment is a discussion thread
+  with its own resolve state, and a reply _in_ the thread is the only thing a
+  reviewer reading that thread sees. It does **not** resolve the thread:
+  resolving is a separate act — the "Resolve conversation" button, or the
+  `resolveReviewThread` GraphQL mutation — and it is the reviewer's to make. The
+  reply is what makes resolving it defensible.
+
+  ```sh
+  # Fetch the round's comments by REVIEW id — the unpaginated /reviews listing
+  # hides later rounds behind your own replies.
+  # --paginate: this endpoint returns 30 per page, and a round you only half
+  # fetch is a round you only half answer.
+  gh api --paginate repos/modelcontextprotocol/inspector/pulls/<N>/reviews/<REVIEW_ID>/comments \
+    --jq '.[]|"\(.id) \(.path):\(.line)\n\(.body)"'
+
+  # Reply into one thread, keyed by the comment id from above.
+  gh api repos/modelcontextprotocol/inspector/pulls/<N>/comments/<COMMENT_ID>/replies \
+    -f body='Fixed in <sha> — …'
+  ```
+
+- ⚠️ **Then mirror the round at PR level, in addition — never instead.** Inline
+  replies go hidden once the fix is pushed, because the threads become outdated,
+  so a summary comment is what keeps the round readable afterwards. It does
+  **not** discharge the per-comment replies: a rollup bullet cannot be connected
+  back to the thread it answers, so the thread stays open with a finding and
+  silence in it, and by round three matching bullets to comments is
+  reconstruction rather than reading.
+- ⚠️ Always read the **"Suppressed comments"** block in the review body. Those
+  findings have no comment id, so they have no thread to reply into — the
+  PR-level mirror is the only place they can be answered, and it is the one case
+  where answering there is the whole response.
 - ⚠️ **Copilot's inline comments lag its review body.** The body's "generated N
   comments" count lands first; fetch by recency and reconcile. Repeated
   re-review silence means the session ended.

AGENTS.md

@@ -372,6 +372,7 @@ When asked to respond to a code review of a PR:
 - it is not necessary to implement all suggestions
 - you are free to implement suggestions in a different way, or to ignore one if there is a good reason
 - after making the changes, respond to each review comment with what was done (or why it was ignored)
+- **that response goes in the review comment's own thread — a rollup comment does not discharge it.** Each review comment is a discussion thread with its own resolve state, so a bullet posted elsewhere on the page cannot be connected back to the thread it answers: the thread stays open showing a finding and no reply, and the PR reads as though the review were ignored. Replying does not itself **resolve** a thread — that is a separate act and the reviewer's to make — but it is what makes resolving it defensible. Reply inline first, per comment; then post the PR-level summary **in addition**, because inline replies go hidden once the fix is pushed. A finding in the review's "Suppressed comments" block has no thread to reply into, so the summary is the only place it can be answered — that is the one exception. The `gh` calls are in the `pr-flow` skill, step 8.
 
 ## Always test new or modified code