Menú
假說驅動的 CREW Bug 根因調查 —— 自動收集證據、模式比對、假說驗證，全程同步 Notion 任務追蹤。當使用者提到 /bug-investigate、「調查 bug 根因」、「CREW bug 根因分析」時觸發此 Skill。
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
CREW 環境健診 —— 一次性檢查 CREW 所有必要與選配依賴（Node/Git/Notion MCP/Agent Teams/瀏覽器 MCP/config/專案註冊/CLAUDE.md），列出綠黃紅燈與修法。當使用者提到 /crew-doctor、「CREW 環境健診」、「CREW 為什麼不能用」時觸發此 Skill。
瀏覽與探索已有的 .spec/ 規劃文件 —— 深度閱讀、跨任務比較、模式搜尋。當使用者提到 /plan-browse、「瀏覽 .spec 規劃」、「看之前的規劃設計」時觸發此 Skill。
從 .spec/{slug}/plan.md 以 Agent Teams leader-delegate 模式產生程式碼，含退出驗證與錨點有效性檢查，Leader 只協調不寫 code。當使用者提到 /plan-build、「從 spec 產生程式碼」、「plan-build 產碼」時觸發此 Skill。
結案前先跑文件漂移硬關卡（FAIL 擋、WARN 需明示放行），通過後蓋章 verified_at_commit、提交 Git、批次同步 plan.md 與 deploy.sql 到 Notion。當使用者提到 /plan-close、「feature 結案」、「同步 spec 到 Notion 並結案」時觸發此 Skill。
智慧推薦 CREW 當前任務下一步 —— 呼叫 crew-state.py 讀 state.json 算出下一個 /plan-* 指令並轉成人話。當使用者提到 /plan-next、「CREW 下一步指令」、「這個 spec 接下來做什麼」時觸發此 Skill。
CREW 規劃 —— spec / db / arch 三個 pass 把決策與驗收條件寫進 .spec/{slug}/plan.md，DB 設計另產 deploy.sql（零 Notion 呼叫）。當使用者提到 /plan、「CREW 完整規劃」、「一次跑完 spec/db/arch」時觸發此 Skill。
| name | bug-investigate |
| description | 假說驅動的 CREW Bug 根因調查 —— 自動收集證據、模式比對、假說驗證，全程同步 Notion 任務追蹤。當使用者提到 /bug-investigate、「調查 bug 根因」、「CREW bug 根因分析」時觸發此 Skill。 |
AI 主動調查 Bug 根因：收集證據、比對已知模式、建立假說、驗證假說，全程自動更新 Notion「任務追蹤工具」的 Bug 頁面。
沒有根因確認，不能開始修復。 假設不等於根因。「我覺得是 XXX」不夠，需要證據支持。
紀律護欄：
../../references/discipline-preamble.md（通用紀律）＋../../references/anti-rationalizations.md「bug-investigate 專用」＋../../references/boundaries.md「bug-investigate」段＋../../references/state-discipline.md「bug-investigate」段（斷點保險，進度即寫）；有「可以跳過」「應該夠了」的衝動時，停下查表確認是否為已知偏離模式。
/bug-start 建立 Bug 條目（Notion 有「進行中」的 🐞 錯誤）前置檢查：參照 plugin 根目錄
references/prerequisites.md（相對 SKILL.md 為../../references/）執行完整前置檢查（CLAUDE.md + 設定檔 + 專案註冊）。
/bug-investigate # 調查當前進行中的 bug
/bug-investigate NullPointerException # 帶症狀描述開始調查
/bug-investigate --resume # 繼續上次的調查（讀取 Notion 已有內容）
與 /bug-update 相同邏輯：參照 plugin 根目錄 references/locate-bug.md（相對 SKILL.md 為 ../../references/）。
若使用 --resume：讀取已有的「調查過程」區塊，從中斷點繼續。
AI 根據 bug 描述自動收集初始證據，不需使用者介入。
模型與邊界（硬性規則）——完整政策見 plugin 根目錄
references/model-policy.md（相對 SKILL.md 為../../references/）：
- 2.1–2.5 的證據收集用 Agent tool 啟動唯讀 subagent，呼叫時必須實際傳入
{"model": "sonnet"}；只在 prompt 寫「請使用 Sonnet」不算。- 互不依賴的收集項（log／Git 歷史／環境狀態／知識庫與學習搜尋）可在同一則訊息並行派出，回報只給結論與
檔案:行號，不貼大段原文。- 🔴
/bug-investigate全程不修改正式程式碼；只寫 Notion 調查紀錄、.spec/與state.json。- 🔴 沒有根因確認，不得進入修正（不自動觸發
/bug-fix）。- 🔴 不得因第一次假說失敗就升級 Opus（升級條件見 4.4）。
- 🔴 不自動啟動 Dynamic Workflow、不依賴
/effort ultracode；沒有它本 skill 也要能跑完。
根據專案類型決定搜集方式：
# 搜尋專案中的 log 檔案
find . -name "*.log" -mmin -60 -type f 2>/dev/null | head -5
# 若有 Docker 容器
docker ps --format '{{.Names}}' 2>/dev/null | head -5
找到 log 來源後：
grep、docker logs、tail）；輸出量大時導到檔案再用 Read tool 讀搜集策略：
at 行）# 最近 10 筆 commit
git log --oneline -10
# 最近修改的檔案
git log --since="3 days ago" --name-only --format="" | sort | uniq -c | sort -rn | head -10
# 若 stacktrace 提到特定檔案，查該檔案的最近變更
git log --oneline -5 -- <affected-file>
git diff HEAD~5..HEAD -- <affected-file>
與 /bug-start 共用收集指令，參照 plugin 根目錄 references/evidence-collection.md（相對 SKILL.md 為 ../../references/）「共用收集項目」段。
本 skill 專屬差異：2.4 知識庫搜尋的關鍵字來源為「bug 描述和 stacktrace 擷取核心詞」（比 bug-start 的標題關鍵字更廣）；2.5 學習搜尋取 tail -5（bug-start 取 tail -3），且若有匹配的歷史學習 → 除了最後寫入 Notion 之外，AI 應立即顯示：「歷史學習：{insight}（{date}，confidence {N}/10）」，讓使用者在調查當下就看到，不必等到 Notion 寫入才知道。
將收集到的證據寫入 Notion 頁面「調查過程」區塊。
重要：使用 update_content 前，必須先 notion-fetch 取得現有內容，將新內容附加到現有內容後面再寫回，避免覆蓋。
寫入格式：標題為「### [HH:mm] 自動收集的證據」，先列本 skill 專屬的「錯誤 Log」「最近變更」，再接 references/evidence-collection.md「共用 Notion 寫入格式」段的三段共用區塊（環境狀態／歷史參考／歷史學習）：
### [HH:mm] 自動收集的證據
**錯誤 Log**：
{擷取的 ERROR/Exception，含 stacktrace}
**最近變更**（3 天內）：
- {commit hash} {message}（{affected files}）
（接續共用區塊：環境狀態／歷史參考／歷史學習，見 references/evidence-collection.md）
AI 根據收集到的證據，比對已知 bug 模式表（plugin 根目錄 references/bug-patterns.md，相對 SKILL.md 為 ../../references/）。
模式比對、相關程式碼搜尋與關鍵方法閱讀屬唯讀工作：由主對話直接做，或派 subagent 時實際傳入
{"model": "sonnet"}。
讀取 plugin 根目錄 references/bug-patterns.md（相對 SKILL.md 為 ../../references/）的 7 種模式定義，將證據中的症狀逐一比對：
依據證據比對結果：
症狀：NullPointerException at PushService.java:235
模式比對：NPE / NullPointer（confidence: 高）
調查方向：追蹤 null 來源 — 參數傳入？DB 查詢回傳？API 回應？
相關歷史：知識庫中有 2 筆同檔案的 NPE 記錄
寫入 Notion「調查過程 > 初步判斷」：
### [HH:mm] 模式比對
**匹配模式**：NPE / NullPointer
**調查方向**：追蹤 null 來源
- PushService.java:235 的 `accessToken` 可能為 null
- 需確認 token 取得邏輯和過期處理
**歷史參考**：同檔案有 2 筆 NPE 歷史（2026-02-15、2026-01-20）
AI 根據證據和模式比對，提出具體、可驗證的假說：
根因假說 #1：
「PushService.getAccessToken() 在 token 過期後回傳 null，
而 PushService.sendPush() 未檢查 null 就呼叫 token.getValue()」
驗證方式：
1. 讀取 PushService.java 的 getAccessToken() 方法
2. 確認 token 過期邏輯
3. 檢查 sendPush() 是否有 null check
AI 根據驗證方式執行具體操作：
# 讀取相關程式碼
grep -n "getAccessToken\|sendPush\|accessToken" src/main/java/.../PushService.java
使用 Read tool 讀取關鍵方法的完整實作。
若需要 DB 查詢驗證（且 DB MCP 可用）：
使用 execute_sql 查詢相關資料狀態
若需要 API 測試驗證：
curl -s "http://localhost:8080/api/xxx" -H "Authorization: Bearer <token>"
寫入 Notion：
### [HH:mm] 假說 #1 驗證
**假說**：token 過期後 getAccessToken() 回傳 null
**驗證結果**：❌ 否定
**原因**：getAccessToken() 有 null check，過期時會自動 refresh
**新線索**：refresh 呼叫的 API endpoint 回傳 HTTP 401 時沒有 retry 邏輯
若連續 3 次假說都被否定：
⚠️ 已嘗試 3 次假說，全部被否定。
已排除的方向：
1. Token 過期 — getAccessToken() 有自動 refresh
2. API 回傳 401 — retry 邏輯存在但只 retry 1 次
3. 網路超時 — timeout 設定正常（30s）
建議：
• 需要更多資訊（log 時間範圍擴大？不同環境？）
• 可能需要在測試環境重現
• 或請熟悉此模組的同事協助
要繼續調查（Sonnet）、升級深度根因推理（Opus）、還是暫停？
model: "sonnet" 繼續調查。完整政策見 plugin 根目錄 references/model-policy.md（相對 SKILL.md 為 ../../references/）。
預設一律 model: "sonnet"，🔴 不得因第一次假說被否定就升級。只有符合下列任一條件才允許升級：
升級前，Sonnet 必須先整理下列交接（寫入 Notion「調查過程」並附在派工 prompt 內）：
## 深度調查交接
### 已確認事實
- ...
### 已排除假說
- ...
### 相關檔案與方法
- ...
### 關鍵證據
- ...
### 尚未解答的問題
- ...
派工規則：用 Agent tool 啟動 subagent 並實際傳入 {"model": "opus"}；Opus 只針對「尚未解答的問題」推理，
🔴 不得重做全部證據收集，🔴 不得修改正式程式碼（本 skill 仍是唯讀調查）。
假說確認後，將根因寫入 Notion「根因分析」區塊：
## 🧠 根因分析
- **問題根因**：LINE API 的 access token refresh 端點偶爾回傳 HTTP 503，
而 getAccessToken() 的 retry 邏輯只重試 1 次且未處理 503 狀態碼，
導致第二次推播時 accessToken 為 null。
- **問題檔案**：PushService.java:235
- **問題程式碼**：
```java
// retry 只處理 401，未處理 503
if (response.getStatusCode() == 401) {
return refreshToken();
}
return null; // ← 503 時走到這裡
同時更新 Notion 頁面屬性：
- 根因分類 → 自動推斷（此例：「第三方API」）
### 6. Phase 5：調查報告
產出結構化調查報告，寫入 Notion 頁面底部：
```markdown
---
## 📋 調查報告
| 項目 | 值 |
|------|-----|
| 調查日期 | {YYYY-MM-DD} |
| 調查時長 | {N} 分鐘 |
| 假說嘗試 | {N} 次（確認第 {N} 次） |
| 證據來源 | Log + Git + 知識庫 |
### 時間線
1. [HH:mm] 收集證據 — stacktrace + 最近 commit
2. [HH:mm] 模式比對 — NPE 模式，追蹤 null 來源
3. [HH:mm] 假說 #1 否定 — token refresh 正常
4. [HH:mm] 假說 #2 確認 — 503 未處理
5. [HH:mm] 根因確認
調查報告產出後，AI 自我檢查是否有無法自行確認的關鍵問題。只在以下情況觸發：
不觸發的情況（直接跳到回傳結果）：
❓ 調查中有 {N} 個問題需要釐清：
1. {問題描述}
背景：{為什麼需要釐清，對根因判斷的影響}
2. {問題描述}
背景：{為什麼需要釐清}
限制 1-3 個問題，只列真正影響後續修復方向的關鍵問題。
根據釐清結果，可能：
然後進入回傳結果。
Bug 調查完成！
📋 根因：LINE API refresh 回傳 503 未處理
📊 調查過程：2 次假說，第 2 次確認
🔗 Notion：{頁面連結}
根據調查結果動態建議後續指令：
根因已確認 → 建議修復：
建議後續：
• /bug-fix — 修復並驗證（根因已確認，可以開始修復）
根因已確認但需要更多資訊 → 建議補充：
建議後續：
• /bug-update <補充> — 先補充更多環境資訊
• /bug-fix — 或直接開始修復
根因未確認（3-Strike 暫停後）→ 建議擴大調查：
建議後續：
• /bug-investigate --resume — 繼續調查（有新線索時）
• /bug-update <新線索> — 補充新發現的資訊
investigate skill 或 superpowers:systematic-debugging/bug-fix/bug-update/crew-doctornotion-fetch 取得現有內容，附加新內容後再寫回。