打破循環 - 深度錯誤分析
當除錯完成後，使用此方法進行深度分析，以打破「修復錯誤 -> 忘記 -> 重複」的循環。
分析框架
從以下 5 個面向分析你剛才修復的錯誤：
1. 根本原因類別
此錯誤屬於哪一類？
| 類別 | 特徵 | 範例 |
|---|---|---|
| A. 缺少規格 | 沒有關於如何執行的文件 | 新功能沒有檢查清單 |
| B. 跨層合約 | 層之間的介面不明確 | API 回傳格式與預期不符 |
| C. 變更傳遞失敗 | 修改一處，遺漏其他處 | 更改函式簽名，遺漏呼叫點 |
| D. 測試覆蓋缺口 | 單元測試通過，整合測試失敗 | 單獨運作正常，組合後出錯 |
| E. 隱含假設 | 程式碼依賴未記錄的假設 | 時間戳記秒數 vs 毫秒數 |
2. 修復為何失敗（如適用）
若你嘗試多次修復才成功，分析每次失敗：
- 表面修復：只修復了症狀，未處理根本原因
- 範圍不完整：找到根本原因，但未涵蓋所有情況
- 工具限制：grep 沒找到，型別檢查不夠嚴格
- 心智模型：一直在同一層尋找，沒想到跨層思考
3. 預防機制
哪些機制可以防止此類錯誤再次發生？
| 類型 | 說明 | 範例 |
|---|---|---|
| 文件 | 寫下來讓人知道 | 更新思考指南 |
| 架構 | 從結構上讓錯誤不可能發生 | 型別安全包裝器 |
| 編譯期 | 嚴格的型別檢查，不留後門 | 簽名變更導致編譯錯誤 |
| 執行期 | 監控、警報、掃描 | 偵測孤立實體 |
| 測試覆蓋 | 端到端測試、整合測試 | 驗證完整流程 |
| 程式碼審查 | 檢查清單、PR 範本 | 「你有檢查 X 嗎？」 |
4. 系統性擴展
此錯誤揭示了哪些更廣泛的問題？
- 類似問題：這個問題還可能出現在哪裡？
- 設計缺陷：是否有根本的架構問題？
- 流程缺陷：是否有開發流程可以改進？
- 知識缺口：團隊是否缺少某些理解？
5. 知識擷取
將洞見固化到系統中：
- 更新
.trellis/spec/guides/中的思考指南 - 更新相關的
.trellis/spec/文件 - 建立問題記錄（如適用）
- 為根本修復建立功能票證
- 必要時更新檢查準則
輸出格式
請以以下格式輸出分析：
## 錯誤分析：[簡短描述]
### 1. 根本原因類別
- **類別**：[A/B/C/D/E] - [類別名稱]
- **具體原因**：[詳細描述]
### 2. 修復為何失敗（如適用）
1. [第一次嘗試]：[失敗原因]
2. [第二次嘗試]：[失敗原因]
...
### 3. 預防機制
| 優先級 | 機制 | 具體行動 | 狀態 |
|--------|------|----------|------|
| P0 | ... | ... | TODO/DONE |
### 4. 系統性擴展
- **類似問題**：[列出有類似問題的地方]
- **設計改善**：[架構層級的建議]
- **流程改善**：[開發流程的建議]
### 5. 知識擷取
- [ ] [要更新的文件 / 要建立的票證]
核心哲學
除錯的價值不在於修復錯誤，而在於讓這類錯誤永遠不再發生。
三個層次的洞見：
- 戰術層：如何修復「這個」錯誤
- 策略層：如何預防「這類」錯誤
- 哲學層：如何擴展思考模式
30 分鐘的分析，可省下未來 30 小時的除錯時間。
思考框架：貝氏推理
當多個根本原因看似合理且證據不完整時，應根據新證據按比例更新你的信念，而不是緊抱初始假設。
步驟 1：建立先驗機率
在調查之前，說明你相信什麼以及原因：
| 假設 | 先驗機率 | 推理 |
|---|---|---|
| H1：[原因 A] | 40% | 此模式中最常見 |
| H2：[原因 B] | 30% | 考量環境後合理 |
| H3：[其他] | 30% | 包羅萬象 |
先驗機率總和必須為 100%。如果你無法分配機率，請先調查。
步驟 2：觀察證據
記錄你發現的內容——具體說明可靠性：
- 你確切觀察到了什麼？
- 可靠性如何？（測試輸出 > 日誌訊息 > 使用者回報 > 直覺）
- 多個假設能否解釋這個證據？
步驟 3：更新信念
對於每個假設，問：如果這個假設為真，這個證據出現的可能性有多高？
更新的方向比精確計算更重要：
- 證據強烈支持 H1 → H1 機率增加
- 證據與 H2 矛盾 → H2 機率降低
- 證據在所有假設下可能性相同 → 無更新
步驟 4：尋找鑑別性證據
不要收集更多同類證據。尋找那些在主要假設之間差異很大的證據。
如果 H1 和 H3 機率接近：「如果 H1 為真，但 H3 不為真，我會看到什麼？」然後去檢查那個。
步驟 5：陳述信心水準
| 信心水準 | 行動 |
|---|---|
| 90% 以上 | 進行修復，並監控 |
| 70-90% | 進行修復，加入備援檢查 |
| 50-70% | 先測試假設，再決定 |
| 低於 50% | 需要更多證據，不要猜測 |
當證據不完整時，永遠不要表達二元的確定性。使用「最有可能」、「合理但不太可能」、「值得調查」。
常見謬誤
| 謬誤 | 範例 | 修正 |
|---|---|---|
| 忽略基礎率 | 「測試失敗 → 程式碼有問題」 | 測試因其他原因失敗的頻率多高？ |
| 確認偏誤 | 「一定是競爭條件，讓我找競爭的證據」 | 主動尋找反對主要假設的證據 |
| 定錨效應 | 「上次是快取問題，這次大概也是快取」 | 根據當前情境建立先驗機率，而不是昨天的錯誤 |
分析後：立即行動
重要：完成上述分析後，你必須立即：
-
更新規格 / 指南 - 不要只是列出待辦事項，要實際更新相關檔案：
- 如果是跨平台問題 → 更新
cross-platform-thinking-guide.md - 如果是跨層問題 → 更新
cross-layer-thinking-guide.md - 如果是程式碼重用問題 → 更新
code-reuse-thinking-guide.md - 如果是領域特定問題 → 更新
backend/*.md或frontend/*.md
- 如果是跨平台問題 → 更新
-
同步範本 - 更新
.trellis/spec/後，同步到src/templates/markdown/spec/ -
提交規格更新 - 這是主要產出，而不只是分析文字
如果分析只留在對話中，它就毫無價值。價值在於已更新的規格。