除錯與修復 (Debug and Fix)

找出根本原因，然後加以修復。此 Skill 會系統化地調查 Bug — 在提出修復方案之前追蹤完整的因果鏈 — 並可選擇以測試先行 (test-first) 的規範來實作修復。

Bug 描述 (<bug_description>) 是呼叫此 Skill 時傳入的輸入內容 — 亦即目前 prompt 或對話中待診斷的失敗問題，無論是使用者直接提供，或是由上層 Skill 所傳入（例如 mode:pipeline 下的 ce-babysit-pr / lfg，會將失敗的作業與 log 結尾作為引數傳入）。它可能是失敗問題的描述、mode: token，或是 issue 參照（#123、org/repo#123 或 issue URL）。本 Skill 後續皆以 <bug_description> 稱之；若未提供任何內容，請將 <bug_description> 視為空白。

初始化設定 (Setup)

請在本次呼叫開始時（在分派任何 subagent 之前）執行一次，並遵循其輸出的指令 — 除非指令與本 Skill 自身關於詢問使用者問題的規則產生衝突。無論該規則是僅適用於非互動模式或適用於所有模式，皆以本 Skill 的規則為準，且不得詢問會造成阻塞的問題。請勿在同一次呼叫中重複執行；後續若呼叫本 Skill 或其他 Skill，會各自執行其設定。若無可用之 Node 執行環境，本 Skill 將維持原本流程繼續執行。

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context script failed; continue with the skill's normal behavior";
else
echo "no Node runtime; continue with the skill's normal behavior";
fi

執行模式 (Mode)

預設模式為互動模式 (interactive) — 先進行調查，接著使用下方撰寫的 Phase 2 修復選擇關卡 (fix-choice gate) 與 Phase 4 交接提示。

mode:pipeline（由 ce-babysit-pr 或 lfg 等協調器設定）：完全以非互動方式執行。在解析前，請從 <bug_description> 中移除 mode:pipeline token。閱讀並遵循 references/pipeline-mode.md — 它會以保守的預設值覆寫本 Skill 中所有「詢問使用者」的點，將 Phase 2 的修復關卡替換為「修復收斂的 Bug，暫緩發散的 Bug」，並將 Phase 4 的提示替換為結構化回傳。在 pipeline 模式下，切勿呼叫會阻塞流程的詢問工具。

核心原則 (Core Principles)

先調查，後修復。 在你能無縫解釋從觸發點到症狀的完整因果鏈之前，請勿提出修復方案。「不知為何 X 導致了 Y」屬於解釋斷層。
對不確定的環節提出預測。 當因果鏈包含不確定或不明顯的環節時，請建立預測 — 亦即在不同程式碼路徑或情境中也必須成立的事實。若預測錯誤但修復「有效」，代表你只找到了症狀，而非根本原因。當因果鏈顯而易見時（如缺失 import、明確的 null 參照），因果鏈本身的解釋即已足夠。
一次只做一項變更。 每次只驗證一個假設、修改一個地方。如果你一次修改多個地方只為了「看看有沒有改善」，請立刻停止 — 那是散彈槍式除錯 (shotgun debugging)。
卡住時，診斷原因 — 而非盲目硬推。

產物根目錄 (Artifact Root)

本 Skill 可能會在 <root>/residual-review-findings/ 下記錄殘留檢查結果，並在 <root>/solutions/ 下記錄累積的經驗心得。當你首次建構 <root>/ 路徑時（依據下方區塊），才去解析 <root> 的實際路徑，切勿提前解析。寫入 <root>/... 或讀取 <root>/solutions/ 皆算作建構 <root>/ 路徑，因此兩者皆會觸發解析；只有完全不碰觸任何 <root>/ 路徑的執行（如僅使用暫存區或無 repo 的流程）才會跳過此步驟。

在建構任何產物路徑之前，先解析 CE 產物根目錄 <root>。

讀取 <repo-root>/.compound-engineering/config.local.yaml 中的 docs_root，若無則讀取 config.yaml；以第一個非空值為準（<repo-root> = git rev-parse --show-toplevel）。若皆未設定 -> <root> 預設為 docs（與先前完全一致）。
驗證已設定的值：必須是相對於 repo 的目錄，且其經 symlink 解析後的真實路徑必須保持在 repo 內部，既不能是 repo 根目錄，也不能位於 .git/ 下。否則請停止執行並回報包含 docs_root 及其設定值的錯誤訊息 -- 切勿直接退回使用 docs。
使用 <root> 作為唯一的產物位置：若不存在請建立之，並將每個路徑建構為 <root>/<subdir>（搭配本 Skill 自己的子目錄），且絕不重複讀取 docs。

執行流程 (Execution Flow)

階段 (Phase)	名稱	目的
0	審查分類 (Triage)	解析輸入、擷取引用的 issue（若有），進入調查流程
1	調查 (Investigate)	重現 Bug，追蹤程式碼執行路徑
2	根本原因 (Root Cause)	建立假設並對不確定環節提出預測、進行驗證、因果鏈關卡、智慧升級機制
3	修復 (Fix)	僅在使用者選擇修復時執行。以測試先行原則進行修復，並包含工作區安全檢查
4	交接 (Handoff)	提供結構化摘要，並提示使用者下一步行動

除了 Phase 0 中針對微小 Bug 的快速路徑之外，不跳過任何後續階段 — 複雜的 Bug 自然會在各階段投入更多時間。不再另外劃分複雜度等級。

Phase 0: 審查分類 (Triage)

解析輸入內容，並得出明確的問題陳述。

若輸入內容引用了 issue 追蹤系統，請擷取其詳細資訊：

GitHub (#123, org/repo#123, github.com 或 GitHub Enterprise 的 issue URL)：從 <bug_description> 解析 issue 參照，並使用 gh issue view <number> --json title,body,comments,labels 擷取。若為 URL，直接將 URL 傳給 gh（它會自動對應其設定的主機，包含 GHE）。
其他追蹤系統 (Linear URL/ID, Jira URL/key, 任何追蹤系統 URL)：嘗試使用現有的 MCP 工具或透過擷取 URL 內容來取得。若擷取失敗 — 例如驗證問題、缺乏工具、非公開頁面 — 請請使用者貼上相關 issue 內容。請確保擷取內容包含完整的留言討論串，而不僅是開頭的描述。

閱讀完整對話 — 包含原始描述以及每一條留言，特別注意最新留言。留言經常包含更新後的重現步驟、縮小的範圍、先前失敗的嘗試、額外的堆疊追蹤，或是轉向不同的疑似根本原因；若僅將首篇貼文視為全貌，往往會導致調查方向偏差。請從整合後的討論串中提取已回報的症狀、預期行為、重現步驟與環境細節。接著進入 Phase 1。

其他所有情況（堆疊追蹤、測試路徑、錯誤訊息、異常行為描述）：輸入內容本身即為問題陳述。

微小 Bug 的快速路徑 (Trivial-bug fast-path)： 當問題明確後，評估是否需要動用完整架構。若原因可直接從輸入中看出一端（單一檔案的打字錯誤、缺失 import、明顯的 null 存取或可透過單行修復的 off-by-one 錯誤），且驗證不需要深度追蹤，請直接呈現原因與建議的單行修復方案，並在編輯前執行 Phase 2 的 立即修復 / 僅診斷 (Fix it now / Diagnosis only) 使用者選擇關卡 — 快速路徑是為了省去調查手續，而非省去使用者對於是否套用修復的選擇權。若使用者選擇修復，請執行 Phase 3 的 工作區與分頁檢查 (Workspace and branch check)（確認未提交的變更以及預設分頁的建立分頁提示），套用修復方案，留下一行說明原因的簡記，並跳至 Phase 4 的結構化摘要。若僅需診斷，寫出摘要後即停止。如有疑慮，請執行完整架構；判斷出錯誤的根本原因所付出的代價，遠高於省下的幾分鐘手續。

否則，請進入 Phase 1。

提問原則：

預設不提出問題 — 先行調查（閱讀程式碼、執行測試、追蹤錯誤）
僅在存在真正的歧義阻礙調查，且無法透過閱讀程式碼或執行測試釐清時，才提出詢問
提問時，僅提出一個具體問題

先前嘗試感知： 若使用者透露過先前失敗的嘗試（例如「我試過了」、「一直失敗」、「卡住了」），請在調查前詢問他們已經嘗試過哪些方法。這能避免重複失敗的做法，也是少數適合先提問的情境之一。

Phase 1: 調查 (Investigate)

1.1 重現 Bug

確認 Bug 存在並瞭解其行為。執行測試、觸發錯誤、遵循回報的重現步驟 — 採取與輸入相符的方式。

瀏覽器相關 Bug： 若有安裝 agent-browser 請優先使用。否則使用任何可行的工具 — MCP 瀏覽器工具、直接 URL 測試、擷取螢幕截圖等。
需要人工設定： 若重現需要 Agent 無法單獨建立的特定條件（資料狀態、使用者角色、外部服務、環境設定），請記錄精確的設定步驟並引導使用者完成。即使流程完全是人工操作，清晰的逐步說明也能節省大量時間。
嘗試 2-3 次後仍無法重現： 閱讀 references/investigation-techniques.md 以取得處理間歇性 Bug 的技巧。
在此環境下完全無法重現： 記錄已嘗試的項目以及似乎缺失的條件。
撰寫重現測試： 使用當前專案的指令以及任何適用於子目錄範圍的指令；在新增涵蓋範圍之前，務必先檢查現有測試。當現有測試已能捕捉該 Bug 時，使用該失敗測試；當現有測試擁有該合約但預期不符時，更新現有測試；當測試被過度 mock 而原本應該捕捉到該 Bug 時，強化該測試；或者僅在沒有合適的現有測試時，新增一個最小化的獨立測試。所選的測試必須在當前 Bug 下失敗，並在套用正確行為後通過；請為其賦予具描述性的名稱，使失敗訊息本身就能解釋該 Bug。

1.2 驗證環境正常狀態 (Verify environment sanity)

在進行深度程式碼追蹤前，請確認環境與你的預期一致：

已切換至正確的分頁；無無意留下的未提交變更
依賴項已安裝且為最新狀態（bun install、npm install、bundle install 等）— 過期的 node_modules/vendor 是常見的干擾源
預期的直譯器或執行階段版本（對照 .tool-versions、.nvmrc、Gemfile 等與實際運行的版本）
必要的環境變數已存在且非空白
無過期的建置產物（dist/、.next/、來自早期分頁編譯出的二進位檔）
依賴的在地服務（資料庫、快取、佇列）運行於預期版本 （當 Bug 合理涉及它們時）

1.3 追蹤程式碼路徑 (Trace the code path)

從症狀點開始向後追蹤資料流，直到找出有效狀態首次變為無效狀態的位置。閱讀程式碼結構以建立假設，然後透過觀察到的實際值進行驗證 — 不要僅憑程式碼空想推論。

具體做法：

由下而上閱讀堆疊追蹤 (stack trace)，開啟每個 frame 的原始碼。最底部的 frame 是症狀點；根本原因位於上游某處。
找出輸入資料已經無效的第一個 frame — 那是需要排查的上限邊界。
在該 frame 周圍建立觀察點：加入針對性的 log/列印敘述、除錯器中斷點 (breakpoint)，或在函式入口/出口擷取實際數值的測試斷言 (assertion)。假設的數值會騙人，觀察到的數值不會。
逐步檢查邊界，直到有效輸入變為無效輸出。該轉換點即為根本原因所在位置。

不要停在第一個看起來有問題的函式 — 根本原因是產生不良狀態的源頭，而非首次觀察到不良狀態的位置。

追蹤時：

檢查你正在閱讀的檔案最近的變更：git log --oneline -10 -- [file]
若 Bug 看起來像是退化問題 (regression，「以前是正常的」)，請使用 git bisect（參閱 references/investigation-techniques.md）
檢查專案的可觀測性工具 (observability tools) 以取得額外證據：
- 錯誤追蹤系統 (Sentry, AppSignal, Datadog, BetterStack, Bugsnag)
- 應用程式日志 (logs)
- 瀏覽器

ce-debug

相關技能