Comprehensive PR review workflow: execute reviews, integrate Gemini suggestions, and interactively resolve issues

version
5.0.0

Install

/plugin install pr-workflow@marxbiotech-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add marxbiotech/pr-review-toolkit.

Contents

Discovered from source

Skills 6

Enable Subagents

幫助使用者配置 Claude Code 環境,讓 subagent 可以正常執行需要的操作。

重要原則:

  1. 永遠使用繁體中文(zh-TW) 與使用者溝通
  2. 先檢查再更新,只新增缺少的權限
  3. 保留現有配置,不覆蓋使用者其他設定

使用時機

當需要:

  • 啟用 pr-review-resolver 等 skill 的 subagent 功能
  • 修復 subagent 權限被阻擋的問題
  • 在新專案或新環境配置 Claude Code 權限
  • 確保 plugin scripts 可被 subagent 執行

背景說明

pr-review-resolver 等 skill 會啟動 subagent 來執行任務。Subagent 需要以下權限:

權限用途
Read讀取原始碼驗證問題
Edit修復問題時修改檔案
Write寫入檔案(修復問題時建立或修改檔案)
Glob搜尋檔案路徑
Grep搜尋檔案內容
Task啟動背景子任務
Bash(mkdir *)建立必要目錄
Bash(git *)執行 git 指令(如 git diff)
Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)執行 plugin scripts

當這些操作在 subagent 中執行時,需要父會話已經有對應權限,否則會被阻擋。

工作流程

步驟 1:選擇配置層級

使用 AskUserQuestion 詢問使用者偏好的配置層級:

請選擇要配置權限的層級:

**User-level** (`~/.claude/settings.json`)
- 套用到所有專案
- 適合經常使用 pr-review-toolkit 的使用者

**Project-level** (`.claude/settings.json`)
- 只影響當前專案
- 適合想要限制權限範圍的使用者
- 可加入版本控制讓團隊共享

<options>
<option>User-level(套用到所有專案)</option>
<option>Project-level(只影響當前專案)</option>
</options>

步驟 2:檢查現有配置

根據使用者選擇的層級,讀取對應的 settings.json:

  • User-level: ~/.claude/settings.json
  • Project-level: .claude/settings.json

如果檔案不存在,準備建立新檔案。

解析現有的 permissions.allow 陣列(如果存在)。

步驟 3:識別缺少的權限

需要配置的權限清單:

[
  "Read",
  "Edit",
  "Write",
  "Glob",
  "Grep",
  "Task",
  "Bash(mkdir *)",
  "Bash(git *)",
  "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)"
]

比對現有配置,列出缺少的權限。

步驟 4:說明與確認

向使用者說明:

  1. 如果已全部配置:告知使用者權限已完整,不需要任何變更,然後結束。

  2. 如果有缺少的權限:

    • 列出將要新增的每個權限及其用途
    • 顯示完整的配置預覽
    • 使用 AskUserQuestion 確認使用者同意更新

範例說明格式:

目前缺少以下權限:

1. `Read` - 讓 subagent 可以讀取原始碼檔案驗證問題
2. `Write` - 讓 subagent 可以寫入臨時檔案

更新後的配置將是:

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "Task",
      "Bash(mkdir *)",
      "Bash(git *)",
      "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)"
    ]
  }
}

<options>
<option>確認更新配置</option>
<option>取消</option>
</options>

步驟 5:更新配置

使用者確認後:

  1. 建立目錄(如需要):

    • User-level: 確保 ~/.claude/ 存在
    • Project-level: 確保 .claude/ 存在
  2. 合併配置:

    • 如果檔案已存在,讀取並解析 JSON
    • 保留所有現有設定
    • 只新增 permissions.allow 中缺少的項目
    • 不刪除或覆蓋任何現有權限
  3. 寫入配置:

    • 使用正確的 JSON 格式(2 空格縮排)
    • 確保檔案以換行結尾

步驟 6:驗證並通知

  1. 重新讀取配置檔確認變更成功
  2. 顯示最終配置摘要
  3. 提示使用者:「配置已更新。如果 Claude Code 正在執行中,可能需要重新啟動才能套用新權限。」

配置範例

最小配置(新建立)

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "Task",
      "Bash(mkdir *)",
      "Bash(git *)",
      "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)"
    ]
  }
}

合併到現有配置

假設現有配置:

{
  "theme": "dark",
  "permissions": {
    "allow": [
      "Read",
      "Bash(git *)"
    ]
  }
}

更新後:

{
  "theme": "dark",
  "permissions": {
    "allow": [
      "Read",
      "Bash(git *)",
      "Edit",
      "Write",
      "Glob",
      "Grep",
      "Task",
      "Bash(mkdir *)",
      "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*)"
    ]
  }
}

錯誤處理

  • JSON 解析失敗:通知使用者現有配置檔格式有誤,詢問是否要備份後重建
  • 寫入失敗:顯示錯誤訊息,建議檢查目錄權限
  • 使用者取消:確認不做任何變更,結束 skill

驗證清單

完成配置前確認:

  • 使用者已選擇配置層級(User-level 或 Project-level)
  • 現有配置已正確讀取(若存在)
  • 只新增缺少的權限,未覆蓋現有設定
  • 使用者已確認變更內容
  • 配置檔案已成功寫入
  • 已驗證變更生效
  • 已提示使用者可能需要重新啟動 Claude Code

完成後的驗證

配置完成後,建議使用者:

  1. 執行 /pr-review-resolver 測試 subagent 是否正常運作
  2. 如果仍有權限問題,檢查 Claude Code 是否需要重新啟動

成功指標:

  • Subagent 可以讀取和編輯檔案,不再出現權限提示
  • Plugin scripts 可以正常執行
  • 不需要在每次 subagent 操作時手動確認權限

Gemini Review Integrator

Integrate Gemini Code Assist review suggestions into the pr-review-and-document PR comment.

When to Use

Invoke this skill when:

  • A PR has both Gemini Code Assist reviews and a pr-review-and-document comment
  • Need to consolidate all review feedback into a single location
  • Want to track Gemini suggestions alongside Claude's PR review

Workflow

Step 1: Get PR Number and Verify Prerequisites (Cache-Aware)

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

This uses the branch-to-PR-number cache (branch-map.json) with 1-hour TTL, falling back to GitHub API on cache miss.

If no PR exists, inform the user and stop.

Verify pr-review-and-document comment exists:

${CLAUDE_PLUGIN_ROOT}/scripts/find-review-comment.sh "$PR_NUMBER"

If no review comment exists, inform the user to run pr-review-and-document skill first.

Step 2: Fetch Gemini Code Assist Comments

Fetch all PR review comments (inline code comments):

${CLAUDE_PLUGIN_ROOT}/scripts/fetch-gemini-comments.sh "$PR_NUMBER"

The script returns JSON with Gemini suggestions, including:

  • id: Comment ID for deduplication
  • priority: high, medium, or low
  • is_security: Whether it's a security issue
  • is_outdated: Whether the comment is outdated (code changed)
  • file: File path
  • line: Line number (null if file-level)
  • body: Full comment body
  • suggestion: Extracted code suggestion (if any)

Step 3: Filter and Deduplicate

Apply filters to Gemini suggestions:

  1. Exclude outdated comments: Skip comments where is_outdated: true
  2. Check existing integration: Parse metadata for review_sources.gemini.consumed_comment_ids; fall back to legacy gemini_integrated_ids
  3. Skip already integrated: Exclude comments whose IDs are already consumed

Step 4: Categorize Suggestions

Map Gemini priorities to pr-review-and-document categories:

Gemini PriorityPR Review Category
high + is_security🔴 Critical Issues
high🟡 Important Issues
medium + is_security🟡 Important Issues
medium💡 Suggestions
low💡 Suggestions

Step 5: Format Integrated Suggestions

For each new Gemini suggestion, format as:

<details>
<summary><b>N. ⚠️ [Gemini] Issue Title</b></summary>

**Source:** Gemini Code Assist
**File:** `path/to/file.ts:line`

**Problem:** Description from Gemini comment.

**Suggested Fix:**
```suggestion
code here
```

Key formatting rules:

  • Prefix title with [Gemini] to identify source
  • Use ⚠️ status indicator (pending review)
  • Include **Source:** Gemini Code Assist line
  • Preserve Gemini's suggestion code block if present

Step 6: Update PR Review Comment

  1. Fetch existing pr-review-and-document comment body
  2. Parse metadata JSON from <!-- pr-review-metadata ... --> block
  3. Update metadata:
    • Upgrade metadata to schema 1.1 with the shared helper when needed:

      METADATA_JSON=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh --stdin --last-writer gemini-review-integrator)
      
    • Replace the updated hidden metadata block. Run this after all metadata edits (including the dual-write jq step below) have been applied to $METADATA_JSON:

      # Set up a temp file for the modified metadata JSON.
      # (If this code block already declares its own trap, extend it instead of adding a second line.)
      METADATA_FILE=$(mktemp)
      trap 'rm -f "$METADATA_FILE"' EXIT
      
      # Write the fully-edited metadata JSON to the temp file.
      printf '%s' "$METADATA_JSON" > "$METADATA_FILE"
      
      # Replace the metadata block in the comment.
      UPDATED_CONTENT=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh --stdin --metadata-file "$METADATA_FILE")
      
    • Mirror new consumed Gemini comment IDs into BOTH review_sources.gemini.consumed_comment_ids AND legacy gemini_integrated_ids (Phase 2 compatibility window)

    • Mirror the integration timestamp into BOTH review_sources.gemini.last_integrated_at AND legacy gemini_integration_date

    • Once Phase 2 ships, the legacy fields will be removed in a future release; until then, every write keeps both fields in sync so a Phase-1 reader still sees up-to-date IDs. The shared review-metadata-upgrade.sh helper only preserves existing legacy fields — it never back-fills new IDs — so this skill MUST perform the dual-write itself.

      Apply the dual-write atomically with jq:

      # Dual-write new Gemini IDs + integration timestamp during Phase 2 compat window.
      # Both nested (1.1 canonical) and top-level (1.0 legacy) are kept in sync until
      # the legacy fields are removed in a future release.
      METADATA_JSON=$(printf '%s' "$METADATA_JSON" | jq \
        --argjson new_ids "$NEW_INTEGRATED_IDS" \
        --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
          .review_sources.gemini.consumed_comment_ids = ((.review_sources.gemini.consumed_comment_ids // []) + $new_ids | unique)
        | .review_sources.gemini.last_integrated_at = $now
        | .gemini_integrated_ids = ((.gemini_integrated_ids // []) + $new_ids | unique)
        | .gemini_integration_date = $now
      ')
      

      $NEW_INTEGRATED_IDS must be a JSON array of the integer comment IDs newly consumed in this run (e.g. [2726014213, 2726014217]).

    • Preserve review_sources.codex, review_sources.claude, review_sources.grok, review_sources.agy, [Codex] issues, [Grok] issues, [AGY] issues, and untagged Claude issues

    • Increment issue counts in issues object

    • Update updated_at timestamp

  4. Insert new Gemini issues into appropriate sections (Critical, Important, Suggestions)
  5. Renumber existing issues to accommodate new entries

Pipe updated content to cache-write-comment.sh via --stdin:

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

This updates local cache and syncs to GitHub in one step, without temp files. If the script exits 4, another tool updated the cache; re-read the latest comment, merge only the new Gemini integrations, and retry once.

Step 7: Report Integration Results

Summarize what was integrated:

Gemini Review Integration Complete:
- Found: X Gemini comments
- Outdated (skipped): Y
- Already integrated (skipped): Z
- Newly integrated: W
  - Critical: A
  - Important: B
  - Suggestions: C

Metadata Schema Extension

The pr-review-and-document metadata is extended with schema 1.1 source fields:

{
  "review_sources": {
    "gemini": {
      "consumed_comment_ids": [2726014213, 2726014217],
      "last_integrated_at": "2026-01-26T12:00:00Z"
    }
  },
  "gemini_integrated_ids": [2726014213, 2726014217],
  "gemini_integration_date": "2026-01-26T12:00:00Z"
}

This enables:

  • Tracking which Gemini comments have been integrated
  • Preventing duplicate integration across multiple runs
  • Audit trail for integrated suggestions

gemini_integrated_ids and gemini_integration_date are legacy compatibility fields. Read from review_sources.gemini.* first, but preserve legacy fields while older skills may still read them. Use ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh to normalize old metadata before applying Gemini-specific updates, then ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh to write the updated JSON back without changing unrelated sections.

Gemini Comment Structure

Gemini Code Assist comments have these characteristics:

Priority Indicators (in body):

  • ![high](...) - High priority
  • ![medium](...) - Medium priority
  • ![security-medium](...) or ![security-high](...) - Security-related

Outdated Detection:

  • GitHub API field position: null indicates the code has changed
  • These comments should be skipped as they may no longer apply

Code Suggestions:

  • Enclosed in ````suggestion` blocks
  • Should be preserved in integration

Handling Multiple Gemini Review Rounds

Gemini may perform multiple review rounds on a PR. The integration handles this by:

  1. ID-based deduplication: Each comment has a unique ID
  2. Cumulative tracking: review_sources.gemini.consumed_comment_ids grows with each integration
  3. New comments only: Only comments not in consumed_comment_ids are processed

To re-integrate after Gemini runs another review:

  1. Run this skill again
  2. Only new comments will be added
  3. Previously integrated comments remain unchanged

Status Indicators for Gemini Issues

IndicatorMeaning
⚠️Pending review (newly integrated from Gemini)
✅Fixed / Resolved
⏭️Deferred / Not applicable
🔴Escalated to blocking

Initial status for all Gemini integrations is ⚠️ (pending review).

Example Integration

Before (pr-review-and-document comment):

### 🟡 Important Issues

<details>
<summary><b>1. ✅ Some Claude-found issue</b></summary>
...
</details>

After integration:

### 🟡 Important Issues

<details>
<summary><b>1. ✅ Some Claude-found issue</b></summary>
...
</details>

<details>
<summary><b>2. ⚠️ [Gemini] Suppress stderr hides errors</b></summary>

**Source:** Gemini Code Assist
**File:** `.claude/skills/pr-review-and-document/scripts/find-review-comment.sh:19`

**Problem:** Suppressing stderr with `2>/dev/null` can hide important underlying errors.

**Suggested Fix:**
```suggestion
  PR_NUMBER=$(gh pr view --json number -q '.number' || echo "")
```

Validation Checklist

Before completing integration:

  • PR number correctly identified
  • pr-review-and-document comment exists
  • Gemini comments fetched successfully
  • Outdated comments filtered out
  • Previously integrated comments skipped
  • New comments categorized correctly
  • Metadata updated with integrated IDs
  • Issue counts updated accurately
  • Comment posted successfully

Error Handling

ErrorAction
No PR foundInform user, stop
No review commentSuggest running pr-review-and-document first
No Gemini commentsInform user, nothing to integrate
API failureReport error with details
All comments outdatedInform user, nothing to integrate
All comments already integratedInform user, up to date

PR Cache Cleanup

Remove cache files for PRs that have been merged or closed.

When to Use

Invoke this skill when:

  • User wants to clean up stale cache files
  • User says "clean up cache", "cleanup merged PR caches", "remove old caches", or "clear review cache"
  • User wants to free up space from old cache files

Note: This skill has disable-model-invocation: true because it deletes files and should only be user-triggered.

Workflow

Step 1: Preview (Dry Run)

Always start with a dry run to show what would be deleted:

${CLAUDE_PLUGIN_ROOT}/scripts/cache-cleanup.sh --dry-run

Step 2: Confirm with User

Present the preview results to the user:

  • How many files would be deleted
  • Which PRs they belong to
  • PR states (MERGED, CLOSED, NOT_FOUND)

Ask for confirmation before proceeding.

Step 3: Execute Cleanup

Only after user confirmation:

${CLAUDE_PLUGIN_ROOT}/scripts/cache-cleanup.sh

Step 4: Report Results

Inform the user:

  • Number of files deleted
  • Number of files kept (open PRs)
  • Any errors encountered

Options

FlagDescription
--dry-runPreview only, don't delete
--allRemove ALL cache files including open PRs (use with caution)

Example Output

=== PR Review Cache Cleanup ===

DRY RUN - no files will be deleted

Scanning cache files...

Would delete: .pr-review-cache/pr-123.json (PR #123, state: MERGED, cached: 2026-02-01T10:00:00Z)
Would delete: .pr-review-cache/pr-124.json (PR #124, state: CLOSED, cached: 2026-02-02T10:00:00Z)
Keeping: .pr-review-cache/pr-125.json (PR #125 is still open)

=== Summary ===
Would delete: 2 files
Kept: 1 files

See Also

完整工作流程說明請參閱 pr-review-workflow.md。

PR Cache Sync

Synchronize local cache with the latest PR review comment from GitHub.

When to Use

Invoke this skill when:

  • User wants to ensure their local cache is up-to-date
  • User suspects the cache might be stale
  • User says "sync PR cache", "pull latest review", "refresh cache", or "update local cache"

Workflow

Step 1: Get PR Number (Cache-Aware)

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

This uses the branch-to-PR-number cache (branch-map.json) with 1-hour TTL, falling back to GitHub API on cache miss.

If no PR exists for the current branch, inform the user and stop.

Step 2: Run Sync Script

${CLAUDE_PLUGIN_ROOT}/scripts/cache-sync.sh "$PR_NUMBER"

The script will:

  1. Show previous cache timestamp (if exists)
  2. Force refresh from GitHub
  3. Compare hashes to detect changes
  4. Report results

Step 3: Report Results

Inform the user:

  • Whether the cache was updated
  • If content changed since last cache
  • The new cache timestamp

Example Output

=== PR Review Cache Sync ===
PR #123

Previous cache: 2026-02-05T10:30:00Z
Previous hash: sha256:abc123...

Fetching from GitHub...

New cache: 2026-02-05T14:45:00Z
New hash: sha256:def456...

⚠️  Content changed since last cache!

=== Sync complete ===

See Also

完整工作流程說明請參閱 pr-review-workflow.md。

PR Review and Document

Execute comprehensive PR review using pr-review-toolkit and post structured results as a PR comment.

When to Use

Invoke this skill when:

  • A comprehensive PR review needs to be documented on the PR
  • A formal review record is required for a feature branch
  • Review findings need to be visible directly on the PR for team reference

Workflow

Step 1: Get PR Number (Cache-Aware)

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

This uses the branch-to-PR-number cache (branch-map.json) with 1-hour TTL, falling back to GitHub API on cache miss.

If no PR exists for the current branch, inform the user and stop.

Step 2: Check Existing Review Comment (Cache-Aware)

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

This uses the local cache if available, falling back to GitHub API on cache miss.

If content is returned:

  • Extract metadata from <!-- pr-review-metadata ... --> block
  • Note the current review_round and issues status
  • Read .pr-review-cache/pr-${PR_NUMBER}.json and save .content_hash as EXPECTED_CONTENT_HASH
  • Preserve any existing [Gemini], [Codex], [Grok], and [AGY] issues and review_sources metadata when writing the next review

Step 3: Execute PR Review

Launch the pr-review-toolkit with opus model using the Skill tool:

Skill: pr-review-toolkit:review-pr
Args: all
Model: opus

Required agents (always run):

  • code-reviewer - General code quality and CLAUDE.md compliance
  • code-simplifier - Code simplification opportunities
  • silent-failure-hunter - Error handling and silent failure detection
  • type-design-analyzer - Type design quality analysis
  • pr-test-analyzer - Test coverage analysis
  • comment-analyzer - Comment accuracy and maintainability

Important: All agents are mandatory for every review to ensure comprehensive coverage.

Step 4: Format Review Comment

Structure the review as a PR comment with hidden metadata and collapsible sections.

Character Limit: Keep total content under ~40K characters (GitHub limit is 65,536).

Multi-source compatibility: If an existing review comment is present, do not blindly regenerate the whole comment. Merge the new Claude findings into the existing structure:

  • Upgrade metadata to schema 1.1 before writing. Prefer the shared helper:
    METADATA_JSON=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh --stdin --last-writer pr-review-and-document)
    
  • After editing metadata JSON (e.g. via jq), replace the hidden block with the shared helper:
    # Set up a temp file for the modified metadata JSON.
    # (If this code block already declares its own trap, extend it instead of adding a second line.)
    METADATA_FILE=$(mktemp)
    trap 'rm -f "$METADATA_FILE"' EXIT
    
    # Write the edited metadata JSON to the temp file.
    printf '%s' "$METADATA_JSON" > "$METADATA_FILE"
    
    # Replace the metadata block in the comment.
    UPDATED_CONTENT=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh --stdin --metadata-file "$METADATA_FILE")
    
  • Preserve review_sources.gemini, review_sources.codex, review_sources.grok, review_sources.agy, [Gemini] issues, [Codex] issues, [Grok] issues, and [AGY] issues
  • Preserve existing issue statuses (✅, ⏭️, ⚠️, 🔴) unless the new Claude review proves they changed
  • Treat untagged issues as Claude issues
  • Increment PR-global review_round only when this review adds new findings; empty refreshes only update review_sources.claude.last_reviewed_*
Metadata Block Format

The metadata block uses HTML comment syntax with a specific marker for identification:

  • Opening: <!-- pr-review-metadata (marker on same line as opening)
  • Content: JSON object with review state
  • Closing: --> on its own line after the JSON

Important: The find-review-comment.sh script searches for <!-- pr-review-metadata to identify review comments. Do not modify this marker format.

Comment Template
<!-- pr-review-metadata
{
  "schema_version": "1.1",
  "created_by": "pr-review-and-document",
  "last_writer": "pr-review-and-document",
  "skill": "pr-review-and-document",
  "review_round": 1,
  "created_at": "YYYY-MM-DDTHH:MM:SSZ",
  "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
  "branch": "branch-name",
  "base": "main",
  "issues": {
    "critical": { "total": 0, "fixed": 0 },
    "important": { "total": 0, "fixed": 0 },
    "suggestions": { "total": 0, "fixed": 0 }
  },
  "agents_run": ["code-reviewer", "silent-failure-hunter", "type-design-analyzer", "pr-test-analyzer", "code-simplifier", "comment-analyzer"],
  "review_sources": {
    "claude": {
      "last_reviewed_head": "HEAD_SHA",
      "last_reviewed_at": "YYYY-MM-DDTHH:MM:SSZ",
      "agents_run": ["code-reviewer", "silent-failure-hunter", "type-design-analyzer", "pr-test-analyzer", "code-simplifier", "comment-analyzer"]
    },
    "gemini": {
      "consumed_comment_ids": [],
      "last_integrated_at": null
    },
    "codex": {
      "last_reviewed_head": null,
      "last_reviewed_at": null,
      "posted_finding_ids": []
    },
    "grok": {
      "last_reviewed_head": null,
      "last_reviewed_at": null,
      "posted_finding_ids": [],
      "agents_run": []
    },
    "agy": {
      "last_reviewed_head": null,
      "last_reviewed_at": null,
      "posted_finding_ids": [],
      "agents_run": []
    }
  }
}
-->

## 🤖 PR Review

**Branch:** `branch-name` → `base-branch`
**Round:** N | **Updated:** YYYY-MM-DD
**Reviewer Sources:** Claude

---

### 📊 Summary

| Category | Total | Fixed | Remaining |
|----------|-------|-------|-----------|
| 🔴 Critical | X | X | X |
| 🟡 Important | X | X | X |
| 💡 Suggestions | X | X | X |

**Status:** [✅ Ready to merge | ⚠️ Needs attention | 🔴 Blocking issues]

---

### 🔴 Critical Issues

<details open>
<summary><b>1. [Status Emoji] Issue Title</b></summary>

**File:** `path/to/file.ts:line`

**Problem:** Description of the issue.

**Fix:** Resolution or suggested fix.

</details>

[Repeat for each critical issue]

---

### 🟡 Important Issues

<details>
<summary><b>1. [Status Emoji] Issue Title</b></summary>

**File:** `path/to/file.ts:line`

**Problem:** Description.

**Fix:** Resolution.

</details>

[Repeat for each important issue]

---

### 💡 Suggestions

<details>
<summary>View N suggestions (M addressed)</summary>

| # | Suggestion | Status |
|---|------------|--------|
| 1 | Description | ✅ / ⏭️ |

</details>

---

### ✨ Strengths

- Positive observation 1
- Positive observation 2

---

### 📋 Type Design Ratings

| Type | Encap. | Express. | Useful. | Enforce. | Overall |
|------|--------|----------|---------|----------|---------|
| TypeName | X/10 | X/10 | X/10 | X/10 | **X/10** |

---

### 🎯 Action Plan

**Before Merge:**
- [ ] Action item 1
- [x] Completed item

**After Merge (Backlog):**
- [ ] Future improvement

---

<sub>Generated by pr-review-and-document skill | Round N | [View edit history](click edited)</sub>

Step 5: Write Review Comment (Cache-Aware)

Pipe the formatted content directly to cache-write-comment.sh via --stdin:

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

The script will:

  • Update local cache (.pr-review-cache/pr-{N}.json)
  • Sync to GitHub via upsert-review-comment.sh --stdin(stdin pipe,不使用 temp file)
  • Return the comment URL
  • Exit 4 if another tool updated the cache after this skill read it; re-read, merge your changes into the newer comment, and retry once

Step 6: Verify

Confirm the comment was posted successfully by checking the returned URL.

Status Indicators

Use consistent status indicators:

IndicatorMeaning
✅Fixed / Resolved
⏭️Deferred / Skipped intentionally
⚠️Needs attention
🔴Blocking / Critical

Multi-Round Reviews

When updating an existing review:

  1. Update review_round and timestamps based on whether this round adds new findings:
    • New findings present: increment review_round, update updated_at, update issue counts and statuses.
    • Empty refresh (no new findings): keep review_round unchanged; update only review_sources.claude.last_reviewed_head and review_sources.claude.last_reviewed_at. Do not modify existing issue statuses or counts.
  2. Preserve review_sources metadata and existing non-Claude issue sections.
  3. Keep the same comment (GitHub tracks edit history).

Previous review content is preserved in GitHub's "edited" dropdown, providing full audit trail.

Metadata Migration

When reading older schema_version: "1.0" metadata, upgrade in memory before writing:

1.0 field1.1 field
skillcreated_by if missing, skill legacy field, and current last_writer
agents_runreview_sources.claude.agents_run and top-level agents_run during compatibility window
gemini_integrated_idsreview_sources.gemini.consumed_comment_ids
gemini_integration_datereview_sources.gemini.last_integrated_at

Do not downgrade. New writes should use comment metadata schema 1.1; the cache envelope remains schema_version: "1.0".

Use ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh for this migration when possible, then use ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh to merge the returned JSON back into the <!-- pr-review-metadata ... --> block without touching issue sections.

Integration Notes

Using with pr-review-toolkit

This skill wraps the pr-review-toolkit:review-pr command and:

  1. Forces opus model for comprehensive analysis
  2. Always runs all 6 review agents (mandatory)
  3. Formats output as structured PR comment
  4. Posts directly to the PR

Character Limit Handling

If review content exceeds ~40K characters:

  1. Collapse more sections with <details>
  2. Summarize verbose descriptions
  3. Move detailed code examples to collapsed sections

No PR Available

If the current branch has no open PR:

  • Inform the user
  • Suggest creating a PR first: gh pr create

Validation Checklist

Before posting the review comment:

  • PR number correctly identified
  • All 6 review agents executed
  • Metadata JSON is valid
  • Issue counts match content
  • Status indicators are consistent
  • Content is under 40K characters
  • Comment posted/updated successfully

PR Review Resolver

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

重要原則:

  1. 永遠使用繁體中文(zh-TW) 與使用者溝通
  2. 逐一處理每個問題,不要批次處理
  3. 由使用者決定處理方式,不要自行決定

使用時機

當需要:

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

工作流程

步驟 1:取得 PR Review Comment(使用快取)

首先取得 PR 編號(使用 branch-map 快取):

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

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

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

接著取得 review comment(使用本地快取):

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

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

若找不到 review comment(exit code 2),通知使用者先執行 pr-review-and-document skill。

步驟 2:解析未解決項目

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

未解決指標:

  • ⚠️ 需要注意的項目(待處理)
  • 🔴 阻擋性問題(必須在 merge 前解決)
  • [Codex]、[Gemini]、[Grok] 或 [AGY] 來源的 ⚠️ / 🔴 details
  • 表格中的 ⚠️ Pending 狀態
  • 沒有 ✅ 或 ⏭️ 前綴的 details summary
  • 「Action Plan」中沒有完成標記 [x] 的任務

已解決指標:

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

來源判斷:

  • [Codex] = Codex review pass 產生的 issue
  • [Gemini] = Gemini Code Assist integration 產生的 issue
  • [Grok] = Grok review pass 產生的 issue
  • [AGY] = Antigravity (agy) review pass 產生的 issue
  • 無來源 prefix 的 issue 視為 Claude issue(相容既有 comment)

步驟 3:逐一處理每個項目(最重要!)

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

對於 每一個 未解決項目,依序執行:

3.1 清楚呈現問題

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

  • 引用 review 中的問題描述
  • 顯示 file:line 參考位置
  • 解釋問題及其影響
3.2 閱讀實際原始碼
  • 使用 Read 工具檢視被參考的檔案
  • 驗證問題是否仍然存在
  • 檢查是否已在最近的 commit 中修復
3.3 與使用者討論(必要!)

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

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

選項範例:

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

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

<options>
<option>修復這個問題</option>
<option>延後到下個 PR</option>
<option>標記為不適用 (N/A)</option>
</options>
3.4 依使用者決定執行

修復路徑:

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

延後 / N/A 路徑(inline 處理,不需子任務):

  • 若使用者選擇 延後:記錄狀態為 ⏭️ Deferred,加上原因
  • 若使用者選擇 標記 N/A:記錄狀態為 ⏭️ N/A,加上說明
3.5 在原始碼中記錄決策

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

  • 註解格式:// Design Decision: [完整原因,直接在註解中說明清楚]
  • 不要使用 @see PR #N 或任何外部參考——所有脈絡必須自包含在註解內
  • 這可防止相同問題在未來的 review 中再次出現,且不依賴外部連結
3.6 自動繼續下一個項目

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

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

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

3.7 等待並驗收所有子任務

所有項目討論完畢後,執行驗收流程:

  1. 顯示進度總覽:

    📊 處理總覽:
    - 🔧 修復中:N 個(背景子任務進行中)
    - ⏭️ 延後:N 個
    - ⏭️ N/A:N 個
    
  2. 逐一收集子任務結果:

    • 使用 TaskOutput 讀取每個背景子任務的輸出
    • 成功 → 更新狀態為 ✅ Fixed
    • 失敗 → 向使用者報告錯誤,提供選項:
      <options>
      <option>重試修復</option>
      <option>延後到下個 PR</option>
      <option>標記為不適用 (N/A)</option>
      </options>
      
  3. 驗證無非預期重疊修改:

    git diff --name-only
    

    確認修改的檔案都在預期範圍內,若有非預期檔案變更,通知使用者確認。

  4. 呈現最終結果表格:

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

步驟 4:更新 Review Comment

前提條件:步驟 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:

  1. 準備更新後的內容:

    • 更新各項目的狀態指標
    • 更新 Summary 表格的計數
    • 更新 metadata 中的 updated_at 和 issues 計數
    • 寫入前用 shared helper 正規化 metadata:
      METADATA_JSON=$(printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh --stdin --last-writer pr-review-resolver)
      
    • 更新 metadata JSON 後(例如透過 jq 編輯 $METADATA_JSON),用 shared helper 寫回 hidden block,避免改動 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")
      
    • 保留 review_sources、[Codex] issues、[Gemini] issues、[Grok] issues、[AGY] issues,以及無 prefix 的 Claude issues
    • 保持既有 review_round 不變(resolver 只更新狀態,不是 review producer)
    • 將 Status 更新為適當狀態
  2. 透過 --stdin 將更新內容直接寫入本地快取並同步至 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

腳本會自動:

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

Exit codes:

  • 0 = 成功(本地快取 + GitHub 都已更新)
  • 1 = GitHub 同步失敗(本地快取是最新的,可用 /push-review-cache 重試)
  • 2 = 本地錯誤(如找不到 PR、內容為空)
  • 4 = cache hash mismatch,代表其他 tool 已更新 comment;重新讀取最新 comment,合併 resolver 狀態更新後重試一次
  1. 若同步失敗,通知使用者:
    • 本地快取已安全保存(.pr-review-cache/pr-${PR_NUMBER}.json)
    • 使用者可稍後執行 /push-review-cache command 完成同步

步驟 5:知識萃取(所有項目完成後)

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

  1. 識別模式:

    • 適用於多個檔案的決策
    • 新建立的慣例
    • 對現有指南的澄清
  2. 檢查是否需要更新 CLAUDE.md:

    • 是否有決策澄清了模糊的指南?
    • 是否建立了應該記錄的新模式?
    • 是否發現了缺少的指南參考?
  3. 必要時建立文件:

    • 將新指南加入適當的 docs/ 檔案
    • 用漸進式揭露方式更新 CLAUDE.md
    • 格式:CLAUDE.md 中放簡要摘要,docs/ 中放完整詳情
  4. 更新 review comment:

    • 在最後加入「Knowledge Extracted」章節
    • 列出任何建立或更新的指南
    • 參考文件變更

決策記錄格式

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

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

範例:

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

狀態指標

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

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

知識萃取標準

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

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

CLAUDE.md 更新格式

萃取知識時,遵循漸進式揭露:

在 CLAUDE.md 中(簡要參考):

#### [類別] 指南

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

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

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

在 docs/ 中(完整詳情):

# [指南標題]

## 背景

[為何需要此指南]

## 模式

[帶範例的詳細說明]

## 使用時機

[適用的情境]

## 例外

[不適用的情況]

驗證清單

完成 review 解決 session 前:

  • 所有項目都有狀態(✅、⏭️ 或明確決策)
  • N/A 和 Deferred 項目有原始碼註解
  • PR review comment 已更新解決方案
  • 已評估知識萃取
  • 任何新指南已記錄並參考
  • Review comment 中的 Summary 計數已更新

互動範例

完整互動範例(含並行背景子任務的正確流程)在 references/interaction-example.md。在開始逐一處理問題前,先讀取此範例以確保互動流程正確。

無 PR 或無 Review Comment 的處理

  • 無 PR:通知使用者先建立 PR(gh pr create)
  • 無 Review Comment:通知使用者先執行 pr-review-and-document skill 產生 review

常見錯誤

❌ 直接使用 gh api 更新 comment

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

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

Commands 2

Deploy to Environment

使用此命令會在當前分支的 PR 上自動留言 /deploy <env> 來觸發部署。

前置條件

  • 已安裝 GitHub CLI (gh) 並完成認證
  • 當前目錄為 git repository
  • 當前分支已有對應的 PR

使用方式

/deploy-pr <environment>

可用環境

環境簡寫
stagingstaging
dev-brianbrian
dev-rayray
dev-reckiereckie
dev-sukisuki
dev-xinxin
previewpreview
snowiousnowiou

執行

${CLAUDE_PLUGIN_ROOT}/scripts/deploy-pr.sh "$ARGUMENTS"

Push Review Cache to GitHub

將本地快取中的 PR review comment 推送至 GitHub。

安全機制

推送前會自動比對本地 cached_at 與遠端 updated_at:

  • 本地較新 → 正常推送
  • 遠端較新 → 中止並警告(exit code 3),避免覆蓋他人更新
  • 加上 force → 跳過時間戳檢查,強制推送

使用時機

  • cache-write-comment.sh 的 GitHub 同步失敗後,需要重試上傳
  • 使用者說「重新同步 review」、「push review cache」、「retry sync」
  • 本地快取已更新但 GitHub 尚未同步

前置條件

  • 本地快取存在(.pr-review-cache/pr-{PR_NUMBER}.json)
  • 已安裝 GitHub CLI (gh) 並完成認證

使用方式

/push-review-cache [PR_NUMBER]
/push-review-cache [PR_NUMBER] force

若不提供 PR_NUMBER,會自動從當前分支取得。

執行

解析參數,判斷是否包含 force:

  • 若 $ARGUMENTS 包含 force,從參數中取出 PR_NUMBER(非 "force" 的部分)並加上 --force 旗標
  • 若 $ARGUMENTS 不包含 force,直接傳遞所有參數
ARGS="$ARGUMENTS"
FORCE_FLAG=""
PR_NUM=""

for word in $ARGS; do
  case "$word" in
    force|--force) FORCE_FLAG="--force" ;;
    *) PR_NUM="$word" ;;
  esac
done

${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --sync-from-cache $PR_NUM $FORCE_FLAG

回報執行結果給使用者:

  • 成功(exit 0):顯示 GitHub comment URL
  • 遠端較新(exit 3):告知使用者遠端有更新的版本,詢問是否要 force push 或先用 /pr-cache-sync 拉取最新版本
  • 同步失敗(exit 1):顯示錯誤訊息,建議檢查網路連線或 GitHub token 權限

Sponsors

Details

Marketplace
marxbiotech/pr-review-toolkit
Author
MarxBiotech
Category
Code Review
License
MIT
Keywords
pr-review, code-review, gemini, github