principle-fix-root-causes | 從症狀追到第一個錯誤

本頁以 pstack-claude 0.9.126 為基準。原文標示 user-invocable: false，通常由 poteto-mode 按需讀取。以下以自然語言套用原則，不提供獨立命令。

定位與適用情境

症狀是錯誤狀態變得可見的位置。根因則是系統第一次做錯決定，或未處理原本應處理的合法狀態的位置。修正應落在後者，不能只讓錯誤訊息消失。

例如工作清單在同一次執行中正常，關閉程式再啟動後卻無法顯示。顯示層的空值存取只是症狀。原因可能與持久化狀態（Persisted State）有關，但必須由實際錯誤與資料證明，不能直接判定是快取壞掉。

這個原則不反對所有防護判斷（Guard）。若新使用者本來就可以沒有任何工作，顯示空清單是合法需求。若空值來自錯誤還原，顯示層略過該筆工作就可能只是掩蓋資料損失。

準備

提供最短重現流程，包含建立工作、關閉、重啟與讀取清單的順序。
保留實際錯誤訊息、堆疊與觸發輸入，不先清除失敗現場。
在測試副本保存設定、快取、鎖定檔與序列化狀態，並去除敏感資料。
明確列出哪些空狀態屬於合法情況，哪些違反系統原有不變條件（Invariant）。不確定的部分先查實作與呼叫端。

操作步驟

先重現症狀。 在隔離測試資料上執行完整重啟流程，確認能看到相同錯誤。記錄顯示前的狀態，不以「偶爾好了」當作已修復。
逐段追問為何。 從顯示層回查資料載入、狀態還原與保存流程。遇到缺少證據的轉換點就加診斷，讀取實際錯誤與輸入輸出，直到找到第一個錯誤決策，而不是停在其後果。
判定觸發狀態是否合法。 若是合法的空工作清單，未能顯示空狀態的位置就可能是根因。若保存檔有完整工作，但還原後必要欄位遺失，應追查還原規則，而不是在顯示層跳過資料。這些是不同證據分支，不能預先選定答案。
修正錯誤產生處並找同類問題。 依證據修改保存、還原或合法狀態處理，搜尋其他具有相同錯誤模式的路徑。在核准範圍內一併修正，不只補眼前一筆資料。
重驗並留下更便宜的訊號。 重跑原本失敗的重啟情境、正常情境與合法空狀態。若關鍵事實很難查到，提出能常態存在的低成本診斷訊號，讓下次更早看見同類錯誤。

可直接使用的提示詞

套用 principle-fix-root-causes。
工作清單同次執行正常，關閉再啟動後失敗。
輸入包含重現順序、實際錯誤、測試用保存檔與相關呼叫路徑。
先在隔離資料重現，再逐段對照保存、還原與顯示前的實際狀態。
不要先清快取、補空值 guard、增加重試或吞掉錯誤。
先判定觸發狀態是否合法，找出第一個錯誤決策，再提出修正。
搜尋相同錯誤模式，列出核准範圍內受影響的路徑。
驗收包含重啟流程、正常流程、合法空清單與資料完整性。
未取得的證據請明示。不要把重啟後失敗直接當成持久化錯誤的證明。

預期結果與驗收

預期得到一條能由證據追溯的因果鏈，清楚區分症狀、錯誤狀態的產生處與修正位置。缺陷測試應先能重現原問題，再因根因修正而通過。

驗收不只是畫面不再拋錯。測試保存資料中的合法工作也應能完整還原並顯示，合法空清單則能顯示正確空狀態。同類錯誤搜尋應列出結果與範圍，不能用「應該只有這裡」代替查核。

常見誤用是把所有失敗改成回傳空清單，或以重試、截斷數值、丟棄狀態來讓測試變綠。若這些行為只是遮住不應存在的狀態，根因仍在。需要長篇文字辯解的繞路修補，也應回頭檢查程式是否修錯位置，而不是刪掉解釋就算完成。

限制與權限

重啟後失敗時應優先檢查持久化狀態，但這只是調查方向。缺少當時狀態或無法重現時，應交付已知事實與下一個觀察點，不宣稱已確認根因。

不要直接刪除設定、快取或鎖定檔來「修好」正式環境。持久化資料修復與遷移可能不可逆，須另外確認。診斷紀錄應避免敏感資料；本原則也不授權移除專案要求的有效文件與準確功能註解。

延伸閱讀與來源

工作清單案例是本頁教學示例。文中的可能原因不是對任何實際專案的診斷結論。