階段日誌
寫下工作階段的持久記錄。這些日誌會被後續閱讀者——包括六週後、已完全失去當下脈絡的你——視為真實依據。準確性比修飾更重要。
何時執行
- 建置、修正、稽核或研究任務剛完成
- 階段即將結束，且下一個階段需要了解當前狀態
- 已找出根本原因，且該機制值得記錄
不要為瑣碎工作執行此技能。一行程式碼的修正不需要日誌。
記錄存放位置
記錄會存放在專案保存階段記錄的位置——可能是 docs/sessions/ 目錄、筆記庫或維基。如果不清楚，先詢問一次，之後保持一致。
檔案名稱應包含日期和簡短描述，以便排序和掃描：YYYY-MM-DD 簡短描述.md。
步驟
1. 寫作前先收集事實
不要僅憑對話記憶來撰寫。 請收集：
- PR 編號、commit SHA、遷移時間戳、部署 ID
- 實際驗證了什麼，以及透過什麼指令驗證
- 哪些項目失敗了，以及哪些仍待處理
- 只有人類能處理的事項
如果某個事實無法確認，請標記為「未確認」，而不是直接刪除或斷言。
2. 撰寫主體
# YYYY-MM-DD — <找出根本原因或已交付的內容>
<一行說明工作如何執行：誰規劃、誰建置、誰審查。>
## 發生了什麼事
- 先說明機制。為什麼會發生，而不只是發生了什麼。
- 具體證據：PR 編號、SHA、時間戳、行數、日誌行。
- 明確區分已證明與推斷的內容。
## 修正
1. 編號步驟。每一步都要說明驗證了什麼以及如何驗證。
## 固定的不可違反規則
<僅在階段產生了禁止事項時使用。每個規則都要基於引發該規則的事件。>
## 待辦事項——需要人類處理
- [ ] 只有人類能處理的事項
連結：<相關文件>
如果筆記系統使用 frontmatter，請包含 outcome 欄位：一句完整的句子，說明現在成立但之前不成立的事實。 這是最常被閱讀的一行。請寫出真實的陳述，而非標籤。
3. 每個人都遺漏的兩個章節
## 待辦事項 和連結頁尾是必填的。 它們是能將價值傳遞給後續階段、卻最常被忽略的兩個章節——在一個筆記庫中，測量 230 份現有日誌後發現，它們分別只出現在約 21% 和 28% 的日誌中。
每次都要寫上這兩個章節。如果確實沒有事項需要人類處理，請寫 無——沒有保留任何事項。，而不是刪除標題。
4. 標記每項聲明
在內文中將每項聲明分別標註為 VERIFIED (驗證方式) 或 ASSUMED (未檢查原因)。請勿模糊處理。
「已驗證」應表示人類或指令確實確認了該項事實。關於生產環境的聲明，必須透過對生產環境的查詢來驗證——而不是通過測試、已合併的 PR 或成功的部署。
5. 儲存前先解析所有連結
在寫入之前，請檢查每個連結目標是否對應到真實檔案。筆記系統中斷連結累積得很快，而充滿無效連結的日誌，沒有人會信任。
6. 更新專案狀態
如果工作改變了專案狀態，請在該專案的主要文件中新增一個帶有日期的狀態區塊——最新的在最前面，往前追加，絕不覆蓋歷史。
如果工作推動了一個需要交接文件的計劃，請就地更新該文件，以便下一個階段能正確接手。
7. 回饋教訓
如果使用者在階段中糾正了某些事項，請將教訓寫入持久儲存位置——規則檔案、記憶儲存、或本技能本身。這就是讓糾正不再重複發生的方法。
內文風格
- 具體且可證偽。模糊的總結在這裡比完全沒有更糟。
- 絕不宣稱某種狀態，除非說明如何檢查。
- 先說壞消息。不要隱藏。
- 為完全不了解當前脈絡的讀者而寫。
禁止事項
- 不要覆蓋現有的日誌。先讀取，再編輯。
- 不要寫入機器生成的目錄。
- 不要建立暫存檔案或將建置輸出放在筆記旁邊。