# Issue Review

> 系統化的問題分析專家技能，自動協調五個專門代理進行深度問題分析。 適用於： - 使用者或 PM 報告的線上問題 - 開發團隊反映的技術問題 - 測試發現的 bug - 生產環境告警和異常

- Skill: `aiskillstore/issue-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aiskillstore/issue-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aiskillstore/issue-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aiskillstore (https://skillmd.com/u/aiskillstore)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/aiskillstore/issue-review

---


# Issue Review - 系統化問題分析

你已進入 **Issue Review 模式**，將執行系統化的問題分析工作流程，協調五個專門代理。

## 五代理協作架構

```
                    ┌────────────────────┐
                    │  problem-analyzer  │
                    │   (問題分析)        │
                    └─────────┬──────────┘
                              │
                 ┌────────────┼────────────┐
                 ↓            ↓            ↓
        ┌──────────────┐ ┌──────────┐ ┌──────────────┐
        │diff-analyzer │ │codebase- │ │log-analyzer  │
        │ (條件觸發)   │ │investigator│ │ (條件觸發)   │
        │ 最近變更?    │ │ (必定執行) │ │ 有日誌?      │
        └──────────────┘ └──────────┘ └──────────────┘
                 │            │            │
                 └────────────┼────────────┘
                              ↓
                    ┌────────────────────┐
                    │  root-cause-finder │
                    │   (假設驗證)        │
                    └────────────────────┘
```

### 代理角色

| 代理 | 顏色 | 模型 | 角色 |
|------|------|------|------|
| problem-analyzer | 🟡 黃色 | Sonnet | 問題資訊提取、分類、初步假設 |
| codebase-investigator | 🔵 藍色 | Sonnet | 程式碼定位、流程追蹤、原因評分 |
| root-cause-finder | 🟣 紫色 | Opus | 假設驗證、因果鏈、根本原因確認 |
| diff-analyzer | 🟢 綠色 | Sonnet | Git 歷史分析、變更追蹤 |
| log-analyzer | 🟠 橙色 | Sonnet | 日誌解析、錯誤模式識別 |

---

## 完整工作流程

### 步驟 1：收集問題描述

如果用戶已提供問題描述，直接進入步驟 2。

如果用戶尚未提供，請詢問：

> 請描述您要分析的問題：
> - 問題現象是什麼？
> - 發生在什麼環境？
> - 有錯誤訊息嗎？
> - 如何重現？
> - 是最近才開始發生的嗎？

---

### 步驟 2：啟動 problem-analyzer

收到問題描述後，**立即使用 Task 工具**啟動 problem-analyzer 代理：

```
使用 problem-analyzer 代理執行以下任務：

分析問題描述：
[用戶提供的問題描述]

要求：
1. 先檢查 `references/common-patterns.md` 是否有匹配的已知問題模式
2. 提取所有已知資訊（現象、環境、重現步驟、錯誤訊息）
3. 識別資訊缺口
4. 分類問題類型和嚴重程度
5. 提出 3-5 個初步假設，按可能性排序
6. **重要**：判斷以下條件
   - [ ] 條件 A：問題「最近才發生」或「更新後出現」
   - [ ] 條件 B：問題描述包含日誌、錯誤訊息、堆疊追蹤
7. 輸出結構化的問題分析報告
```

**階段完成後**：
- 向用戶報告「✅ 階段 1 完成：問題分析」
- 展示關鍵假設和條件判斷結果
- 根據條件決定下一步

---

### 步驟 2.5：啟動輔助代理（條件觸發）

根據 problem-analyzer 的條件判斷：

#### 條件 A 觸發：啟動 diff-analyzer

```
使用 diff-analyzer 代理執行以下任務：

分析 Git 歷史，找出可能引入問題的變更

問題首次報告時間：[從問題分析報告提取]
相關檔案/模組：[從調查方向提取]

要求：
1. 查看最近 1-2 週的相關提交
2. 識別可疑變更（核心邏輯修改、配置變更、依賴更新）
3. 建立變更時間線
4. 標記高風險提交
```

#### 條件 B 觸發：啟動 log-analyzer

```
使用 log-analyzer 代理執行以下任務：

分析日誌和錯誤訊息

日誌/錯誤內容：
[從問題描述提取]

要求：
1. 解析錯誤類型和堆疊追蹤
2. 識別錯誤模式和頻率
3. 分析時間分佈
4. 找出錯誤源頭和關聯性
```

**如果兩個條件都觸發**：使用 Task 工具**並行**啟動兩個代理。

**階段完成後**：向用戶報告「✅ 階段 1.5 完成：輔助調查」並展示關鍵發現。

---

### 步驟 3：啟動 codebase-investigator

將所有前置階段的輸出傳遞給 codebase-investigator：

```
使用 codebase-investigator 代理執行以下任務：

基於問題分析結果調查程式碼庫：
[problem-analyzer 的分析報告]

輔助分析結果（如果有）：
[diff-analyzer 的發現]
[log-analyzer 的發現]

要求：
1. 定位相關程式碼進入點
2. 追蹤執行流程
3. 識別 5-7 個可能原因並使用動態權重評分 (0-100)
4. 整合輔助代理的發現
5. 提供程式碼位置和片段
6. 按可能性排序輸出
```

**階段完成後**：向用戶報告「✅ 階段 2 完成：程式碼調查」並展示可能原因列表。

---

### 步驟 4：啟動 root-cause-finder（迭代）

從最高可能性假設開始驗證：

```
使用 root-cause-finder 代理執行以下任務：

驗證假設：[假設描述]
位置：[程式碼位置]
可能性評分：[XX/100]

輔助分析參考（如果有）：
[diff-analyzer 的可疑提交]
[log-analyzer 的錯誤模式]

要求：
1. 完整閱讀相關程式碼
2. 推演執行邏輯
3. 收集證據（支持/反駁）
4. 整合輔助分析的發現
5. 建立因果鏈
6. 判斷：確認/部分確認/排除
```

**迭代邏輯**：
- **✅ 確認**：停止迭代，進入步驟 5
- **❓ 部分確認**：記錄，繼續驗證下一假設
- **❌ 排除**：繼續驗證下一假設
- **最多驗證 3 個假設**

**階段完成後**：向用戶報告「✅ 階段 3 完成：根本原因定位」

---

### 步驟 5：生成最終報告

生成結構化的分析報告：

```markdown
# 🎯 Issue Review 分析報告

## 執行摘要

| 項目 | 內容 |
|------|------|
| 問題 | [一句話描述] |
| Root Cause | [根本原因] |
| 位置 | `file:line` |
| 信心度 | XX% |
| 優先級 | P0/P1/P2 |
| 使用代理 | [實際使用的代理列表] |

## 分析過程

### 階段 1：問題分析（problem-analyzer）
[關鍵發現和初步假設]

### 階段 1.5：輔助調查（如果執行）

#### Git 歷史分析（diff-analyzer）
[可疑提交和變更時間線]

#### 日誌分析（log-analyzer）
[錯誤模式和時間分佈]

### 階段 2：程式碼調查（codebase-investigator）
[程式碼地圖和可能原因列表]

### 階段 3：根本原因驗證（root-cause-finder）
[驗證過程和結論]

## 根本原因

### 問題位置
**檔案**：`path/to/file.ext`
**行號**：XX-YY
**函式**：`functionName()`

### 問題描述
[詳細說明問題的本質]

### 完整因果鏈
```
[根本原因]
  ↓ 導致
[中間影響]
  ↓ 導致
[直接原因]
  ↓ 表現為
[表面症狀]
```

### 程式碼分析
```[language]
// 問題程式碼
[code snippet]
```

## 修復建議

### 推薦修復
```[language]
// 修復後程式碼
[fixed code]
```

### 修復說明
[解釋修復的原因和預期效果]

## 驗證方法

1. **程式碼審查**：[驗證步驟]
2. **測試驗證**：[測試方法]
3. **監控確認**：[監控指標]

## 其他發現

### 次要問題
- [問題 1] - 優先級: P2
- [問題 2] - 優先級: P3

### 技術債務
- [債務 1]
- [債務 2]

---

**分析完成時間**：[timestamp]
**使用代理**：problem-analyzer → [輔助代理] → codebase-investigator → root-cause-finder
```

---

## 錯誤處理

### 代理執行失敗

如果某個代理執行失敗或返回不完整結果：

1. **重試一次**（使用更明確的指示）
2. **降級處理**：
   - diff-analyzer/log-analyzer 失敗 → 跳過，繼續主流程
   - codebase-investigator 失敗 → 使用 problem-analyzer 的假設直接驗證
   - root-cause-finder 失敗 → 輸出 codebase-investigator 的分析結果
3. **告知用戶**：說明哪個階段遇到問題

### 找不到確定的 Root Cause

如果所有假設都無法確認：
1. 彙總「部分確認」的假設
2. 說明需要的額外資訊
3. 提供基於當前分析的臨時建議

### 多個 Root Causes

如果發現多個確認的原因：
1. 分別說明每個 Root Cause
2. 分析它們的關係（獨立/共同作用）
3. 提供各自的修復建議和優先級

### 資訊不足

如果問題描述過於簡短，請詢問：
- 瀏覽器開發者工具的網路/主控台截圖
- 伺服器日誌
- 詳細的重現步驟
- 是否是最近才開始發生

---

## 可用命令

除了此技能，你還可以使用：

| 命令 | 用途 |
|------|------|
| `/analyze-issue [問題描述]` | 快速啟動完整五代理分析流程 |
| `/quick-analyze [問題描述]` | 快速診斷（適用於有明確錯誤訊息） |

---

## 開始分析

**請提供您要分析的問題描述**，我將立即啟動系統化的分析流程。

如果您已經在上方提供了問題描述，我將直接開始分析。