pr-review-resolver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Review Resolver

互動式解決 PR review comment 中的未解決問題。

重要原則：

永遠使用繁體中文（zh-TW） 與使用者溝通
逐一處理每個問題，不要批次處理
由使用者決定處理方式，不要自行決定

Interactively resolve unresolved issues in PR review comments.

Core Principles:

Always communicate with users in Traditional Chinese (zh-TW)
Process each issue one by one, do not batch process
Let the user decide on the handling method, do not make decisions autonomously

使用時機

Usage Scenarios

當需要：

處理 PR review 中的未解決問題
解決先前 review session 的回饋
在 merge 前完成剩餘任務
討論如何處理特定的 review 發現

Use when you need to:

Handle unresolved issues in PR reviews
Address feedback from previous review sessions
Complete remaining tasks before merging
Discuss how to handle specific review findings

工作流程

Workflow

步驟 1：取得 PR Review Comment（使用快取）

Step 1: Retrieve PR Review Comments (Using Cache)

首先取得 PR 編號（使用 branch-map 快取）：

bash

PR_NUMBER=$("${CLAUDE_PLUGIN_ROOT}/scripts/get-pr-number.sh")

此指令使用 branch-to-PR-number 快取（TTL 1 小時），快取未命中時才呼叫 GitHub API。

若無 PR，通知使用者並停止。

接著取得 review comment（使用本地快取）：

bash

REVIEW_CONTENT=$(${CLAUDE_PLUGIN_ROOT}/scripts/cache-read-comment.sh "$PR_NUMBER")

此指令會先檢查本地快取，若快取不存在則從 GitHub 取得並建立快取。

若找不到 review comment（exit code 2），通知使用者先執行

pr-review-and-document

skill。

First, get the PR number (using branch-map cache):

bash

PR_NUMBER=$("${CLAUDE_PLUGIN_ROOT}/scripts/get-pr-number.sh")

This command uses the branch-to-PR-number cache (TTL 1 hour), and only calls the GitHub API when the cache misses.

If there is no PR, notify the user and stop.

Next, retrieve review comments (using local cache):

bash

REVIEW_CONTENT=$(${CLAUDE_PLUGIN_ROOT}/scripts/cache-read-comment.sh "$PR_NUMBER")

This command first checks the local cache; if the cache does not exist, it retrieves from GitHub and creates the cache.

If no review comments are found (exit code 2), notify the user to run the

pr-review-and-document

skill first.

步驟 2：解析未解決項目

Step 2: Parse Unresolved Items

從 review comment 中識別所有未解決項目：

未解決指標：

```
⚠️
```
需要注意的項目（待處理）
```
🔴
```
阻擋性問題（必須在 merge 前解決）
表格中的
```
⚠️ Pending
```
狀態
沒有
```
✅
```
或
```
⏭️
```
前綴的 details summary
「Action Plan」中沒有完成標記
```
[x]
```
的任務

已解決指標：

```
✅
```
問題已解決（程式碼變更已完成）
```
⏭️
```
刻意延後或不適用（標記為 Deferred / N/A / Kept）
```
[x]
```
已勾選的 checkbox

Identify all unresolved items from the review comments:

Unresolved Indicators:

```
⚠️
```
Items needing attention (pending)
```
🔴
```
Blocking issues (must be resolved before merging)
```
⚠️ Pending
```
status in tables
Details summaries without
```
✅
```
or
```
⏭️
```
prefixes
Tasks in the "Action Plan" without completion mark
```
[x]
```

Resolved Indicators:

```
✅
```
Issue resolved (code changes completed)
```
⏭️
```
Deliberately deferred or not applicable (marked as Deferred / N/A / Kept)
```
[x]
```
Checked checkboxes

步驟 3：逐一處理每個項目（最重要！）

Step 3: Process Each Item One by One (Most Important!)

關鍵要求：一次討論一個項目，但修復以背景子任務並行執行，不阻塞討論流程。

對於 每一個 未解決項目，依序執行：

Key Requirement: Discuss one item at a time, but execute fixes as parallel background subtasks without blocking the discussion flow.

For each unresolved item, execute the following steps in order:

3.1 清楚呈現問題

3.1 Clearly Present the Issue

用繁體中文向使用者說明：

引用 review 中的問題描述
顯示 file:line 參考位置
解釋問題及其影響

Explain to the user in Traditional Chinese:

Quote the issue description from the review
Show file:line reference locations
Explain the issue and its impact

3.2 閱讀實際原始碼

3.2 Read the Actual Source Code

使用 Read 工具檢視被參考的檔案
驗證問題是否仍然存在
檢查是否已在最近的 commit 中修復

Use the Read tool to view the referenced file
Verify if the issue still exists
Check if it has been fixed in recent commits

3.3 與使用者討論（必要！）

3.3 Discuss with the User (Mandatory!)

這是最重要的步驟。必須：

用繁體中文解釋可能的解決方案
如果有多種方法，以選項形式呈現
使用 AskUserQuestion 工具或
```
<options>
```
讓使用者選擇
等待使用者決定後才能繼續

選項範例：

這個問題有幾種處理方式：

1. **修復** - [說明修復方法]
2. **延後** - [說明為何可以延後]
3. **標記為 N/A** - [說明為何不適用]

<options>
<option>修復這個問題</option>
<option>延後到下個 PR</option>
<option>標記為不適用 (N/A)</option>
</options>

This is the most important step. You must:

Explain possible solutions in Traditional Chinese
If there are multiple methods, present them as options
Use the AskUserQuestion tool or
```
<options>
```
to let the user choose
Wait for the user's decision before proceeding

Example options:

There are several ways to handle this issue:

1. **Fix** - [Explain the fix method]
2. **Defer** - [Explain why it can be deferred]
3. **Mark as N/A** - [Explain why it is not applicable]

<options>
<option>Fix this issue</option>
<option>Defer to next PR</option>
<option>Mark as not applicable (N/A)</option>
</options>

3.4 依使用者決定執行

3.4 Execute According to User's Decision

修復路徑：

確認目標檔案清單（從問題描述與原始碼分析中取得）
檢查檔案衝突——目標檔案是否與進行中的背景子任務重疊：
- 無衝突 → 立即啟動背景子任務
- 有衝突 → 通知使用者：「⏳ 目標檔案
```
{file}
```
  正在被子任務 {task_id}（{問題名稱}）修改中，等待完成後再啟動。」使用
```
TaskOutput
```
  等待衝突子任務完成，然後再啟動新子任務
用 Task tool（
```
run_in_background: true
```
）啟動背景子任務，prompt 必須包含：
- 完整的問題描述（從 review comment 引用）
- 目標檔案路徑與行號
- 使用者選擇的修復方案
- 足夠的 context 讓子任務可獨立執行（不依賴主對話）
將子任務加入追蹤清單（在記憶體中維護）：
```
{ task_id, 問題名稱, 目標檔案列表 }
```
記錄暫定狀態
```
🔧 修復中
```

延後 / N/A 路徑（inline 處理，不需子任務）：

若使用者選擇延後：記錄狀態為
```
⏭️ Deferred
```
，加上原因
若使用者選擇 標記 N/A：記錄狀態為
```
⏭️ N/A
```
，加上說明

Fix Path:

Confirm the target file list (obtained from issue description and source code analysis)
Check for file conflicts - whether the target files overlap with ongoing background subtasks:
- No conflict → Immediately start the background subtask
- Conflict exists → Notify the user: "⏳ Target file
```
{file}
```
  is being modified by subtask {task_id} ({issue name}), waiting for completion before starting." Use
```
TaskOutput
```
  to wait for the conflicting subtask to complete, then start the new subtask
Use the Task tool (
```
run_in_background: true
```
) to start the background subtask. The prompt must include:
- Complete issue description (quoted from review comments)
- Target file path and line numbers
- The fix solution chosen by the user
- Sufficient context for the subtask to execute independently (without relying on the main conversation)
Add the subtask to the tracking list (maintained in memory):
```
{ task_id, issue name, target file list }
```
Record the tentative status
```
🔧 In Progress
```

Defer / N/A Path (handled inline, no subtask needed):

If the user chooses Defer: Record status as
```
⏭️ Deferred
```
, plus the reason
If the user chooses Mark as N/A: Record status as
```
⏭️ N/A
```
, plus the explanation

3.5 在原始碼中記錄決策

3.5 Record Decisions in Source Code

對於標記為 N/A 或 Deferred 的項目，在相關原始碼中加入註解：

註解格式：

// Design Decision: [完整原因，直接在註解中說明清楚]

不要使用
@see PR #N
或任何外部參考——所有脈絡必須自包含在註解內
這可防止相同問題在未來的 review 中再次出現，且不依賴外部連結

For items marked as N/A or Deferred, add comments in the relevant source code:

Comment format:

// Design Decision: [Full reason, clearly explained directly in the comment]

Do not use
@see PR #N
or any external references - all context must be self-contained in the comment
This prevents the same issue from reappearing in future reviews and does not rely on external links

3.6 自動繼續下一個項目

3.6 Automatically Proceed to the Next Item

決策記錄完成後，不需等待修復子任務完成，直接告知使用者：

「✓ 已記錄。接下來看下一個問題（{current}/{total}）。」

然後立即進入下一個項目的 3.1 步驟。

After recording the decision, do not wait for the fix subtask to complete, directly inform the user:

"✓ Recorded. Moving on to the next issue ({current}/{total})."

Then immediately proceed to step 3.1 for the next item.

3.7 等待並驗收所有子任務

3.7 Wait for and Accept All Subtasks

所有項目討論完畢後，執行驗收流程：

顯示進度總覽：

📊 處理總覽：
- 🔧 修復中：N 個（背景子任務進行中）
- ⏭️ 延後：N 個
- ⏭️ N/A：N 個

逐一收集子任務結果：

使用
```
TaskOutput
```
讀取每個背景子任務的輸出
成功 → 更新狀態為
```
✅ Fixed
```

失敗 → 向使用者報告錯誤，提供選項：

<options>
<option>重試修復</option>
<option>延後到下個 PR</option>
<option>標記為不適用 (N/A)</option>
</options>

驗證無非預期重疊修改：
bash
```
git diff --name-only
```
確認修改的檔案都在預期範圍內，若有非預期檔案變更，通知使用者確認。

呈現最終結果表格：

| # | 問題 | 決策 | 狀態 |
|---|------|------|------|
| 1 | Silent Cart Failure | 修復 | ✅ Fixed |
| 2 | Missing Error Boundary | 延後 | ⏭️ Deferred |
| 3 | Unused Import | N/A | ⏭️ N/A |

After discussing all items, execute the acceptance process:

Show Progress Overview:

📊 Processing Overview:
- 🔧 In Progress: N items (background subtasks ongoing)
- ⏭️ Deferred: N items
- ⏭️ N/A: N items

Collect Subtask Results One by One:
- Use
```
TaskOutput
```
  to read the output of each background subtask
- Success → Update status to
```
✅ Fixed
```
- Failure → Report the error to the user and provide options:
```
<options>
<option>Retry fix</option>
<option>Defer to next PR</option>
<option>Mark as not applicable (N/A)</option>
</options>
```
Verify No Unexpected Overlapping Changes:
bash
```
git diff --name-only
```
Confirm that all modified files are within the expected range. If there are unexpected file changes, notify the user to confirm.

Present Final Results Table:

| # | Issue | Decision | Status |
|---|------|------|------|
| 1 | Silent Cart Failure | Fix | ✅ Fixed |
| 2 | Missing Error Boundary | Defer | ⏭️ Deferred |
| 3 | Unused Import | N/A | ⏭️ N/A |

步驟 4：更新 Review Comment

Step 4: Update Review Comments

前提條件：步驟 3.7 驗收完成後才執行此步驟。

⚠️ 警告：必須使用快取腳本！
更新 PR review comment 時，務必使用
cache-write-comment.sh
腳本，絕對不要直接使用
gh api
指令。呼叫時不要使用
--local-only
旗標，否則只會更新本地快取而不同步 GitHub。
直接使用
gh api
會導致本地快取與 GitHub 永久不同步——comment 內容快取沒有 TTL（與 branch-map 快取的 1 小時 TTL 不同），不會自動過期，所有後續
cache-read-comment.sh
讀取都會拿到過期資料，直到下一次
cache-write-comment.sh
或
cache-read-comment.sh --force-refresh
才會修正。

更新 PR review comment：

準備更新後的內容：
- 更新各項目的狀態指標
- 更新 Summary 表格的計數
- 更新 metadata 中的
```
updated_at
```
  和 issues 計數
- 將 Status 更新為適當狀態
透過
```
--stdin
```
將更新內容直接寫入本地快取並同步至 GitHub：

bash

echo "$UPDATED_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"

腳本會自動：

將內容寫入本地快取（
```
.pr-review-cache/pr-${PR_NUMBER}.json
```
）
嘗試同步至 GitHub（自動重試最多 3 次）
成功後更新快取中的 comment ID
使用 atomic write（先寫入
```
.tmp
```
再
```
mv
```
）避免寫入中斷造成損壞

Exit codes：

```
0
```
= 成功（本地快取 + GitHub 都已更新）
```
1
```
= GitHub 同步失敗（本地快取是最新的，可用
```
/push-review-cache
```
重試）
```
2
```
= 本地錯誤（如找不到 PR、內容為空）

若同步失敗，通知使用者：
- 本地快取已安全保存（
```
.pr-review-cache/pr-${PR_NUMBER}.json
```
  ）
- 使用者可稍後執行
```
/push-review-cache
```
  command 完成同步

Prerequisite: Execute this step only after completing step 3.7 acceptance.

⚠️ Warning: Must use cache scripts!
When updating PR review comments, always use the
cache-write-comment.sh
script, never directly use the
gh api
command. Do not use the
--local-only
flag when calling, otherwise only the local cache will be updated without syncing to GitHub.
Directly using
gh api
will cause permanent desynchronization between the local cache and GitHub - the comment content cache has no TTL (unlike the branch-map cache's 1-hour TTL) and will not automatically expire. All subsequent
cache-read-comment.sh
reads will get outdated data until the next
cache-write-comment.sh
or
cache-read-comment.sh --force-refresh
is executed.

Update PR review comments:

Prepare updated content:
- Update status indicators for each item
- Update counts in the Summary table
- Update
```
updated_at
```
  and issue counts in metadata
- Update Status to the appropriate state
Write the updated content directly to the local cache and sync to GitHub via
```
--stdin
```
:

bash

echo "$UPDATED_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"

The script will automatically:

Write the content to the local cache (
```
.pr-review-cache/pr-${PR_NUMBER}.json
```
)
Attempt to sync to GitHub (automatic retry up to 3 times)
Update the comment ID in the cache after success
Use atomic write (write to
```
.tmp
```
first then
```
mv
```
) to avoid corruption from interrupted writes

Exit codes:

```
0
```
= Success (both local cache and GitHub updated)
```
1
```
= GitHub sync failed (local cache is up to date, use
```
/push-review-cache
```
to retry)
```
2
```
= Local error (e.g., PR not found, empty content)

If sync fails, notify the user:
- The local cache has been safely saved (
```
.pr-review-cache/pr-${PR_NUMBER}.json
```
  )
- The user can later run the
```
/push-review-cache
```
  command to complete the sync

步驟 5：知識萃取（所有項目完成後）

Step 5: Knowledge Extraction (After All Items Completed)

當所有項目都解決後，分析此次 session 的學習：

識別模式：
- 適用於多個檔案的決策
- 新建立的慣例
- 對現有指南的澄清
檢查是否需要更新 CLAUDE.md：
- 是否有決策澄清了模糊的指南？
- 是否建立了應該記錄的新模式？
- 是否發現了缺少的指南參考？
必要時建立文件：
- 將新指南加入適當的
```
docs/
```
  檔案
- 用漸進式揭露方式更新 CLAUDE.md
- 格式：CLAUDE.md 中放簡要摘要，docs/ 中放完整詳情
更新 review comment：
- 在最後加入「Knowledge Extracted」章節
- 列出任何建立或更新的指南
- 參考文件變更

When all items are resolved, analyze learnings from this session:

Identify Patterns:
- Decisions applicable to multiple files
- Newly established conventions
- Clarifications to existing guidelines
Check if CLAUDE.md Needs Update:
- Did any decision clarify ambiguous guidelines?
- Was a new pattern established that should be documented?
- Were missing guideline references discovered?
Create Documentation if Necessary:
- Add new guidelines to appropriate
```
docs/
```
  files
- Update CLAUDE.md using progressive disclosure
- Format: Place a brief summary in CLAUDE.md, with full details in docs/
Update Review Comments:
- Add a "Knowledge Extracted" section at the end
- List any guidelines created or updated
- Reference document changes

決策記錄格式

Decision Recording Format

標記項目為 N/A 或 Deferred 時，在原始碼中加入註解：

typescript

// Design Decision: [決策的完整原因，直接說明清楚]
// Rationale: [如需要，更詳細的說明]

範例：

typescript

// Design Decision: 為可讀性保留明確的 null 檢查
// Rationale: 抽象成 helper 會降低清晰度，收益不大；此處的明確檢查讓維護者一眼就能理解邊界條件

When marking items as N/A or Deferred, add comments in the source code:

typescript

// Design Decision: [Full reason for the decision, clearly explained directly]
// Rationale: [More detailed explanation if needed]

Example:

typescript

// Design Decision: Keep explicit null checks for readability
// Rationale: Abstracting into a helper would reduce clarity with little benefit; the explicit check here lets maintainers understand boundary conditions at a glance

狀態指標

Status Indicators

更新 review 時使用一致的狀態指標：

指標	意義	使用時機
✅	問題已解決	程式碼變更已完成並驗證
⏭️	刻意延後或不適用	將在未來處理或設計考量
⚠️	需要注意	仍需處理
🔴	阻擋性問題	必須在 merge 前解決

Use consistent status indicators when updating reviews:

Indicator	Meaning	Usage Scenario
✅	Issue resolved	Code changes completed and verified
⏭️	Deliberately deferred or not applicable	Will be handled in the future or due to design considerations
⚠️	Needs attention	Still requires handling
🔴	Blocking issue	Must be resolved before merging

知識萃取標準

Knowledge Extraction Standards

評估每個已解決項目是否需要知識萃取：

決策類型	萃取到 CLAUDE.md？	範例
一次性修復	否	錯字修正、簡單 bug
模式澄清	是	「日期排序使用 localeCompare」
新慣例	是	「所有 response DTO 使用 snake_case」
指南例外	是	「CMS 錯誤使用優雅降級」
工具偏好	是	「條件式 className 使用 clsx」

Evaluate whether each resolved item requires knowledge extraction:

Decision Type	Extract to CLAUDE.md?	Example
One-time fix	No	Typo correction, simple bug fix
Pattern clarification	Yes	"Use localeCompare for date sorting"
New convention	Yes	"All response DTOs use snake_case"
Guideline exception	Yes	"Graceful degradation for CMS errors"
Tool preference	Yes	"Use clsx for conditional className"

CLAUDE.md 更新格式

CLAUDE.md Update Format

萃取知識時，遵循漸進式揭露：

在 CLAUDE.md 中（簡要參考）：

markdown

undefined

When extracting knowledge, follow progressive disclosure:

In CLAUDE.md (brief reference):

markdown

undefined

[類別] 指南

[Category] Guidelines

詳見

docs/[guideline-file].md

。

核心原則：[一句話摘要]

必須參考的情境：

[觸發情境 1]
[觸發情境 2]


**在 docs/ 中（完整詳情）：**
```markdown

See

docs/[guideline-file].md

for details.

Core Principle: [One-sentence summary]

Mandatory Reference Scenarios:

[Trigger scenario 1]
[Trigger scenario 2]


**In docs/ (full details):**
```markdown

[指南標題]

[Guideline Title]

背景

Background

[為何需要此指南]

[Why this guideline is needed]

模式

Pattern

[帶範例的詳細說明]

[Detailed explanation with examples]

使用時機

Usage Scenarios

[適用的情境]

[Applicable scenarios]

例外

Exceptions

[不適用的情況]

undefined

[Scenarios where it does not apply]

undefined

驗證清單

Verification Checklist

互動範例

Interaction Example

完整互動範例（含並行背景子任務的正確流程）在

references/interaction-example.md

。在開始逐一處理問題前，先讀取此範例以確保互動流程正確。

A complete interaction example (including correct flow for parallel background subtasks) is available in

references/interaction-example.md

. Read this example before starting to process issues one by one to ensure correct interaction flow.

無 PR 或無 Review Comment 的處理

Handling No PR or No Review Comments

無 PR：通知使用者先建立 PR（
```
gh pr create
```
）
無 Review Comment：通知使用者先執行
```
pr-review-and-document
```
skill 產生 review

No PR: Notify the user to create a PR first (
```
gh pr create
```
)
No Review Comments: Notify the user to run the
```
pr-review-and-document
```
skill first to generate a review

常見錯誤

Common Errors

❌ 直接使用

gh api

更新 comment

❌ Directly using

gh api

to update comments

bash

undefined

bash

undefined

錯誤做法 - 永遠不要這樣做！

Wrong approach - never do this!

gh api repos/{owner}/{repo}/issues/comments/${COMMENT_ID} -X PATCH -f body="..."


這會導致本地快取與 GitHub 永久不同步。正確做法及錯誤恢復方式請參考**步驟 4：更新 Review Comment** 中的警告。

gh api repos/{owner}/{repo}/issues/comments/${COMMENT_ID} -X PATCH -f body="..."


This will cause permanent desynchronization between the local cache and GitHub. For the correct approach and error recovery methods, refer to the warning in **Step 4: Update Review Comments**.