
pr-workflow
Comprehensive PR review workflow: execute reviews, integrate Gemini suggestions, and interactively resolve issues
- version
- 5.0.0
Install
/plugin install pr-workflow@marxbiotech-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add marxbiotech/pr-review-toolkit.
Contents
Discovered from sourceSkills 6
Enable Subagents
幫助使用者配置 Claude Code 環境,讓 subagent 可以正常執行需要的操作。
重要原則:
- 永遠使用繁體中文(zh-TW) 與使用者溝通
- 先檢查再更新,只新增缺少的權限
- 保留現有配置,不覆蓋使用者其他設定
使用時機
當需要:
- 啟用 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:說明與確認
向使用者說明:
-
如果已全部配置:告知使用者權限已完整,不需要任何變更,然後結束。
-
如果有缺少的權限:
- 列出將要新增的每個權限及其用途
- 顯示完整的配置預覽
- 使用 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:更新配置
使用者確認後:
-
建立目錄(如需要):
- User-level: 確保
~/.claude/存在 - Project-level: 確保
.claude/存在
- User-level: 確保
-
合併配置:
- 如果檔案已存在,讀取並解析 JSON
- 保留所有現有設定
- 只新增
permissions.allow中缺少的項目 - 不刪除或覆蓋任何現有權限
-
寫入配置:
- 使用正確的 JSON 格式(2 空格縮排)
- 確保檔案以換行結尾
步驟 6:驗證並通知
- 重新讀取配置檔確認變更成功
- 顯示最終配置摘要
- 提示使用者:「配置已更新。如果 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
完成後的驗證
配置完成後,建議使用者:
- 執行
/pr-review-resolver測試 subagent 是否正常運作 - 如果仍有權限問題,檢查 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 deduplicationpriority: high, medium, or lowis_security: Whether it's a security issueis_outdated: Whether the comment is outdated (code changed)file: File pathline: Line number (null if file-level)body: Full comment bodysuggestion: Extracted code suggestion (if any)
Step 3: Filter and Deduplicate
Apply filters to Gemini suggestions:
- Exclude outdated comments: Skip comments where
is_outdated: true - Check existing integration: Parse metadata for
review_sources.gemini.consumed_comment_ids; fall back to legacygemini_integrated_ids - Skip already integrated: Exclude comments whose IDs are already consumed
Step 4: Categorize Suggestions
Map Gemini priorities to pr-review-and-document categories:
| Gemini Priority | PR 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 Assistline - Preserve Gemini's suggestion code block if present
Step 6: Update PR Review Comment
- Fetch existing pr-review-and-document comment body
- Parse metadata JSON from
<!-- pr-review-metadata ... -->block - Update metadata:
-
Upgrade metadata to schema
1.1with 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
jqstep 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_idsAND legacygemini_integrated_ids(Phase 2 compatibility window) -
Mirror the integration timestamp into BOTH
review_sources.gemini.last_integrated_atAND legacygemini_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.shhelper 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_IDSmust 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
issuesobject -
Update
updated_attimestamp
-
- Insert new Gemini issues into appropriate sections (Critical, Important, Suggestions)
- 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 priority- Medium priorityor- Security-related
Outdated Detection:
- GitHub API field
position: nullindicates 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:
- ID-based deduplication: Each comment has a unique ID
- Cumulative tracking:
review_sources.gemini.consumed_comment_idsgrows with each integration - New comments only: Only comments not in
consumed_comment_idsare processed
To re-integrate after Gemini runs another review:
- Run this skill again
- Only new comments will be added
- Previously integrated comments remain unchanged
Status Indicators for Gemini Issues
| Indicator | Meaning |
|---|---|
| ⚠️ | 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
| Error | Action |
|---|---|
| No PR found | Inform user, stop |
| No review comment | Suggest running pr-review-and-document first |
| No Gemini comments | Inform user, nothing to integrate |
| API failure | Report error with details |
| All comments outdated | Inform user, nothing to integrate |
| All comments already integrated | Inform 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
| Flag | Description |
|---|---|
--dry-run | Preview only, don't delete |
--all | Remove 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:
- Show previous cache timestamp (if exists)
- Force refresh from GitHub
- Compare hashes to detect changes
- 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_roundand issues status - Read
.pr-review-cache/pr-${PR_NUMBER}.jsonand save.content_hashasEXPECTED_CONTENT_HASH - Preserve any existing
[Gemini],[Codex],[Grok], and[AGY]issues andreview_sourcesmetadata 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.1before 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_roundonly when this review adds new findings; empty refreshes only updatereview_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
4if 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:
| Indicator | Meaning |
|---|---|
| ✅ | Fixed / Resolved |
| ⏭️ | Deferred / Skipped intentionally |
| ⚠️ | Needs attention |
| 🔴 | Blocking / Critical |
Multi-Round Reviews
When updating an existing review:
- Update
review_roundand timestamps based on whether this round adds new findings:- New findings present: increment
review_round, updateupdated_at, update issue counts and statuses. - Empty refresh (no new findings): keep
review_roundunchanged; update onlyreview_sources.claude.last_reviewed_headandreview_sources.claude.last_reviewed_at. Do not modify existing issue statuses or counts.
- New findings present: increment
- Preserve
review_sourcesmetadata and existing non-Claude issue sections. - 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 field | 1.1 field |
|---|---|
skill | created_by if missing, skill legacy field, and current last_writer |
agents_run | review_sources.claude.agents_run and top-level agents_run during compatibility window |
gemini_integrated_ids | review_sources.gemini.consumed_comment_ids |
gemini_integration_date | review_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:
- Forces opus model for comprehensive analysis
- Always runs all 6 review agents (mandatory)
- Formats output as structured PR comment
- Posts directly to the PR
Character Limit Handling
If review content exceeds ~40K characters:
- Collapse more sections with
<details> - Summarize verbose descriptions
- 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 中的未解決問題。
重要原則:
- 永遠使用繁體中文(zh-TW) 與使用者溝通
- 逐一處理每個問題,不要批次處理
- 由使用者決定處理方式,不要自行決定
使用時機
當需要:
- 處理 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 依使用者決定執行
修復路徑:
- 確認目標檔案清單(從問題描述與原始碼分析中取得)
- 檢查檔案衝突——目標檔案是否與進行中的背景子任務重疊:
- 無衝突 → 立即啟動背景子任務
- 有衝突 → 通知使用者:「⏳ 目標檔案
{file}正在被子任務 {task_id}({問題名稱})修改中,等待完成後再啟動。」使用TaskOutput等待衝突子任務完成,然後再啟動新子任務
- 用 Task tool(
run_in_background: true)啟動背景子任務,prompt 必須包含:- 完整的問題描述(從 review comment 引用)
- 目標檔案路徑與行號
- 使用者選擇的修復方案
- 足夠的 context 讓子任務可獨立執行(不依賴主對話)
- 將子任務加入追蹤清單(在記憶體中維護):
{ task_id, 問題名稱, 目標檔案列表 } - 記錄暫定狀態
🔧 修復中
延後 / 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 等待並驗收所有子任務
所有項目討論完畢後,執行驗收流程:
-
顯示進度總覽:
📊 處理總覽: - 🔧 修復中:N 個(背景子任務進行中) - ⏭️ 延後:N 個 - ⏭️ N/A:N 個 -
逐一收集子任務結果:
- 使用
TaskOutput讀取每個背景子任務的輸出 - 成功 → 更新狀態為
✅ Fixed - 失敗 → 向使用者報告錯誤,提供選項:
<options> <option>重試修復</option> <option>延後到下個 PR</option> <option>標記為不適用 (N/A)</option> </options>
- 使用
-
驗證無非預期重疊修改:
git diff --name-only確認修改的檔案都在預期範圍內,若有非預期檔案變更,通知使用者確認。
-
呈現最終結果表格:
| # | 問題 | 決策 | 狀態 | |---|------|------|------| | 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:
-
準備更新後的內容:
- 更新各項目的狀態指標
- 更新 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 更新為適當狀態
-
透過
--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
腳本會自動:
- 將內容寫入本地快取(
.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、內容為空)4= cache hash mismatch,代表其他 tool 已更新 comment;重新讀取最新 comment,合併 resolver 狀態更新後重試一次
- 若同步失敗,通知使用者:
- 本地快取已安全保存(
.pr-review-cache/pr-${PR_NUMBER}.json) - 使用者可稍後執行
/push-review-cachecommand 完成同步
- 本地快取已安全保存(
步驟 5:知識萃取(所有項目完成後)
當所有項目都解決後,分析此次 session 的學習:
-
識別模式:
- 適用於多個檔案的決策
- 新建立的慣例
- 對現有指南的澄清
-
檢查是否需要更新 CLAUDE.md:
- 是否有決策澄清了模糊的指南?
- 是否建立了應該記錄的新模式?
- 是否發現了缺少的指南參考?
-
必要時建立文件:
- 將新指南加入適當的
docs/檔案 - 用漸進式揭露方式更新 CLAUDE.md
- 格式:CLAUDE.md 中放簡要摘要,docs/ 中放完整詳情
- 將新指南加入適當的
-
更新 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-documentskill 產生 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>
可用環境
| 環境 | 簡寫 |
|---|---|
| staging | staging |
| dev-brian | brian |
| dev-ray | ray |
| dev-reckie | reckie |
| dev-suki | suki |
| dev-xin | xin |
| preview | preview |
| snowiou | snowiou |
執行
${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