1byte index 2 is not a char boundary; it is inside '⏳' (bytes 0..3) of `⏳ |`

查了半小時才搞清楚：有人在 markdown 表格的狀態欄位貼了個沙漏 emoji，Rust 切字串時踩到多位元組字元邊界，直接 crash。

這個意外讓我們重新想「工作日誌到底該長什麼樣」。

工作日誌的本質

工作日誌不是私人筆記，也不是 log 檔。它是一份版本企劃書，給下一個接手的人看的。

那個人可能是三個月後的自己，可能是新人，也可能是凌晨三點被叫起來排查問題的 on-call。他們需要快速搞清楚：這個版本要做什麼、為什麼這樣設計、現在到哪了。

所以工作日誌最重要的特質是自給自足：拿起來讀，不需要問任何人，就能理解完整脈絡。

三個核心原則

原則一：工具相容性優先

從那個 panic 事故學到的：markdown 表格單元格裡，禁止放 emoji。⏳、🔄、❌ 一律不行。工具鏈複雜，有些工具處理多位元組 Unicode 有 bug，而這種 bug 偏偏只在最不需要的時候出現。

表格外的段落、標題、列表可以自由用 emoji，限制只針對表格單元格。

錯誤的寫法：

1| Ticket ID | 狀態 |
2|-----------|------|
3| W1-001    | ⏳   |
4| W1-002    | 🔄   |

正確的寫法：

1| Ticket ID | 狀態 |
2|-----------|------|
3| W1-001    | 待處理 |
4| W1-002    | 進行中 |

一份無法被工具讀取的文件，等於沒有文件。

原則二：狀態符號標準化

表格只能用純文字，那就把詞彙統一：

• 等待開始：待處理
• 正在執行：進行中
• 執行完畢：已完成
• 主動取消：取消
• 跳過不做：跳過
• 被阻塞中：阻塞
• 失敗或錯誤：失敗

詞彙固定，Hook 和解析工具才能依賴它計算——統計完成率、自動產生摘要、偵測卡住的任務。詞彙一飄移，自動化就跟著失效。

原則三：標準化結構

結構固定，任何人拿到都知道去哪找什麼。標準模板的必要部分：

版本基本資訊（最上方）：版本號、開始日期、當前狀態、Git 分支。五秒內確認自己看的是哪個版本。

版本目標：幾句話說這個版本要做什麼。夠高層次讓非技術的人能讀懂，夠具體讓接手工程師能判斷方向對不對。

執行階段與 Ticket 清單：每個階段一張表，欄位固定：Ticket ID、操作動詞（Analyze、Design、Fix、Implement）、目標、負責人、依賴、狀態。Ticket ID 格式是 版本號-Wave-序號，例如 0.25.0-W1-001，看到 ID 就知道它屬於哪個版本哪個批次。

技術筆記：記錄開發過程中的發現和決策。沒有固定格式，但很重要——「為什麼這樣做」不寫下來，幾個月後就消失了。

細節下沉原則

工作日誌只寫大方向。分析過程、測試結果、錯誤訊息，放到 Ticket 文件裡。

工作日誌回答「要做什麼」和「為什麼」，Ticket 回答「怎麼做」和「結果如何」。違反這個原則的工作日誌會變成大雜燴：目標、程式碼片段、技術細節、執行記錄全部混在一起，要找什麼資訊得從頭讀到尾。

讓格式守護自己

光靠自律維持格式效果有限。我們建了一個 Hook：worklog-format-check，在每次寫入或編輯工作日誌後自動觸發，掃描表格裡有沒有問題 emoji，有就輸出警告並指出位置。

它不阻擋操作，只提醒。強制阻擋讓人挫敗，沉默放行問題悄悄累積——警告是中間那個平衡點：提醒問題存在，但把修正的決定權留給人。

格式是一種溝通

設計這些規則的時候，有時候會覺得這些細節是不是太瑣碎了。

但格式的背後是一種承諾：下一個接手的人不需要猜測，就能從文件裡找到答案；工具鏈穩定運作，不會在最需要的時候 crash；整個團隊說的是同一套語言。

格式是工具，工具設計得好，人才能把注意力放在真正重要的事上。

生命週期總覽

 1需求/問題產生
 2    |
 3    v
 4建立 Ticket (/ticket create)
 5    |
 6    v
 7Ticket 狀態: pending
 8    |
 9    v
10認領 Ticket (/ticket track claim)
11    |
12    v
13Ticket 狀態: in_progress
14    |
15    +-- 正常完成 --> /ticket track complete --> 狀態: completed
16    |
17    +-- 無法繼續 --> /ticket track release --> 狀態: blocked
18    |                                              |
19    |                                              v
20    |                                         升級到 PM 處理
21    |
22    v
23完成

這套系統的核心目標是將任務需求有邏輯地拆分拆細。任務進來後先分析，拆分成平行的子任務；子任務若仍太大，可繼續往下切分。執行時從最底層開始，完成後檢查平行任務，再往上驗收父任務，直到整個任務鏈完成。

任務拆小的好處：降低執行時的認知負擔，也讓驗收檢查更容易發現疏失。

Ticket 狀態定義

階段-標準流程對照表

每個生命週期階段都有對應的標準流程和提示，防止關鍵步驟被遺漏。

建立階段

認領階段

執行階段

完成階段

驗收後階段

任務鏈後續步驟建議

當 Ticket 完成時，系統會自動分析任務鏈狀態並建議下一步。

分析優先級

輸出範例

 1============================================================
 2[任務鏈後續步驟建議]
 3============================================================
 4
 5已完成: 0.31.0-W4-007.1
 6        [實作 track P0 功能]
 7
 8任務鏈進度: 1/3 completed
 9   Root: 0.31.0-W4-007
10
11建議下一步:
12   1. 0.31.0-W4-007.2
13      [實作 track P1 功能]
14      原因: 阻塞已解除（blockedBy 0.31.0-W4-007.1 已完成）
15      狀態: pending → 可認領

任務鏈 ID 格式

10.31.0-W3-002              # ticket-handoff 功能（根）
2├── 0.31.0-W3-002.1        # chain_analyzer 模組
3│   ├── 0.31.0-W3-002.1.1  # 問題修復
4│   └── 0.31.0-W3-002.1.2  # 測試補充
5├── 0.31.0-W3-002.2        # handoff_executor 模組
6└── 0.31.0-W3-002.3        # 文件更新

chain 欄位

根任務 0.31.0-W3-002 的 chain：

1chain:
2  root: "0.31.0-W3-002"
3  parent: null
4  depth: 0
5  sequence: [2]

子任務 0.31.0-W3-002.1.1 的 chain：

1chain:
2  root: "0.31.0-W3-002"
3  parent: "0.31.0-W3-002.1"
4  depth: 2
5  sequence: [2, 1, 1]

ID 正則表達式：^(\d+\.\d+\.\d+)-W(\d+)-(\d+(?:\.\d+)*)$

Ticket 建立流程

任務層級判斷

 1任務層級判斷
 2    |
 3    v
 4這個任務是否因為執行現有 Ticket 而產生？
 5    |
 6    +-- 是 → 來源 Ticket 是什麼？
 7    |       |
 8    |       └── 確定來源 Ticket ID → 建立該 Ticket 的子任務
 9    |           ├── 來源: 010.4 → 子任務 ID: 010.4.x
10    |           ├── 來源: 010.4.1 → 子任務 ID: 010.4.1.x
11    |           └── 來源: 010 → 子任務 ID: 010.x
12    |
13    └-- 否 → 建立新任務鏈（新的 Wx-00n）

核心判斷問題：「這個任務是在執行哪個 Ticket 時產生的？」若有明確來源，建立子任務；若無關聯，建立新任務鏈。

建立格式

 1---
 2id: {版本}-W{波次}-{序號}
 3title: {動詞} {目標}
 4type: IMP/RES/ANA/INV/DOC
 5status: pending
 6priority: P0/P1/P2
 7assignee: pending
 8created: {日期}
 9---
10
11# {Ticket ID}: {標題}
12
13## 目標
14
15{目標描述}
16
17## 驗收條件
18
19- [ ] {條件1}
20- [ ] {條件2}

Atomic Ticket 檢查

驗收條件格式要求

驗收條件必須符合 4V 原則：可驗證、可量化、可追溯、可記錄。

標準格式（表格式）：

1## Acceptance Criteria
2
3| #   | 項目       | 來源       | 確認方法   | 狀態 |
4| --- | ---------- | ---------- | ---------- | ---- |
5| 1   | {項目描述} | {來源引用} | {確認方法} | [ ]  |
6| 2   | {項目描述} | {來源引用} | {確認方法} | [ ]  |

Ticket 有效性驗證

有效 Ticket 定義

有效的 Ticket 必須滿足以下條件：

驗證時機

無效 Ticket 處理

無效 Ticket（缺少決策樹欄位）：

• 無法用於 Task 派發（被 Hook 阻止）
• 需要補充決策樹欄位才能使用
• 建議使用 /ticket create 重新建立

補充決策樹欄位

如果 Ticket 缺少決策樹欄位，可手動補充：

1. YAML 格式（在 frontmatter 中）：

   1decision_tree_path:
   2  entry_point: "第X層"
   3  decision_nodes:
   4    - layer: "X"
   5      question: "決策問題"
   6      answer: "答案"
   7      next_action: "下一步"
   8  final_decision: "最終決策"
   9  rationale: "決策理由"

2. Markdown 格式（在內容中）：

   1## 決策樹路徑
   2
   3### 進入點
   4
   5- **層級**: 第X層
   6- **觸發條件**: ...

Ticket 認領流程

認領規則

Ticket 執行流程

 1認領 Ticket
 2    |
 3    v
 4執行對應階段工作
 5    |
 6    v
 7更新工作日誌
 8    |
 9    v
10驗證驗收條件
11    |
12    +-- 全部通過 --> 完成 Ticket
13    +-- 部分通過 --> 繼續處理或升級
14    +-- 無法完成 --> 釋放 Ticket

完成檢查

Ticket 釋放流程

釋放時機

Ticket 類型說明

版本歷史

• v2.8.0 (2026-02-01): 取消驗收豁免機制，改為契約式驗收
• v2.7.0 (2026-02-01): 強化驗收代理人派發要求
• v2.6.0 (2026-01-31): 新增任務層級判斷規則
• v2.5.0 (2026-01-30): 新增階段-標準流程對照表和任務鏈後續步驟建議
• v2.4.0 (2026-01-30): 新增建議追蹤流程整合章節
• v2.3.0 (2026-01-30): 新增驗收條件格式要求章節
• v2.2.0 (2026-01-29): 新增任務鏈 ID 格式章節
• v2.1.0 (2026-01-27): 新增 Ticket 有效性驗證章節
• v2.0.0 (2026-01-23): 重構為 TDD 含 SA 前置審查流程版本

我們原本設計的是三重文件系統，但是現在會經過擴充把分工再度做拆分，重新調整不同的工作職責

changelog 是純粹的提供給其他工程師了解版本推進的變化

todo.md 是當前版本已知的待處理的問題，但是還沒加入執行的排程中，可能會在下一個版本或者更之後的版本處理這些問題，如果已經解決的任務應該要從 todo.md 移除

worklog 是記錄這個版本的大方向，這個版本任務的前情提要，整個版本的執行企劃，不包括執行細節，因為執行細節我們會交付給 ticket ，我們要確保的是 worklog 想要達到的目標都有達成，比如我們剛剛規劃的 step by step ,我們為什麼會這樣設計，為什麼我們需要這些設計相關的解釋，理論上，每一個工程師，不需要其他的 context 解釋，他應該能從當前版本的 worklog 理解所有人的工作目標跟工作要求

ticket 是所有任務的細節，會記錄任務從何而來，目標是什麼，執行的途中也會更新 ticket 的處理狀況跟進度 ，直到 ticket 被更新為完成為止

最後是我們剛剛新增的錯誤模式文件系統，當我們在執行 ticket 之前跟之後，都需要查詢或者更新相關的問題，蒐集問題，並且提供之後改善我們工作模式的參考素材

所以我們需要 SKILL 說明每個文件的職責，設計相關的 command 做更新或者查詢，用 hook 確保文件進度的同步，這是我們現在的工作模式的核心運作系統