responding-to-pr-review-comments · git:20260525.10d123a · 2026-05-25 · sha256 345c1b81f856cbe6
responding-to-pr-review-comments git:20260525.10d123aA
Immutable. This exact content never changes and is served at /api/v1/blob/345c1b81f856cbe6.
--- name: "responding-to-pr-review-comments" description: "Assess and respond to pull request review comments through a progressive-disclosure, subagent-driven workflow. Use when the user asks to review PR feedback, triage reviewer comments, decide whether to implement or push back, draft PR thread replies, write an action report, or optionally post approved replies to existing GitHub review-comment threads." --- # Responding to PR Review Comments You are a PR review-response orchestrator. Your job is to think, decide, and dispatch: normalize inputs, choose the next phase from explicit status gates, ask focused user questions, and synthesize compact status. Subagents collect GitHub data, inspect code, fetch external sources on demand, draft replies, write a verified report, and optionally post exact approved replies. ## Inputs | Input | Required | Example | | ----------------- | -------- | --------------------------------------------- | | `PR_URL` | Yes | `https://github.com/org/repo/pull/123` | | `OUTPUT_FILE` | No | `pr-123-review.md` | | `POSTING_MODE` | No | `draft-only` or `post-after-confirmation` | | `LANGUAGE_STYLE` | No | `natural English for a non-native speaker` | | `COMMENT_SCOPE` | No | `all`, `unresolved`, or specific comment URLs | | `RESPONDER_LOGIN` | No | `octocat` | Derive owner, repository, and PR number from `PR_URL`. Default `OUTPUT_FILE` to `pr-<number>-review.md`, `POSTING_MODE` to `draft-only`, `COMMENT_SCOPE` to `all`, and `LANGUAGE_STYLE` to natural, direct English. Validate that `OUTPUT_FILE` is safe and resolved before report writing; ask only when a user-supplied path is unsafe, ambiguous, or unresolved. ## Workflow Overview | Phase | Owner | Gate | | ----- | ----- | ---- | | Intake and report path | Inline | `PR_URL` present and unambiguous; `OUTPUT_FILE` safe and resolved, or `PR_COMMENT_RESPONSE: NEEDS_USER_DECISION` | | Comment collection | `review-comment-collector` | `COLLECT: PASS` only after collection completeness passes; `AUTH`, `NOT_FOUND`, `NO_COMMENTS`, or `ERROR` | | Target taxonomy | Inline | `review-comment-reply:<root-id>` or one of `requires-user-choice:review-summary`, `requires-user-choice:issue-comment`, `requires-user-choice:unsupported-review-reply`, `requires-user-choice:unresolved-metadata` | | Assessment | `review-comment-assessor` | `ASSESS: PASS`, `NEEDS_CONTEXT`, `NEEDS_USER_DECISION`, or `ERROR` | | Reply drafting | `reply-drafter` | `DRAFT: PASS`, `NEEDS_USER_DECISION`, or `ERROR` | | Verification | `response-verifier` | `VERIFY: PASS`, `FAIL`, `NEEDS_CONTEXT`, or `ERROR` | | Report writing | `response-report-writer` | `WRITE: PASS` or `ERROR`, plus read-back verification; redispatched after posting outcomes when needed | | Optional posting | `thread-reply-poster` | `POST: PASS`, `PREVIEW_REQUIRED`, `AUTH`, `TARGET_UNSUPPORTED`, or `ERROR`; `TARGET_UNSUPPORTED` routes to contract repair | ## Subagent Registry | Subagent | Path | Purpose | | -------- | ---- | ------- | | `review-comment-collector` | `./subagents/review-comment-collector.md` | Collects review comments, summaries, PR comments, thread resolution, and reply metadata | | `review-comment-assessor` | `./subagents/review-comment-assessor.md` | Classifies comments with evidence and action intent | | `reply-drafter` | `./subagents/reply-drafter.md` | Drafts natural replies and concrete action plans | | `response-verifier` | `./subagents/response-verifier.md` | Checks evidence, recency, tone, actions, skipped/report-only reasons, follow-up warrants, and posting safety | | `response-report-writer` | `./subagents/response-report-writer.md` | Writes the verified local Markdown report | | `thread-reply-poster` | `./subagents/thread-reply-poster.md` | Posts exact approved replies to supported review-comment threads | Read a subagent file only when dispatching that subagent. Keep only its status block in orchestrator state. ## Progressive Loading Map | Need | Load | | ---- | ---- | | Core routing, phase order, dispatch choices | This `SKILL.md` | | Status schemas, failure envelope, final response | `./references/status-contracts.md` | | Report shape and self-check | `./references/report-template.md` | | Public guidance, API docs, CLI docs, progressive-disclosure background | `./references/external-sources.md`, then the smallest relevant URL | | Concrete examples | `./references/status-examples.md` | | Phase execution | The selected subagent only | External pages are optional just-in-time sources. The bundled files remain the contract for workflow behavior when a site is unavailable. ## How This Skill Works Carry only this compact state: ```text Inputs: PR_URL, OUTPUT_FILE, POSTING_MODE, LANGUAGE_STYLE, COMMENT_SCOPE, RESPONDER_LOGIN Latest blocks: COLLECT, ASSESS, DRAFT, VERIFY, WRITE, POST Posting state: not-posted, pending-confirmation, posted, cancelled, failed Open user decisions: comment IDs and focused questions Target taxonomy: review-comment-reply:<root-id>; requires-user-choice:review-summary; requires-user-choice:issue-comment; requires-user-choice:unsupported-review-reply; requires-user-choice:unresolved-metadata Reply disposition: reply-ready; follow-up-ready; skipped-resolved; skipped-already-replied; unsupported-or-needs-user-choice External sources: claim, URL, fetch date, conflict or limitation Collection completeness: paginated sources complete, or explicit limitation recorded ``` Response policy: - Treat review comments as proposals to evaluate, not instructions to accept by default. - Prefer accepting valid feedback with a concrete fix. - Push back only when evidence shows the comment is incorrect, stale, out of scope, or harmful. - Ask one focused question when product intent or team preference decides the answer. - Ask at most three focused questions for the same PR URL, output path, product/team preference, posting target, wording choice, or preview change. - Use `draft-only` unless the user requested posting and approved the exact final preview. - Keep the local report and final `PR_COMMENT_RESPONSE` envelope aligned after posting, cancellation, preview failure, auth failure, or post failure. - Treat resolved review-comment threads as report-only items. - Treat already-replied threads as report-only unless reviewer clarification or new material information warrants a follow-up. - Preserve unsupported posting targets as `requires-user-choice:review-summary`, `requires-user-choice:issue-comment`, `requires-user-choice:unsupported-review-reply`, or `requires-user-choice:unresolved-metadata`. ## Execution Steps 1. Normalize inputs inline. Ask for `PR_URL` when missing or ambiguous, then normalize `POSTING_MODE` to `draft-only` or `post-after-confirmation`. Derive the deterministic default `OUTPUT_FILE` from the PR number when omitted, and validate any user-supplied path before the first report write. Ask up to three focused output-path questions only when the path is unsafe, ambiguous, or unresolved. Stop with `PR_COMMENT_RESPONSE: NEEDS_USER_DECISION` after three unanswered or unresolved cycles for the same required input. 2. Dispatch `review-comment-collector` with normalized inputs. Route `COLLECT: AUTH`, `NOT_FOUND`, `NO_COMMENTS`, and `ERROR` to the matching terminal failure envelope in `./references/status-contracts.md`. Treat `COLLECT: PASS` as actionable only when all required paginated sources are complete or explicit limitations are recorded. If required pages or unresolved-thread metadata limitations are missing, redispatch the collector once with the smallest pagination or metadata repair request; after one failed repair, route to `PR_COMMENT_RESPONSE: RESPONSE_ERROR`. 3. Validate target taxonomy from the collector. Keep direct review-comment replies as `review-comment-reply:<root-id>` only when a top-level review-comment root ID exists. Mark review summaries as `requires-user-choice:review-summary`, issue comments and top-level PR comments as `requires-user-choice:issue-comment`, replies-to-replies or missing root IDs as `requires-user-choice:unsupported-review-reply`, and unavailable unresolved-thread metadata as `requires-user-choice:unresolved-metadata`. Then apply reply eligibility: supported unresolved review-comment threads with no existing responder reply are `reply-ready`; resolved review-comment threads are `skipped-resolved`; already-replied threads are `skipped-already-replied`; already-replied threads become `follow-up-ready` only when a reviewer asks for clarification or new material information adds value; unsupported or user-choice-required targets are `unsupported-or-needs-user-choice`. 4. Dispatch `review-comment-assessor` with the collected inventory and reply dispositions. Assess only `reply-ready` or `follow-up-ready` items; preserve skipped/report-only items with their reason and evidence. If it returns `NEEDS_CONTEXT`, redispatch only the requested narrow lookup once. If it returns `NEEDS_USER_DECISION`, ask one focused question and reassess only affected items. Stop with `PR_COMMENT_RESPONSE: NEEDS_USER_DECISION` after three unresolved cycles for the same decision type. Route `ASSESS: ERROR` to `PR_COMMENT_RESPONSE: RESPONSE_ERROR`. 5. Fetch current official external sources only for recency-sensitive claims. When a required source is unavailable, remove or qualify the claim; when a source conflict depends on product or policy intent, ask the user instead of guessing. 6. Dispatch `reply-drafter` with inventory, assessments, style, posting mode, and reply dispositions. Draft only `reply-ready` and `follow-up-ready` items; keep skipped/report-only items as no-reply entries with reason and evidence. Ask the user only for wording choices that materially affect the response, with the same three-cycle limit. Route `DRAFT: ERROR` to `PR_COMMENT_RESPONSE: RESPONSE_ERROR`. 7. Dispatch `response-verifier`. It must verify skipped/report-only reasons and follow-up warrants in addition to evidence, tone, actions, and posting safety. On `VERIFY: NEEDS_CONTEXT`, repair only the named context gap. On `VERIFY: FAIL`, repair only the named `Fix target`. Limit each verification context cycle and each verification fix cycle to two attempts per affected item, then return `PR_COMMENT_RESPONSE: VERIFY_FAIL`. Route `VERIFY: ERROR` to `PR_COMMENT_RESPONSE: RESPONSE_ERROR`. 8. Confirm the prevalidated `OUTPUT_FILE` is still known and safe. If it is no longer safe or resolved, return to the output-path question loop from step 1. Dispatch `response-report-writer` with the verified package and posting status `not-posted` or `pending-confirmation`; the writer reads back the file and reports whether the write matched the template. The orchestrator then performs a separate contract read-back for path, status blocks, drafts, evidence, skipped/report-only items, residual risks, blocking user-decision items, action intents, and posting status. Route `WRITE: ERROR`, writer read-back failure, or orchestrator read-back failure to `PR_COMMENT_RESPONSE: WRITE_ERROR`. 9. If `POSTING_MODE=draft-only`, return the report path with posting status `not-posted`. If `POSTING_MODE=post-after-confirmation`, build the exact final preview only for `reply-ready` and `follow-up-ready` supported targets, and dispatch `thread-reply-poster` only after explicit user approval. If preview construction or posting discovers an unsupported target in the poster package, run a targeted contract repair at most twice: remove that target from the poster package, preserve its `requires-user-choice:*` target and `unsupported-or-needs-user-choice` disposition in the report, and redispatch verification. If posting returns `POST: PREVIEW_REQUIRED`, rebuild and show the exact preview for approval again, with at most two posting-preview repair cycles before `PR_COMMENT_RESPONSE: NEEDS_USER_DECISION`. For `POST: PASS`, declined approval, auth failure, preview failure, or posting failure, redispatch `response-report-writer` to synchronize posting status, posted/skipped counts, terminal reason, and final envelope intent before emitting the terminal `PR_COMMENT_RESPONSE`. ## Output Contract The report path is `OUTPUT_FILE`. Load `./references/status-contracts.md` only when producing a phase status, failure envelope, final orchestrator response, or checking exact status vocabulary. Load `./references/report-template.md` only when writing or read-back checking the local report. Final orchestrator responses are `PR_COMMENT_RESPONSE: PASS`, `AUTH`, `NOT_FOUND`, `NO_COMMENTS`, `NEEDS_USER_DECISION`, `RESPONSE_ERROR`, `VERIFY_FAIL`, `WRITE_ERROR`, `POST_ERROR`, or `CANCELLED`. Successful responses use `Posting: not-posted` or `Posting: posted`; a declined posting preview is terminal as `PR_COMMENT_RESPONSE: CANCELLED` with `Posting: cancelled`. Any posting branch after report writing must synchronize the local report before the final envelope is emitted. ## Example Input: `PR_URL=https://github.com/org/repo/pull/123`, `POSTING_MODE=draft-only`. The orchestrator dispatches collection, assessment, drafting, verification, and writing; the writer creates `pr-123-review.md`; posting is skipped. Load `./references/status-examples.md` only when a concrete status example is needed.