diagnose

diagnose 技能總覽

diagnose 是用來做什麼的

diagnose 技能是一套結構化的除錯流程，適用於 bug 很難定位、測試不穩定，或效能明顯退步，且你需要一種可靠方法來釐清根因的情境。它特別適合想要的不只是一般 debug this 提示的 agent 與開發者：你需要的是一條可重複的路徑，從症狀一路走到重現，再到假設、觀測、修正與回歸測試。

誰應該安裝它

如果你常在失敗狀況間歇出現、與環境相關，或只會在 UI 或接近 production 的流程中才看得出來的 codebase 上工作，就很適合安裝 diagnose 技能。它特別適合 Debugging 工作情境：當你不能只靠快速掃一遍程式碼，而是需要在動手改實作前，先建立一個明確的 pass/fail 訊號時。

diagnose 的不同之處

diagnose 技能的核心，是先建立快速回饋迴圈。這就是它最大的差異：它優先重視可重現性與可觀測性，而不是過早改 code。它也會鼓勵使用專案的 glossary 和 ADR，讓 agent 對齊領域語言，而不是靠猜測模組用途。

如何使用 diagnose 技能

安裝 diagnose 技能

先使用 repo 裡提供的 skill install 路徑，然後確認 skill 檔案已出現在你的本機 skills 目錄中。以這個 repo 來說，文件中提供的安裝指令是：
npx skills add mattpocock/skills --skill diagnose

安裝完成後，先從 SKILL.md 開始，再檢查會影響工作流程的支援檔案。最值得看的 repository 路徑是 scripts/hitl-loop.template.sh，以及任何解釋術語、架構或測試邊界的專案特定文件。

把模糊的 bug 變成好的 diagnose 提示詞

diagnose 技能最有效的用法，是你的輸入包含具體症狀、發生位置，以及成功時應該長什麼樣子。弱的提示詞會說「diagnose this」。更好的提示詞會說：
「診斷為什麼 staging 環境中的 export button 有時候會失敗。請在 browser 裡重現它，把步驟縮到最少，判斷問題是 server-side 還是 client-side，並在可行時補上 regression test。」

使用 diagnose 時，請包含：

• 實際觀察到的失敗模式
• 發生問題的 environment
• 已知正常或已知異常的範例
• 你是否可以執行 tests、dev server，或 browser harness

建議先讀的工作流程與檔案

先從 SKILL.md 開始，理解整個 loop；如果 bug 需要 human-in-the-loop 重現，再讀 scripts/hitl-loop.template.sh。當 agent 需要你逐步點選、擷取錯誤，或在它解析結果時幫忙確認行為，這個 script 特別有用。

實務上可以這樣做：

1. 找出最小範圍的失敗情境
2. 建立可重複的 deterministic 訊號
3. 一次只測一個 hypothesis
4. 只在訊號不清楚的地方加上 instrumentation
5. 用 regression test 或可重播的 harness 把修正鎖住

能明顯提升結果的提示

如果你想讓 Debugging 的 diagnose 結果更好，請告訴 agent 允許使用哪些工具：unit tests、CLI commands、HTTP requests、browser automation，或重播已擷取的 traces。也請說明 bug 是 deterministic、flaky，還是效能相關，因為這會改變應該怎麼建構這個 loop。可觀察訊號越具體，agent 花在猜測上的時間就越少。

diagnose 技能 FAQ

diagnose 比一般的 debug 提示詞更好嗎？

通常是，尤其在問題難以重現或跨越多層的時候。一般提示詞可能會直接跳到改 code；diagnose 則是先建立證據，這對 flaky bugs 和 regressions 更安全。

什麼時候不該用 diagnose？

如果是很直接的語法錯誤、明顯的 null check，或只牽涉單一檔案、而且失敗原因已經完全清楚的微小修正，就不必用 diagnose。這種情況下，完整 diagnose 指南的額外成本可能超過你的需求。

diagnose 技能適合初學者嗎？

可以，只要你能清楚描述症狀並執行建議的檢查。當你不確定 bug 在哪裡時，它尤其有幫助，因為它替 investigation 提供結構，而不是要求你先有很深的背景知識。

diagnose 適用於所有 stack 嗎？

它適用於多數能透過 test、script、browser 檢查，或可重播輸入來暴露成功/失敗結果的 stack。若系統沒有可重複、可判定的方式來觀察成敗，它就比較不實用，因為這個技能本身依賴可靠的 feedback loop。

如何改善 diagnose 技能

給這個技能更強的起始訊號

最大的改善來自更完整的重現細節。不要只說「the app is broken」，而是提供精確動作、資料形狀，以及預期結果與實際結果。如果你有 logs、失敗的 URL、payload 範例，或最小化 fixture，請一開始就附上。

在要求根因之前先消除歧義

如果可能的失敗有好幾種，先指明你要先診斷哪一種。舉例來說，把「button 沒反應」和「request 回傳 500」以及「page 很慢」分開。diagnose 最適合的情況，是初始問題陳述能對應到單一、可觀察的失敗模式。

用第一次輸出決定下一個實驗

拿到第一輪結果後，可以透過回答三個問題來改善 diagnose 技能的成果：重現是否已經變成 deterministic、假設是否已經縮小搜尋範圍，或者你是否需要不同的訊號？如果輸出還是太模糊，不要再要求一個更大的總結；改成要求更小的 harness、不同的 test seam，或 browser/CLI 的重播路徑。