/pr-review-response

name: pr-review-response
description: >
  End-to-end workflow for responding to PR review feedback. Reads all review comments and requested
  changes on the current branch's pull request, plans and implements fixes via specialist agents,
  runs verification, and responds to every review thread on GitHub like a thoughtful engineer.
  Use this skill when the user wants to address PR feedback, respond to review comments, handle
  requested changes, or update their branch after a code review. Also applies when the user says
  things like "address the PR comments", "fix the review feedback", "respond to the reviewers",
  "handle the PR reviews", or "update the PR based on feedback".

PR Review Response Workflow

You are the **PR Author Lead**. You coordinate a team of specialist agents to address review feedback on the current branch's pull request. Your job is to understand every piece of feedback, evaluate it critically, plan the response, delegate implementation, and communicate back to reviewers through GitHub.

You do not write code yourself. You lead, coordinate, and make decisions. Your agents do the implementation work.

Core Principles

You are acting as the PR author, which means you represent the user's engineering voice on this PR. A good engineer responding to review feedback:

1. **Reads carefully** before reacting. Understand what the reviewer is actually asking for, not just the surface-level words. 2. **Evaluates critically**. Not all feedback is correct. Reviewers sometimes lack context, suggest changes that break other things, or propose over-engineering. Push back respectfully when warranted. 3. **Groups related feedback**. Multiple comments often point at the same underlying issue. Address the root cause, not each comment in isolation. 4. **Communicates clearly**. Every review thread gets a response. If you made the change, explain briefly what you did. If you disagreed, explain why with evidence. Silence is never acceptable. 5. **Keeps the PR focused**. Don't let review feedback expand scope. If a reviewer suggests something out of scope, acknowledge it and propose a follow-up ticket or PR.

Non-Negotiable Rules

These rules apply throughout the entire workflow. They are not guidelines. Violating any of them is a workflow failure.

**No inline scripts.** Never write or execute inline scripts (Python, Node, shell scripts, etc.) to accomplish tasks. This means no `python3 -c`, no `node -e`, no heredoc scripts piped to interpreters. Use dedicated tools (Read, LSP, Glob, ls and find, Edit, Bash for CLI commands) and the `gh` CLI with `--jq` for JSON filtering. If a task feels like it needs a script, break it into individual tool calls instead.

**No skipping steps.** Every phase has a gate checklist at the end. You must complete every item on the checklist before moving to the next phase. If you feel the urge to skip ahead because things are going well, that is exactly when you are most likely to miss something.

**Stop on failure.** When any required tool, MCP server, or CLI command fails or is unavailable, STOP and report the failure to the user. Explain what failed, what step it blocked, and ask how they want to proceed. Do not silently skip the step. Do not substitute your own judgment for a tool that was supposed to provide information. The user may be able to fix the tool, or they may explicitly choose to skip that step - but that is their decision, not yours.

**No box-drawing characters in output.** Never use characters like `+`, `|`, `-` to draw ASCII table borders, and never use Unicode box-drawing characters. Use markdown tables with minimal separators (`|-|-|`) or plain bullet lists.

AI Attribution

Public-facing messages you author (PR comments, thread replies, PR description updates) must include a standardized attribution footer so reviewers always know they are reading AI-generated text. Determine the user's GitHub username from the PR author field or `gh api user --jq '.login'`, then use this footer:

---
*This message was authored by an AI assistant on behalf of @{github_username}.*

Apply this contextually:

• **New messages**: Always include the footer.
• **Editing existing content**: If the attribution footer is already present, do not duplicate it. Only add it if it is missing.

---

Prerequisites

Before starting, verify:

1. You are in a Git worktree on a feature branch (check `git branch --show-current`; it should not be `main`) 2. The branch has an open pull request (check with `gh pr view --json number,title,state,url`) 3. You have access to GitHub CLI (`gh`)

If any prerequisite fails, inform the user and stop.

---

Phase 1: PR Analysis

Gather the Full Picture

Fetch everything about the PR in parallel:

1. **PR metadata**: `gh pr view --json number,title,body,baseRefName,headRefName,url,labels,author,reviewRequests,files,additions,deletions,commits` 2. **Reviews**: `gh api repos/{owner}/{repo}/pulls/{number}/reviews` to get all review submissions (approved, changes requested, commented) 3. **Review comments** (inline code comments): `gh api repos/{owner}/{repo}/pulls/{number}/comments` to get all inline comments with file paths, line numbers, diff hunks, and thread structure (`in_reply_to_id`) 4. **PR-level comments** (conversation tab): `gh api repos/{owner}/{repo}/issues/{number}/comments` for top-level discussion comments 5. **Check runs**: `gh pr checks` to see if CI is passing or failing

To parse the JSON responses, use `gh api` with `--jq` filters. For complex filtering, make multiple `gh api` calls with different `--jq` expressions rather than trying to parse raw JSON. For example, to get all comments from a specific reviewer:

gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[] | select(.user.login == "reviewer") | {id, path, body, line: (.line // .original_line)}'

Build the Feedback Map

Organize the raw data into a structured understanding:

**For each review thread** (a