---
name: spec-todo-list
description: 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` 或需求語句依據；多項同時完成時可整理成一則留言，但每一項都要能個別對應到依據。
- 無法安全完成的項目保持未勾選，並標註原因（例如「需人工確認」）供後續處理，不得略而不報。