SuperAPI AI Directory

pr-review-resolver

General & other

View repository

Updated 10-15 22:39

About this skill

PR Review Resolver

Interactively resolve unresolved issues in PR review comments.

Important principles:

  1. Always use Traditional Chinese (zh-TW) to communicate with the user
  2. Handle one by oneeach issue, do not batch process
  3. Let the user decidethe handling approach, do not decide on your own

When to use

When you need to:

  • Handle unresolved issues in PR review
  • Resolve feedback from a previous review session
  • Complete remaining tasks before merge
  • Discuss how to handle specific review findings

Workflow

Step 1: Get PR Review Comment (using cache)

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

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 on a cache miss.

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

Then get the review comment (using local cache):

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

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

If no review comment is found (exit code 2), notify the user to first run pr-review-and-document skill。

Step 2: Parse unresolved items

Identify all unresolved items from the review comment:

Unresolved indicators:

  • ⚠️ Items that need attention (pending)
  • 🔴 Blocking issues (must be resolved before merge)
  • [Codex] or [Gemini] from the source ⚠️ / 🔴 details
  • in the table ⚠️ Pending status
  • No ✅ or ⏭️ details summary prefixed with
  • Tasks in the "Action Plan" without a completion marker [x] of

Resolved indicators:

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

Source determination:

  • [Codex] = issue generated by Codex review pass
  • [Gemini] = issue generated by Gemini Code Assist integration
  • Issues without a source prefix are treated as Claude issues (compatible with existing comments)

Step 3: Handle each item one by one (most important!)

Key requirement: discuss one item at a time, but perform fixes as background subtasks in parallel without blocking the discussion flow.

For each unresolved item, execute in order:

3.1 Clearly present the issue

Explain to the user in Traditional Chinese:

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

3.2 Read the actual source code

  • Use the Read tool to view the referenced file
  • Verify whether the issue still exists
  • Check whether it has already been fixed in a recent commit

3.3 Discuss with the user (required!)

This is the most important step. You must:

  • Explain the possible solutions in Traditional Chinese
  • If there are multiple methods, present them as options
  • Use the AskUserQuestion tool or <options> let the user choose
  • Wait for the user to decide before continuing

Option examples:

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

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

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

3.4 Execute according to the user's decision

Fix path:

  1. Confirm the target file list (obtained from the problem description and source code analysis)
  2. Check for file conflicts — whether the target files overlap with in-progress background subtasks:
    • No conflict → Start the background subtask immediately
    • Conflict → Notify the user: "⏳ Target file {file} is currently being modified by subtask {task_id} ({problem name}), wait for it to complete before starting." Use TaskOutput to wait for the conflicting subtask to complete, then start the new subtask
  3. Use the Task tool (run_in_background: true) to start a background subtask; the prompt must include:
    • The complete problem description (quoted from the review comment)
    • Target file paths and line numbers
    • The fix option chosen by the user
    • Enough context for the subtask to run independently (without relying on the main conversation)
  4. Add the subtask to the tracking list (maintained in memory):{ task_id, 問題名稱, 目標檔案列表 }
  5. Record the provisional status 🔧 修復中

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

  • If the user chooses Defer: record the status as ⏭️ Deferred, add the reason
  • If the user chooses Mark N/A: record the status as ⏭️ N/A, add the explanation

3.5 Record the decision in the source code

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

  • Comment format:// Design Decision: [完整原因,直接在註解中說明清楚]
  • Do not use @see PR #N or any external references— all context must be self-contained within the comment
  • This prevents the same problem from appearing again in future reviews, and does not rely on external links

3.6 Automatically continue to the next item

After the decision is recorded, without waiting for the fix subtask to complete, directly inform the user:

"✓ Recorded. Next, let's look at the next problem ({current}/{total})."

Then immediately proceed to step 3.1 for the next item.

3.7 Wait for and accept all subtasks

After all items have been discussed, run the acceptance process:

  1. Show a progress overview:

    📊 處理總覽:
    - 🔧 修復中:N 個(背景子任務進行中)
    - ⏭️ 延後:N 個
    - ⏭️ N/A:N 個
    
  2. Collect the results of each subtask one by one:

    • Use TaskOutput to read the output of each background subtask
    • Success → Update the status to ✅ Fixed
    • Failure → Report the error to the user and provide options:
      <options>
      <option>重試修復</option>
      <option>延後到下個 PR</option>
      <option>標記為不適用 (N/A)</option>
      </options>
      
  3. Verify there are no unexpected overlapping modifications:

    git diff --name-only
    

    Confirm that all modified files are within the expected scope; if there are unexpected file changes, notify the user for confirmation.

  4. Present the final results table:

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

Step 4: Update Review Comment

Precondition: this step can only be executed after step 3.7 acceptance is complete.

⚠️ Warning: the cache script must be used!

When updating a PR review comment,be sure to use the cache-write-comment.sh script, and never directly use the gh api command. When calling it,do not use the --local-only flag, otherwise it will only update the local cache and not sync to GitHub.

Directly using gh api will cause the local cache and GitHub to permanently fall out of sync—the comment content cache has no TTL (unlike the branch-map cache's 1-hour TTL), so it will not expire automatically, and all subsequent cache-read-comment.sh reads will get stale data until the next cache-write-comment.sh or cache-read-comment.sh --force-refresh corrects it.

Update the PR review comment:

  1. Prepare the updated content:

    • Update the status indicator for each item
    • Update the counts in the Summary table
    • Update the updated_at and issues counts in the metadata
    • Before writing, use the shared helper to normalize the metadata:
      METADATA_JSON=$(printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh --stdin --last-writer pr-review-resolver)
      
    • After updating the metadata JSON (for example, via jq editing $METADATA_JSON), use the shared helper to write it back to the hidden block, avoiding changes to the issue sections:
      # 為修改後的 metadata JSON 建立暫存檔。
      # (若此 code block 已有自己的 trap,請擴充既有 trap 而非新增一行。)
      METADATA_FILE=$(mktemp)
      trap 'rm -f "$METADATA_FILE"' EXIT
      
      # 將編輯後的 metadata JSON 寫入暫存檔。
      printf '%s' "$METADATA_JSON" > "$METADATA_FILE"
      
      # 替換 comment 中的 metadata block。
      UPDATED_CONTENT=$(printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh --stdin --metadata-file "$METADATA_FILE")
      
    • Preserve review_sources、[Codex] issues、[Gemini] issues, as well as Claude issues without a prefix
    • Keep the existing review_round unchanged (the resolver only updates status, it is not a review producer)
    • Update Status to the appropriate state
  2. Via --stdin write the updated content directly to the local cache and sync it to GitHub:

EXPECTED_CONTENT_HASH=$(jq -r '.content_hash // ""' ".pr-review-cache/pr-${PR_NUMBER}.json" 2>/dev/null || echo "")

if [ -n "$EXPECTED_CONTENT_HASH" ]; then
  printf '%s\n' "$UPDATED_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER" --expected-content-hash "$EXPECTED_CONTENT_HASH"
else
  printf '%s\n' "$UPDATED_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"
fi

The script will automatically:

  1. Write the content to the local cache (.pr-review-cache/pr-${PR_NUMBER}.json)
  2. Attempt to sync to GitHub (automatically retries up to 3 times)
  3. After success, update the comment ID in the cache
  4. Use atomic write (first write to .tmp then mv) to avoid corruption caused by interrupted writes

Exit codes:

  • 0 = success (both the local cache and GitHub have been updated)
  • 1 = GitHub sync failed (the local cache is up to date, you can use /push-review-cache to retry)
  • 2 = local error (such as PR not found, content empty)
  • 4 = cache hash mismatch, meaning another tool has already updated the comment; re-read the latest comment, merge the resolver status updates, and retry once
  1. If the 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

Step 5: Knowledge extraction (after all items are complete)

Once all items are resolved, analyze what was learned in this session:

  1. Identify patterns:

    • Decisions that apply to multiple files
    • Newly established conventions
    • Clarifications to existing guidelines
  2. Check whether CLAUDE.md needs to be updated:

    • Did any decision clarify an ambiguous guideline?
    • Was a new pattern established that should be documented?
    • Was a missing guideline reference discovered?
  3. Create documentation when necessary:

    • Add the new guideline to the appropriate docs/ file
    • Update CLAUDE.md using progressive disclosure
    • Format: Put a brief summary in CLAUDE.md, and full details in docs/
  4. Update review comment:

    • Add a "Knowledge Extracted" section at the end
    • List any guidelines created or updated
    • Reference document changes

Decision record format

When marking an item as N/A or Deferred, add a comment in the source code:

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

Example:

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

Status indicators

Use consistent status indicators when updating the review:

Indicator Meaning When to use
✅ Issue resolved Code changes completed and verified
⏭️ Intentionally deferred or not applicable Will be handled in the future or is a design consideration
⚠️ Needs attention Still needs to be handled
🔴 Blocking issue Must be resolved before merge

Knowledge extraction criteria

Evaluate whether each resolved item requires knowledge extraction:

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

CLAUDE.md update format

When extracting knowledge, follow progressive disclosure:

In CLAUDE.md (brief reference):

#### [類別] 指南

詳見 [`docs/[guideline-file].md`](docs/[guideline-file].md)。

**核心原則**:[一句話摘要]

**必須參考的情境:**
1. [觸發情境 1]
2. [觸發情境 2]

In docs/ (full details):

# [指南標題]

## 背景

[為何需要此指南]

## 模式

[帶範例的詳細說明]

## 使用時機

[適用的情境]

## 例外

[不適用的情況]

Verification checklist

Before completing the review resolution session:

  • All items have a status (✅, ⏭️, or explicit decision)
  • N/A and Deferred items have source code comments
  • PR review comment has been updated with the resolution
  • Knowledge extraction has been evaluated
  • Any new guidelines have been documented and referenced
  • Summary counts in the Review comment have been updated

Interaction example

The complete interaction example (including the correct flow with parallel background subtasks) is in references/interaction-example.md. Before starting to handle issues one by one, read this example to ensure the interaction flow is correct.

Handling when there is no PR or no Review Comment

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

Common mistakes

❌ Directly use gh api to update the comment

# 錯誤做法 - 永遠不要這樣做!
gh api repos/{owner}/{repo}/issues/comments/${COMMENT_ID} -X PATCH -f body="..."

This will cause the local cache to be permanently out of sync with GitHub. For the correct approach and error recovery method, refer toStep 4: Update Review Comment the warning in.