shared/skills/spec-todo-list/SKILL.md

name, description

name	description
spec-todo-list	JSC plugins 共用「TODO list 規範」：一律用 Markdown checklist（`- [ ]`）格式、每項要具體到可執行可驗收、必要時補上實作方式與建議修改內容、不得憑空編造需求外的項目、依影響範圍由小到大排序、每項要能舉證對應到 `path:line` 或議題描述的哪一句、完成一項就勾選並附上 Asia/Taipei 時間戳並留言回報進度。當其他 skill 內文引用 spec-todo-list 或 /jsc-shared:spec-todo-list、或需要產生／追蹤議題（或文件）TODO list 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

spec-todo-list — 共用 TODO list 規範

所有 JSC skills 在議題描述、保存議題、TARGET.md 等場合產生或追蹤 TODO 清單時，一律遵守以下規範。

格式：Markdown checklist

• 一律使用 Markdown 任務清單語法：未完成 - [ ]，已完成 - [x]；不得改用其他符號（*、純文字條列、表情符號打勾等）。
• 沒有既有 ## TODO 區塊時，於描述或文件最後新增 ## TODO 標題再接清單；已有該區塊時在其中追加，不新開第二個 ## TODO 區塊。
• 子項目以縮排表示上層項目的子步驟，隨上層一起追蹤；子項目全部完成才可把上層一併勾選。
• 標題、說明文字等非清單內容原樣保留，只當作項目的背景脈絡，不得因為新增／調整 TODO 而改寫。

項目內容：可執行、可驗收

• 每一項 TODO 都必須具體到看到這一句就知道要做什麼、做完後能明確判斷是否達成；不得使用「優化一下」「檢查看看」「處理相關問題」這類模糊、無驗收標準的措辭。
• 動詞＋對象＋（必要時）驗收條件三者盡量齊備，例如「把 UserService.Login 的密碼驗證改為使用雪湯 hash 比對，單元測試涵蓋密碼錯誤與帳號鎖定兩種情境」，而非「改善登入安全性」。
• 一項 TODO 只對應一件可獨立完成、可獨立驗收的工作；範圍過大時拆成多項，不得把整個議題塞成一項。
• 若 TODO 用於實作或修正文件／程式，建議直接補上「實作方式」與「建議修改內容」，讓執行者不必回頭猜測改法。
• 供實作型 TODO 使用時，建議格式可寫成 - [ ] **編號 短標題**：具體內容；實作方式：...；驗收條件：...；來源依據：...；建議修改內容：...；若確實沒有明確修改方向，建議修改內容 可省略，但 實作方式 不可省略。

禁止憑空編造

• TODO 只能從需求來源（議題描述、留言、來源文件、使用者明確補充）推導；不得加入來源未提及、也無法從來源合理推得的項目。
• 推導有疑慮或來源本身模糊時，標註「需人工確認」，不得用臆測或「合理推測」補上內容並當作既定需求。
• 盤點既有 TODO 時，已勾選（- [x]）項目視為已完成，不得重新編造或重做；只在確有缺漏時才補上新項目，並標明「新增」以便使用者辨識。

排序：依影響範圍由小到大

清單依每項 TODO 的影響範圍（預計修改的檔案／模組數與波及面）由小到大排序；範圍相同時，前置依賴項排在前面。可參考下列分級（節錄自 code/skills/issues/SKILL.md）：

影響範圍	定義（參考）
XS	單一檔案內的局部修改（文案、設定值、小修正）
S	單一檔案或單一函式的邏輯調整
M	同一模組內跨多檔案的修改
L	跨模組修改或介面／契約變更
XL	跨專案、資料結構或流程性的大改動

排序目的是讓小範圍、低風險的項目先完成，逐步逼近影響面較大的項目；不得因為「比較想先做」而打亂由小到大的順序。

舉證：對應 path:line 或議題描述語句

• 每一項 TODO 都必須能舉證它從何而來，二擇一（或並列）：
  • 對應到需求來源（議題描述、留言、來源文件）中的哪一句——引用或指出該句內容；
  • 對應到程式碼中的哪個位置——以 path:line 標明（例如 src/services/UserService.cs:42）。
• 判斷 TODO 是否已完成時，同樣要以 path:line 指出對應的實作位置作為依據；無法從檔案或來源可靠判斷者，維持未完成並標註「需人工確認」，不得憑印象判定完成。
• 舉證資訊留在 TODO 項目本身、留言或回傳內容中，方便日後追溯每一項 TODO 的來源與完成依據。

完成回報：勾選並留言

• 完成一項 TODO，就地把該行改成 - [x]（子項目全部完成才勾選上層），不得留待多項一起補勾。
• 勾選時在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」時間戳，時區與格式依 /jsc-shared:spec-time-log（Asia/Taipei）；不得使用其他時區或格式。
• 每完成一項，都要把進度回報成留言（或依所在流程指定的回報位置），內容至少包含：完成了哪一項、對應的 path:line 或需求語句依據；多項同時完成時可整理成一則留言，但每一項都要能個別對應到依據。
• 無法安全完成的項目保持未勾選，並標註原因（例如「需人工確認」）供後續處理，不得略而不報。