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：生成最終報告

生成結構化的分析報告：

# 🎯 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]

修復建議

推薦修復

// 修復後程式碼
[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 [問題描述]` | 快速診斷（適用於有明確錯誤訊息） |

---

## 開始分析

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

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