PR Review Resolver

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

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

Step 1: Retrieve PR Review Comments (Using Cache)

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.

Step 2: Parse Unresolved Items

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

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 Clearly Present the Issue

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 Read the Actual Source Code

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 Discuss with the User (Mandatory!)

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 Execute According to User's Decision

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 Record Decisions in Source Code

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 Automatically Proceed to the Next Item

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 Wait for and Accept All Subtasks

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 |

Step 4: Update Review Comments

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

Step 5: Knowledge Extraction (After All Items Completed)

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

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

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

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 Update Format

When extracting knowledge, follow progressive disclosure:

In CLAUDE.md (brief reference):

markdown

#### [Category] Guidelines

See [`docs/[guideline-file].md`](docs/[guideline-file].md) for details.

**Core Principle**: [One-sentence summary]

**Mandatory Reference Scenarios:**
1. [Trigger scenario 1]
2. [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

[Scenarios where it does not apply]

Verification Checklist

Before completing the review resolution session:

All items have statuses (✅, ⏭️ or explicit decisions)
N/A and Deferred items have source code comments
PR review comments have been updated with solutions
Knowledge extraction has been evaluated
Any new guidelines have been documented and referenced
Summary counts in review comments have been updated

Interaction Example

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.

Handling No PR or No Review Comments

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

❌ Directly using

gh api

to update comments

bash

# Wrong approach - never do this!
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.

pr-review-resolver

NPX Install

Tags

SKILL.md Content (Chinese)

PR Review Resolver

Usage Scenarios

Workflow

Step 1: Retrieve PR Review Comments (Using Cache)

Step 2: Parse Unresolved Items

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

3.1 Clearly Present the Issue

3.2 Read the Actual Source Code

3.3 Discuss with the User (Mandatory!)

3.4 Execute According to User's Decision

3.5 Record Decisions in Source Code

3.6 Automatically Proceed to the Next Item

3.7 Wait for and Accept All Subtasks

Step 4: Update Review Comments

Step 5: Knowledge Extraction (After All Items Completed)

Decision Recording Format

Status Indicators

Knowledge Extraction Standards

CLAUDE.md Update Format

Verification Checklist

Interaction Example

Handling No PR or No Review Comments

Common Errors

❌ Directly using
`gh api`
to update comments