# Incidents

平台/架構級事件 post-mortem。每份檔案 = 一個事件。

不同於 SDD（`.agents/specs/`）的「我們要怎麼設計」，incident 記錄「我們實際撞過什麼雷、怎麼診斷、怎麼修、未來怎麼避免」。

## 命名慣例

`YYYY-MM-DD-{short-slug}.md`

例：`2026-05-13-cypher-outbound-522.md`

## 寫的時機

- 花了顯著時間（> 1 小時）才查清根因的問題
- 平台層 / CF / 架構層問題（不是普通 code bug）
- 需要修架構決策或 URL 慣例的問題
- 「以為解決了結果不是」的反覆事件

普通 bug fix 不需要寫 incident。

## 檔案結構建議

每份 incident 至少含：

- **症狀**：怎麼觀察到的
- **誤判路徑**：走過哪些錯方向（含為什麼錯）
- **真相**：根因
- **修法**：實際改了什麼
- **驗證**：怎麼確認解了
- **未來避免**：下次怎麼提早識別

最重要的是**誤判路徑**——這是未來自己（或其他 dev）會踩同樣假設的最好預防。