bug-close

name	bug-close
description	修復 Bug 後從 Git diff 自動擷取修復細節並更新 Notion 任務追蹤頁面（僅限 bug 型任務）。當使用者提到 /bug-close、「關閉 bug」、「bug 結案並補修復細節」時觸發此 Skill。

Bug Close — 結案並自動補齊修復細節

修復 Bug 並 commit 後，從 Git 自動擷取修改資訊，更新 Notion「任務追蹤工具」的 Bug 頁面，並在「Bug 知識庫」同步建立精簡條目。

---

前置條件

• 已使用 /bug-start 建立 Bug 條目（Notion「任務追蹤工具」中有狀態為「進行中」的 🐞 錯誤條目）
• 修復程式碼已 commit

前置檢查：參照 plugin 根目錄 references/prerequisites.md（相對 SKILL.md 為 ../../references/）執行完整前置檢查（CLAUDE.md + 設定檔 + 專案註冊）。

---

流程

1. 從 Git 擷取修復資訊

依序執行以下指令：

# 當前分支
git branch --show-current

# 最近 10 筆 commit（供使用者選擇範圍）
git log --oneline -10

# 預設取最近 1 個 commit 的變更
git diff HEAD~1..HEAD --stat

# 完整 diff（用於摘要化）
git diff HEAD~1..HEAD

若使用者指定 commit 範圍（如 HEAD~3..HEAD），使用指定的範圍。

2. Merge 引導（Feature Branch → DEV）

結案前，若偵測到修復在 feature branch 上進行（同時滿足：當前分支是 Bug 的修復分支、屬於 feature/hotfix 分支、能取得 DEV 分支名稱），引導使用者 merge 回開發分支；條件不滿足或使用者選擇跳過則直接進入原有結案流程。完整判斷條件、互動式引導文案、執行步驟見 plugin 根目錄 references/merge-guide.md（相對 SKILL.md 為 ../../references/）。

3. 搜尋對應的 Bug 條目

搜尋 Notion「任務追蹤工具」（Data Source ID 見設定檔）中符合條件的條目：

使用 notion-search 搜尋：

• 條件：狀態為「進行中」且任務類型包含「🐞 錯誤」

同時取得 Git Repo 識別碼（從 git remote get-url origin 解析），用於輔助篩選同一專案下的 Bug。

優先匹配邏輯：

1. 若「修復分支」欄位與當前 Git branch 完全匹配 → 自動選定
2. 若有多個候選，優先顯示與當前 Git Repo 所屬專案相關的條目
3. 若有多個候選 → 列出清單讓使用者選擇
4. 若無候選 → 提示使用者先用 /bug-start 建立

4. 退出驗證門檻

結案前執行 4 項檢查，確保修復品質達標：

#	檢查項	驗證方式	失敗處理
C1	根因分析已填寫	Notion 頁面「根因分析」區塊非空	WARN：提醒補填，允許繼續但狀態強制為「測試中」
C2	修復 commit 存在	git log --oneline -10 中有相關 commit	BLOCK：必須先 commit
C3	迴歸測試存在	grep -rF "Regression: {Bug 標題}" --include="*Test.java" --include="*.test.*" --include="*.spec.*" .（{Bug 標題} = Notion 頁面標題，需與 /bug-fix 產出的 attribution 註解 // Regression: {Bug 標題} 用字完全一致；grep 需在專案根目錄執行）	WARN：建議用 /bug-fix 產出
C4	驗證項目至少一項勾選	Notion 頁面 checkbox 狀態	WARN：提醒驗證

驗證結果顯示：

退出驗證：
  ✅ C1 根因分析已填寫
  ✅ C2 修復 commit 存在（abc1234）
  ⚠️  C3 無迴歸測試
  ⚠️  C4 驗證項目未勾選

結論：可結案，建議處理 C3 和 C4

若 C1 為 WARN → 目標狀態選項中移除「已完成」，只能選「測試中」。

5. 互動式補充資訊

詢問使用者（若未在初始輸入中提供）：

1. 根因分類：邏輯錯誤 / 資料異常 / 設定問題 / 第三方API / 效能 / 權限 / 前端UI
2. 根因說明：一句話描述為什麼會發生（例如：「employees 表的 status 欄位被誤設為 99 導致查詢不到」）
3. 目標狀態：測試中（預設）或 已完成

6. 產出修復摘要

根據 git diff 自動產出以下內容：

修改檔案清單：從 --stat 擷取，格式化為列表 修改說明：根據 diff 內容，以分層架構摘要（如 Java 專案的 Controller / Service / DAO 層） 修改後程式碼：擷取關鍵的程式碼變更片段（不超過 50 行）

7. 更新 Notion Bug 頁面

使用 notion-update-page 更新條目：

Properties 更新：

欄位	值
狀態	使用者選擇（預設「測試中」）
根因分類	使用者選擇的分類
修復分支	當前 Git branch（若原本為空）

Content 更新：

使用 update_content 指令，搜尋模板中的空白區塊並填入：

1. 「根因分析」區塊：

   • 問題根因 = 使用者提供的根因說明
   • 問題檔案 = 從 diff stat 擷取的檔案路徑
   • 問題程式碼 = diff 中被刪除的關鍵程式碼

2. 「修復方案」區塊：

   • 修改檔案清單 = 格式化的檔案列表
   • 修改說明 = 自動產出的分層摘要
   • 修改後程式碼 = diff 中新增的關鍵程式碼
   • 修復 Commit = commit hash + message
   • 修復分支 = branch 名稱

8. 同步到知識庫

在「Bug 知識庫」資料庫建立一筆精簡條目（Data Source ID 見設定檔）：

欄位	值
Name	Bug 標題
Tags	根據 bug 內容自動推測相關標籤
難易度	根據修改檔案數和 diff 行數判斷：≤3 檔案且 ≤50 行 → 普通(2~4h)，否則 → 困難(4~6h)
專案資料庫	同一專案
參考連結	任務追蹤工具的頁面 URL

頁面內容為精簡版：

**根因**：{根因說明}

**解法**：{修復摘要，2-3 句話}

**關鍵程式碼**：
（修改前後的關鍵差異）

若設定檔中「Bug 知識庫」ID 為空，則跳過此步驟。

9. 學習捕捉

AI 分析本次 bug 的根因、修復和調查過程，判斷是否有可複用的洞察。

學習類型

類型	說明	範例
pattern	可複用的 bug 模式	「此專案的 token 過期 bug 常發生在推播模組」
pitfall	應避免的陷阱	「LINE API 的 503 需要特別處理，不能只處理 401」
architecture	架構層面的洞察	「PushService 和 TokenService 的耦合度太高」
environment	環境相關的知識	「正式環境的 LINE API rate limit 是 100 req/min」

學習格式

寫入 ~/.claude-company/bug-workflow/learnings/{project-slug}.jsonl：

{
  "date": "2026-04-24",
  "skill": "bug-close",
  "bug_title": "推播排程發送失敗",
  "root_cause": "LINE API refresh 回傳 503 未處理",
  "pattern": "third-party-api",
  "type": "pitfall",
  "insight": "LINE API 的 refresh token 端點偶爾回傳 503，retry 邏輯必須涵蓋 503 且加入 exponential backoff",
  "confidence": 9,
  "files": ["PushService.java"],
  "notion_url": "https://www.notion.so/xxx"
}

project-slug 來自 Git Repo 識別碼（/ 替換為 -）。每行一筆 JSON（JSONL 格式）。

自動 vs 手動

AI 自動判斷是否有學習價值：

• 有明確洞察 → 自動寫入，在結案訊息中顯示「學習已捕捉：{insight}」
• 不確定 → 詢問使用者：「這次 bug 有什麼值得記下來的嗎？」
• 太泛/太明顯 → 不記錄（如「要注意 null check」太泛，不記）

學習目錄建立

mkdir -p ~/.claude-company/bug-workflow/learnings

若目錄不存在，首次使用時自動建立。

10. 標記結案狀態

把 .spec/{slug}/state.json 的 close 步驟標為完成（見 ../../references/state-discipline.md）：

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/crew-state.py" set \
  --slug {slug} --step close --status done

標記後 /plan-next 與 SessionStart 開場提醒就不會再把它列為未結案。

🔴 不要刪除 state.json。舊版的 handoff.md 是純過程性檔案、結案即刪；state.json 是任務的結案紀錄，要保留並入版控 —— /plan-deploy-confirm 事後要靠它查 steps.close.status 與 deploy 的執行進度，刪掉就查不到「這個任務的 SQL 到底跑了沒」。

與下方回傳結果的 Git 分支清理提示同屬結案收尾動作。

11. 回傳結果

向使用者回傳：

• 更新後的 Notion 頁面連結
• 變更摘要（修改了幾個檔案、根因分類、目前狀態）
• 知識庫條目連結（若有同步）
• Merge 結果（若「Merge 引導」步驟執行了 merge）：「已合併 feature/xxx → {dev_branch}」
• 提示後續操作：

  Bug 已結案！後續事項：
  {若有 merge} • git push origin {dev_branch}  — 推送合併結果
  • 驗證完成後請在 Notion 頁面勾選驗證項目
  • 若上線後問題復發，可使用 /bug-update reopen 重新開啟
  {若 feature branch 不再需要} • git branch -d feature/xxx  — 清理分支
  

---

何時不用

close 組 —— 本 skill 只結 bug 型任務；feature/.spec 任務結案用 /plan-close。

• feature/.spec 任務結案 → 用 /plan-close
• 尚未修完、只想中途補調查資訊 → 用 /bug-update
• Jira 單結案（非 Notion bug 流程）→ 用 jira MCP（mcp-atlassian）或 jira-from-pm
• 未建立 Notion bug 條目就想結案 → 先執行 /bug-start

---

Gotchas

• update_content 找不到區塊標題：如果使用者手動修改過 Notion 頁面（例如把「🧠 根因分析」改成「根因分析」），update_content 的搜尋模式會匹配失敗。遇到這種情況，改用 replace_content 重寫整個頁面內容（先讀取現有內容合併）。
• diff 包含二進位檔案：git diff 遇到圖片、Excel 等二進位檔案會顯示 Binary files differ，不要把這些納入「修改後程式碼」區塊。只擷取文字類檔案的 diff。
• 知識庫 Tags 推測容易偏離：自動推測 Tags 時，Claude 傾向選太多標籤。限制最多 3 個，優先選與 bug 直接相關的模組標籤（如「推播」、「排程」），避免選泛用標籤（如「API」、「效能」除非確實是那類問題）。
• commit 範圍判斷：使用者可能在修 bug 過程中穿插了不相關的 commit（如 merge commit）。若 git log --oneline -10 中混有非修復用途的 commit，應先確認正確範圍再擷取 diff，不要盲目用 HEAD~1..HEAD。
• 難易度判斷閾值偏保守：「≤3 檔案且 ≤50 行 → 普通」的規則在重構型修復（改很多檔但每個只改一行）時會誤判為困難。若 diff 中大部分是 import 變更或 rename，應降級為「普通」。
• Merge 引導是建議不是強制：「Merge 引導」步驟可以跳過。有些場景使用者會在其他工具（如 GitLab MR）做 merge，不需要在 CLI 操作。
• dev_branch 跨 plugin 讀取：Merge 引導需要讀取 feature-workflow 的設定檔取得 dev_branch，但 bug-close 是 bug-workflow 的 skill。讀取失敗時顯示簡化提示，不阻擋流程。
• Merge 衝突不自動解決：衝突屬於需要人類判斷的操作，遇到衝突時顯示衝突檔案列表、暫停結案流程，等使用者解決後重新執行 /bug-close。
• 不自動 push：merge 完成後不自動執行 git push，因為 push 會影響遠端共享狀態，需使用者明確操作。

參考 examples/good-closure-report.md 了解理想的結案報告結構和品質。

---

邊界情況

• 設定檔不存在：提示使用者先執行 /bug-setup 完成初始設定
• 無 commit 可擷取：提示使用者先 commit 修復程式碼
• Notion 頁面內容與模板不符：處理方式見 Gotchas 的「update_content 找不到區塊標題」
• 使用者想手動補充調查過程：提示可直接在 Notion 頁面編輯「調查過程」區塊
• diff 過大（> 500 行）：僅摘要檔案清單和關鍵變更，不貼完整 diff
• merge 衝突：處理方式見 Gotchas 的「Merge 衝突不自動解決」
• feature-workflow 未安裝或未設定：原因與處理方式見 Gotchas 的「dev_branch 跨 plugin 讀取」
• DEV 分支在本地不存在：嘗試 git checkout {dev_branch}（git 會自動從 remote tracking 建立本地分支），若失敗則 git fetch && git checkout {dev_branch}
• Feature branch 是否應刪除：不自動刪除，僅在結案提示中建議。若 Feature 仍在開發中，刪除分支會造成問題