resolve-pr-feedback

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Resolve PR Review Feedback

处理PR评审反馈

Evaluate and fix PR review feedback, then reply and resolve threads. Spawns parallel agents for each thread.

Agent time is cheap. Tech debt is expensive. Fix everything valid -- including nitpicks and low-priority items. If we're already in the code, fix it rather than punt it.

评估并修复PR评审反馈，然后回复并解决评审线程。为每个线程生成并行Agent。

Agent的时间成本很低，技术债务的代价很高。 修复所有有效的反馈——包括细节挑剔和低优先级的问题。既然我们已经在处理这段代码，就直接修复，不要往后拖。

Mode Detection

模式检测

Argument	Mode
No argument	Full -- all unresolved threads on the current branch's PR
PR number (e.g., `123` )	Full -- all unresolved threads on that PR
Comment/thread URL	Targeted -- only that specific thread

Targeted mode: When a URL is provided, ONLY address that feedback. Do not fetch or process other threads.

参数	模式
无参数	完整模式——当前分支PR上的所有未解决线程
PR编号（例如： `123` ）	完整模式——该PR上的所有未解决线程
评论/线程URL	目标模式——仅处理该特定线程

目标模式：当提供URL时，仅处理该条反馈。不要获取或处理其他线程。

Full Mode

完整模式

1. Fetch Unresolved Threads

1. 获取未解决线程

If no PR number was provided, detect from the current branch:

bash

gh pr view --json number -q .number

Then fetch all feedback using the GraphQL script at scripts/get-pr-comments:

bash

bash scripts/get-pr-comments PR_NUMBER

Returns a JSON object with three keys:

Key	Contents	Has file/line?	Resolvable?
`review_threads`	Unresolved, non-outdated inline code review threads	Yes	Yes (GraphQL)
`pr_comments`	Top-level PR conversation comments (excludes PR author)	No	No
`review_bodies`	Review submission bodies with non-empty text (excludes PR author)	No	No

If the script fails, fall back to:

bash

gh pr view PR_NUMBER --json reviews,comments
gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments

如果未提供PR编号，则从当前分支自动检测：

bash

gh pr view --json number -q .number

然后使用位于scripts/get-pr-comments的GraphQL脚本获取所有反馈：

bash

bash scripts/get-pr-comments PR_NUMBER

返回一个包含三个键的JSON对象：

键名	内容	包含文件/行号？	可解决？
`review_threads`	未解决、未过时的内联代码评审线程	是	是（GraphQL）
`pr_comments`	PR顶层对话评论（排除PR作者）	否	否
`review_bodies`	包含非空文本的评审提交内容（排除PR作者）	否	否

如果脚本执行失败，使用备用方案：

bash

gh pr view PR_NUMBER --json reviews,comments
gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments

2. Triage: Separate New from Pending

2. 分类：区分新反馈与待处理反馈

Before processing, classify each piece of feedback as new or already handled.

Review threads: Read the thread's comments. If there's a substantive reply that acknowledges the concern but defers action (e.g., "need to align on this", "going to think through this", or a reply that presents options without resolving), it's a pending decision -- don't re-process. If there's only the original reviewer comment(s) with no substantive response, it's new.

PR comments and review bodies: These have no resolve mechanism, so they reappear on every run. Check the PR conversation for an existing reply that quotes and addresses the feedback. If a reply already exists, skip. If not, it's new.

The distinction is about content, not who posted what. A deferral from a teammate, a previous skill run, or a manual reply all count.

If there are no new items across all feedback types, skip steps 3-7 and go straight to step 8.

处理前，将每条反馈分类为新反馈或已处理反馈。

评审线程：读取线程中的所有评论。如果存在实质性回复，确认了问题但推迟了处理（例如：“需要对此达成一致”、“我会仔细考虑”，或提出了选项但未解决问题的回复），则属于待决策——不要重新处理。如果只有评审者的原始评论而无实质性回复，则属于新反馈。

PR评论和评审提交内容：这些内容没有内置的解决机制，因此每次运行都会重新出现。检查PR对话中是否存在引用并处理该反馈的回复。如果已有回复，则跳过；如果没有，则属于新反馈。

分类的依据是内容，而非回复者身份。无论是队友的推迟回复、之前的Skill运行结果还是手动回复，都算作已处理。

如果所有类型的反馈中都没有新项，则跳过步骤3-7，直接进入步骤8。

3. Plan

3. 制定计划

Create a task list of all new unresolved items grouped by type (e.g.,

TaskCreate

in Claude Code,

update_plan

in Codex):

Code changes requested
Questions to answer
Style/convention fixes
Test additions needed

创建所有新未解决项的任务列表，按类型分组（例如Claude Code中的

TaskCreate

、Codex中的

update_plan

）：

要求修改的代码变更
需要回答的问题
风格/规范修复
需要添加的测试

4. Implement (PARALLEL)

4. 执行（并行）

Process all three feedback types. Review threads are the primary type; PR comments and review bodies are secondary but should not be ignored.

For review threads (

review_threads

): Spawn a

compound-engineering:workflow:pr-comment-resolver

agent for each.

Each agent receives:

The thread ID
The file path and line number
The full comment text (all comments in the thread)
The PR number (for context)
The feedback type (
```
review_thread
```
)

For PR comments and review bodies (

pr_comments

review_bodies

): These lack file/line context. Spawn a

compound-engineering:workflow:pr-comment-resolver

agent for each actionable item. The agent receives the comment ID, body text, PR number, and feedback type (

pr_comment

review_body

). The agent must identify the relevant files from the comment text and the PR diff.

Each agent returns a short summary:

verdict:

fixed

fixed-differently

replied

not-addressing

, or

needs-human

feedback_id: the thread ID or comment ID it handled
feedback_type:
```
review_thread
```
,
```
pr_comment
```
, or
```
review_body
```
reply_text: the markdown reply to post (quoting the relevant part of the original feedback)
files_changed: list of files modified (empty if replied/not-addressing)
reason: brief explanation of what was done or why it was skipped

Verdict meanings:

```
fixed
```
-- code change made as requested
```
fixed-differently
```
-- code change made, but with a better approach than suggested
```
replied
```
-- no code change needed; answered a question, acknowledged feedback, or explained a design decision
```
not-addressing
```
-- feedback is factually wrong about the code; skip with evidence
```
needs-human
```
-- cannot determine the right action; needs user decision

Batching: If there are 1-4 items total, dispatch all in parallel. For 5+ items, batch in groups of 4.

Conflict avoidance: If multiple threads reference the same file, group them into a single agent dispatch to avoid parallel edit conflicts. The agent handling a multi-thread file receives all threads for that file and addresses them sequentially.

Fixes can occasionally expand beyond their referenced file (e.g., renaming a method updates callers elsewhere). This is rare but can cause parallel agents to collide. The verification step (step 7) catches this -- if re-fetching shows unresolved threads or if the commit reveals inconsistent changes, re-run the affected agents sequentially.

Platforms that do not support parallel dispatch should run agents sequentially.

处理所有三种类型的反馈。评审线程是主要类型；PR评论和评审提交内容是次要类型，但也不应被忽略。

针对评审线程（

review_threads

）：为每个线程生成一个

compound-engineering:workflow:pr-comment-resolver

Agent。

每个Agent会收到以下信息：

线程ID
文件路径和行号
完整的评论文本（线程中的所有评论）
PR编号（用于上下文）
反馈类型（
```
review_thread
```
）

针对PR评论和评审提交内容（

pr_comments

、

review_bodies

）：这些内容缺少文件/行上下文。为每个可操作项生成一个

compound-engineering:workflow:pr-comment-resolver

Agent。Agent会收到评论ID、正文文本、PR编号和反馈类型（

pr_comment

或

review_body

）。Agent必须从评论文本和PR差异中识别相关文件。

每个Agent会返回一个简短摘要：

verdict：

fixed

、

fixed-differently

、

replied

、

not-addressing

或

needs-human

feedback_id：处理的线程ID或评论ID
feedback_type：
```
review_thread
```
、
```
pr_comment
```
或
```
review_body
```
reply_text：要发布的Markdown回复（引用原始反馈的相关部分）
files_changed：修改的文件列表（如果是回复/未处理则为空）
reason：所做操作或跳过原因的简要说明

Verdict含义：

```
fixed
```
—— 按要求完成代码变更
```
fixed-differently
```
—— 完成了代码变更，但使用了比建议更好的方案
```
replied
```
—— 无需代码变更；已回答问题、确认反馈或解释设计决策
```
not-addressing
```
—— 反馈对代码的描述与事实不符；附上证据后跳过
```
needs-human
```
—— 无法确定正确操作；需要用户决策

批量处理：如果总共有1-4个项，则并行调度所有Agent。如果有5个及以上项，则按4个一组分批处理。

冲突避免：如果多个线程引用同一个文件，则将它们分组到同一个Agent调度中，以避免并行编辑冲突。处理多线程文件的Agent会收到该文件的所有线程，并按顺序处理。

修复操作有时可能超出引用文件的范围（例如：重命名方法会更新其他地方的调用者）。这种情况很少见，但可能导致并行Agent冲突。验证步骤（步骤7）会捕获此类问题——如果重新获取反馈显示仍有未解决线程，或者提交的变更不一致，则重新运行受影响的Agent（按顺序执行）。

不支持并行调度的平台应按顺序运行Agent。

5. Commit and Push

5. 提交并推送

After all agents complete, check whether any files were actually changed. If all verdicts are

replied

not-addressing

, or

needs-human

(no code changes), skip this step entirely and proceed to step 6.

If there are file changes:

Stage only files reported by sub-agents and commit with a message referencing the PR:

bash

git add [files from agent summaries]
git commit -m "Address PR review feedback (#PR_NUMBER)

- [list changes from agent summaries]"

Push to remote:

bash

git push

所有Agent完成后，检查是否有文件实际被修改。如果所有verdict都是

replied

、

not-addressing

或

needs-human

（无代码变更），则完全跳过此步骤，直接进入步骤6。

如果有文件变更：

仅暂存子Agent报告的文件，并使用引用PR的消息提交：

bash

git add [来自Agent摘要的文件]
git commit -m "处理PR评审反馈 (#PR_NUMBER)

- [来自Agent摘要的变更列表]"

推送到远程仓库：

bash

git push

6. Reply and Resolve

6. 回复并解决

After the push succeeds, post replies and resolve where applicable. The mechanism depends on the feedback type.

推送成功后，发布回复并在适用时解决线程。具体机制取决于反馈类型。

Reply format

回复格式

All replies should quote the relevant part of the original feedback for continuity. Quote the specific sentence or passage being addressed, not the entire comment if it's long.

For fixed items:

markdown

> [quoted relevant part of original feedback]

Addressed: [brief description of the fix]

For items not addressed:

markdown

> [quoted relevant part of original feedback]

Not addressing: [reason with evidence, e.g., "null check already exists at line 85"]

For

needs-human

verdicts, post the reply but do NOT resolve the thread. Leave it open for human input.

所有回复都应引用原始反馈的相关部分以保证连贯性。如果评论较长，仅引用被处理的特定句子或段落，而非整个评论。

针对已修复的项：

markdown

> [引用原始反馈的相关部分]

已处理：[修复内容的简要说明]

针对未处理的项：

markdown

> [引用原始反馈的相关部分]

未处理：[附上证据的原因说明，例如：“第85行已存在空值检查”]

对于

needs-human

的verdict，发布回复但不要解决线程，保持线程开放以等待用户输入。

Review threads

评审线程

Reply using scripts/reply-to-pr-thread:

bash

echo "REPLY_TEXT" | bash scripts/reply-to-pr-thread THREAD_ID

Resolve using scripts/resolve-pr-thread:

bash

bash scripts/resolve-pr-thread THREAD_ID

回复使用scripts/reply-to-pr-thread：

bash

echo "REPLY_TEXT" | bash scripts/reply-to-pr-thread THREAD_ID

解决使用scripts/resolve-pr-thread：

bash

bash scripts/resolve-pr-thread THREAD_ID

PR comments and review bodies

PR评论和评审提交内容

These cannot be resolved via GitHub's API. Reply with a top-level PR comment referencing the original:

bash

gh pr comment PR_NUMBER --body "REPLY_TEXT"

Include enough quoted context in the reply so the reader can follow which comment is being addressed without scrolling.

这些内容无法通过GitHub API解决。发布顶层PR评论并引用原始内容：

bash

gh pr comment PR_NUMBER --body "REPLY_TEXT"

回复中应包含足够的引用上下文，以便读者无需滚动即可明确正在处理哪条评论。

7. Verify

7. 验证

Re-fetch feedback to confirm resolution:

bash

bash scripts/get-pr-comments PR_NUMBER

The

review_threads

array should be empty (except

needs-human

items). If threads remain, repeat from step 1 for the remaining threads.

PR comments and review bodies have no resolve mechanism, so they will still appear in the output. Verify they were replied to by checking the PR conversation.

重新获取反馈以确认问题已解决：

bash

bash scripts/get-pr-comments PR_NUMBER

review_threads

数组应为空（

needs-human

项除外）。如果仍有线程未解决，则针对剩余线程重复步骤1。

PR评论和评审提交内容没有解决机制，因此仍会出现在输出中。通过检查PR对话来确认已回复这些内容。

8. Summary

8. 总结

Present a concise summary of all work done. Group by verdict, one line per item describing what was done not just where. This is the primary output the user sees.

Format:

Resolved N of M new items on PR #NUMBER:

Fixed (count): [brief description of each fix]
Fixed differently (count): [what was changed and why the approach differed]
Replied (count): [what questions were answered]
Not addressing (count): [what was skipped and why]

If any agent returned

needs-human

, append a decisions section. These are rare but high-signal. Each

needs-human

agent returns a

decision_context

field with a structured analysis: what the reviewer said, what the agent investigated, why it needs a decision, concrete options with tradeoffs, and the agent's lean if it has one.

Present the

decision_context

directly -- it's already structured for the user to read and decide quickly:

Needs your input (count):

1. [decision_context from the agent -- includes quoted feedback,
   investigation findings, why it needs a decision, options with
   tradeoffs, and the agent's recommendation if any]

The

needs-human

threads already have a natural-sounding acknowledgment reply posted and remain open on the PR.

If there are pending decisions from a previous run (threads detected in step 2 as already responded to but still unresolved), surface them after the new work:

Still pending from a previous run (count):

1. [Thread path:line] -- [brief description of what's pending]
   Previous reply: [link to the existing reply]
   [Re-present the decision options if the original context is available,
   or summarize what was asked]

If a blocking question tool is available, use it to ask about all pending decisions (both new

needs-human

and previous-run pending) together. If there are only pending decisions and no new work was done, the summary is just the pending items.

If a blocking question tool is available (

AskUserQuestion

in Claude Code,

request_user_input

in Codex,

ask_user

in Gemini), use it to present the decisions and wait for the user's response. After they decide, process the remaining items: fix the code, compose the reply, post it, and resolve the thread.

If no question tool is available, present the decisions in the summary output and wait for the user to respond in conversation. If they don't respond, the items remain open on the PR for later handling.

呈现所有完成工作的简明摘要。按verdict分组，每行描述所做工作而非仅说明位置。这是用户看到的主要输出。

格式：

已解决PR #NUMBER中M个新项中的N个：

已修复（数量）：[每个修复的简要说明]
已修复（替代方案）（数量）：[变更内容及方案不同的原因]
已回复（数量）：[已回答的问题]
未处理（数量）：[跳过的内容及原因]

如果有Agent返回

needs-human

，则追加决策部分。此类情况很少见，但信号性强。每个

needs-human

Agent会返回

decision_context

字段，包含结构化分析：评审者的意见、Agent的调查内容、需要决策的原因、带有权衡的具体选项，以及Agent的倾向（如果有的话）。

直接呈现

decision_context

——它已经过结构化处理，便于用户快速阅读和决策：

需要您的输入（数量）：

1. [来自Agent的decision_context——包括引用的反馈、
   调查结果、需要决策的原因、带有权衡的选项，
   以及Agent的建议（如果有）]

needs-human

线程已发布自然的确认回复，并在PR上保持开放状态。

如果存在之前运行中未解决的待决策项（步骤2中检测到的已回复但仍未解决的线程），则在新工作的摘要之后列出这些项：

之前运行中仍待处理的项（数量）：

1. [线程路径:行号] —— [待处理内容的简要说明]
   之前的回复：[现有回复的链接]
   [如果原始上下文可用，则重新呈现决策选项，
   或总结之前的问题]

如果有可用的阻塞式提问工具（如Claude Code中的

AskUserQuestion

、Codex中的

request_user_input

、Gemini中的

ask_user

），则使用它一次性询问所有待决策项（包括新的

needs-human

项和之前运行的待决策项）。如果只有待决策项而无新工作，则摘要仅包含待决策项。

如果没有可用的提问工具，则在摘要输出中呈现决策内容并等待用户在对话中回复。如果用户未回复，则这些项会在PR上保持开放状态，供后续处理。

Targeted Mode

目标模式

When a specific comment or thread URL is provided:

当提供特定评论或线程URL时：

1. Extract Thread Context

1. 提取线程上下文

Parse the URL to extract OWNER, REPO, PR number, and comment REST ID:

https://github.com/OWNER/REPO/pull/NUMBER#discussion_rCOMMENT_ID

Step 1 -- Get comment details and GraphQL node ID via REST (cheap, single comment):

bash

gh api repos/OWNER/REPO/pulls/comments/COMMENT_ID \
  --jq '{node_id, path, line, body}'

Step 2 -- Map comment to its thread ID. Use scripts/get-thread-for-comment:

bash

bash scripts/get-thread-for-comment PR_NUMBER COMMENT_NODE_ID [OWNER/REPO]

This fetches thread IDs and their first comment IDs (minimal fields, no bodies) and returns the matching thread with full comment details.

解析URL以提取OWNER、REPO、PR编号和评论REST ID：

https://github.com/OWNER/REPO/pull/NUMBER#discussion_rCOMMENT_ID

步骤1 —— 通过REST API获取评论详情和GraphQL节点ID（轻量操作，仅获取单条评论）：

bash

gh api repos/OWNER/REPO/pulls/comments/COMMENT_ID \\
  --jq '{node_id, path, line, body}'

步骤2 —— 将评论映射到其线程ID。使用scripts/get-thread-for-comment：

bash

bash scripts/get-thread-for-comment PR_NUMBER COMMENT_NODE_ID [OWNER/REPO]

该脚本会获取线程ID及其第一条评论ID（仅获取必要字段，不包含正文），并返回匹配的线程及完整评论详情。

2. Fix, Reply, Resolve

2. 修复、回复并解决

Spawn a single

compound-engineering:workflow:pr-comment-resolver

agent for the thread. Then follow the same commit -> push -> reply -> resolve flow as Full Mode steps 5-6.

为该线程生成一个

compound-engineering:workflow:pr-comment-resolver

Agent。然后遵循完整模式中步骤5-6的提交→推送→回复→解决流程。

Scripts

脚本

scripts/get-pr-comments -- GraphQL query for unresolved review threads
scripts/get-thread-for-comment -- Map a comment node ID to its parent thread (for targeted mode)
scripts/reply-to-pr-thread -- GraphQL mutation to reply within a review thread
scripts/resolve-pr-thread -- GraphQL mutation to resolve a thread by ID

scripts/get-pr-comments —— 获取未解决评审线程的GraphQL查询脚本
scripts/get-thread-for-comment —— 将评论节点ID映射到其父线程（用于目标模式）
scripts/reply-to-pr-thread —— 在评审线程中回复的GraphQL变更脚本
scripts/resolve-pr-thread —— 通过ID解决线程的GraphQL变更脚本

Success Criteria

成功标准

All unresolved review threads evaluated
Valid fixes committed and pushed
Each thread replied to with quoted context
Threads resolved via GraphQL (except
```
needs-human
```
)
Empty result from get-pr-comments on verify (minus intentionally-open threads)

所有未解决的评审线程均已评估
有效的修复已提交并推送
每个线程都有带引用上下文的回复
线程已通过GraphQL解决（
```
needs-human
```
项除外）
验证时get-pr-comments返回空结果（故意保持开放的线程除外）",