shared/skills/todo/SKILL.md

---
name: todo
description: 把「需求 → 分析 → 產生 todo.md → 交給指定模型實作」整條路徑固定成可重複執行的流程：先依 `/jsc-shared:spec-model` 的「需求分析」任務挑出分析模型，當前模型不符就停止並要求切換、不得先分析再說；接著讀取來源（需求描述、本機檔案，或走 `/jsc-shared:spec-issue-read` 讀取的 Gitea 議題）並釐清需求，任何不清楚之處一律依 `/jsc-shared:spec-ask-user` 詢問使用者、絕不臆測或編造；再依「依清單實作」任務挑出實作模型（使用者可用 `--impl-model` 指定，會在 `model_reason` 註明是使用者指定）；最後產生（或視既有檔案 frontmatter 的 `model` 是否相同，決定附加或詢問是否覆蓋）一份帶 `model`／`model_alias`／`model_reason`／`analyzed_by`／`analyzed_at`／`scope` frontmatter 與「給執行本清單 Agent 的強制規則」區塊的 `todo.md`，供使用者另開一個以該模型執行的 session 落地實作。當使用者說要把需求整理成待辦清單交給指定模型做、產生或更新 `todo.md`、幫需求選一個實作模型並寫成清單、要一份鎖定模型的執行清單，或提到 todo skill、需求轉 todo.md、指定模型 todo 時觸發。不適用於：把需求拆分成多個 Gitea 議題（用 `/jsc-doc:issues-analyze`）、實作既有 Gitea 議題的 TODO（用 `/jsc-code:issues`）。
argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--file <path>] [--impl-model <id|alias>] [--append|--overwrite] [--yes]"
---

# todo — 需求分析並產生指定模型執行的 todo.md

把「需求 → 分析 → 產生 `todo.md` → 交給指定模型實作」固定成六個階段，全程強制模型一致性：分析本身要用夠強的模型做，產出的清單要鎖定一個實作模型，執行清單的 agent 開工前必須自我核對模型，不符就停。

| 階段 | 做什麼 | 產出 |
| --- | --- | --- |
| 1. 選分析模型 | 依 `spec-model`「需求分析」任務取得推薦模型，比對當前模型 | 相符才繼續，不符則停止 |
| 2. 分析需求 | 讀取來源、釐清不清楚之處 | 需求彙整（目標／驗收條件／限制／`scope`） |
| 3. 選實作模型 | 依 `spec-model`「依清單實作」任務取得推薦模型，或採用使用者指定 | 實作模型 id／alias／理由 |
| 4. 產生 `todo.md` | 依固定格式寫出 frontmatter＋強制規則區塊＋checklist | 草稿內容（尚未寫檔） |
| 5. 檔案已存在的處理 | 依既有檔案 frontmatter 決定建立／附加／詢問覆蓋 | 實際寫入的檔案 |
| 6. 交付 | 輸出摘要表格，提醒以哪個模型開新 session 執行 | 面向使用者的總結 |

---

## 共用規範（必要前置）

先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝，
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。
本 skill 需要的規範：`spec-model`、`spec-output`、`spec-execution`、`spec-issue-read`、`spec-todo-list`、`spec-ask-user`、`spec-time-log`、`spec-gitea`、`spec-skill-invocation`

本 skill 特有補充：

- 本 skill 產生的 `todo.md` 就是 `spec-model` 第六節所述「帶 `model:` frontmatter 的清單檔」的**源頭**；本 skill 自己只負責產生這份清單，不執行清單內容。
- 全程不落地草稿檔以外的臨時檔案；`--source` 若指向 Gitea 議題附件需要暫存讀取時，比照 `spec-issue-read` 的唯讀暫存例外，讀完立即刪除。
- 階段 1 的模型檢查針對「執行本 skill 分析工作的 agent 自己」；階段 3 選出的實作模型是**寫進檔案給未來另一個 session 用的**，兩者是不同的模型、不同的檢查時機，不要混淆。

---

## 參數

`[--source <需求描述|檔案路徑|議題編號>] [--file <path>] [--impl-model <id|alias>] [--append|--overwrite] [--yes]`

| 參數 | 說明 |
| --- | --- |
| `--source` | 需求來源。未帶時視為「目標不明」的必要決策（依 `spec-execution`），詢問使用者要用描述／檔案路徑／議題編號哪一種，不得臆測。 |
| `--file` | 產出路徑，**預設 `./todo.md`**（相對於執行本 skill 當下的工作目錄）。 |
| `--impl-model` | 直接指定實作模型（id 或 alias），跳過階段 3 的推薦流程；仍會在 `model_reason` 註明「使用者指定」。 |
| `--append` / `--overwrite` | 針對階段 5「檔案存在且 `model` 不同」情境**提前作答**，用於跳過該次 `AskUserQuestion`；不影響「`model` 相同」時固定附加的規則（見階段 5）。二擇一，同時提供視為衝突，仍需詢問使用者。 |
| `--yes` | 依 `spec-execution` 略過一般性確認（例如「要不要現在就寫檔」）；**不得**用來略過階段 5 對「模型不同是否覆蓋」的詢問——那是破壞性決策，依 `spec-ask-user` 一律必須真的問到答案，除非已用 `--append`／`--overwrite` 明確作答。 |

---

## 階段 1：選分析模型

1. 依 `/jsc-shared:spec-model` 第三節取得可用模型清單與標籤（`claude-api` skill → CLI 自陳 → 使用痕跡 → smoke test，前一項取得就不必往下）。
2. 依第二節「需求分析／拆 TODO／架構決策」任務列比對必要標籤 `#深度推理` `#分析` `#本機可用`，選出推薦模型（加分標籤 `#長上下文`）。
3. 確認**當前執行本 skill 的模型 id**：agent 依自身系統提示所述的 exact model id 自我回報；無法確定時請使用者以 `/status` 確認，不要用猜的。
4. 當前模型 ≠ 推薦模型 → 依 `spec-model` 第五節格式**停止並要求使用者切換**，不得先做階段 2 的任何分析：

   ```
   [yyyy/MM/dd HH:mm:ss][模型檢查][ERR]: 本次需求分析建議使用 <推薦 model>（<alias>），當前模型為 <current-model-id>。
   請執行 /model <alias> 切換後重新呼叫本 skill，本次不進行任何分析。
   ```

5. 相符 → 記錄此模型 id（含變體標記，如 `[1m]`，依自我回報原樣記錄）供階段 4 的 `analyzed_by` 使用，繼續階段 2。

## 階段 2：分析需求

1. **判斷來源型態**（`--source` 未帶則先依〔參數〕表詢問使用者）：
   - 對應到本機可讀取的檔案路徑 → 視為**檔案**，讀取全文。
   - 純數字、`#123`、或 Gitea 議題 URL → 視為**議題編號**，走 `/jsc-shared:spec-issue-read`（含描述、所有留言、所有附件；分頁規則依 `spec-gitea`）；議題所在 repo 無法從目前工作目錄的 git remote 推斷時，詢問使用者 `owner/repo`，不得臆測。
   - 都不是 → 視為**需求描述**本文，直接採用 `--source` 的文字內容。
2. **釐清需求**：依 `/jsc-shared:spec-execution`「不臆測／需人工確認」——目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 `/jsc-shared:spec-ask-user` 詢問使用者（單選／多選判斷時機、選項上限 4、必含「其他」），**不得自行補完或用常見做法代填**。
3. 產出**需求彙整**：目標、驗收條件、限制條件，以及本次 `todo.md` 的 `scope`（受影響的目錄／repo／模組範圍，供階段 4 frontmatter 使用）。
4. 若來源本身有既有 Markdown checklist（例如議題描述或既有文件），依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。

## 階段 3：選實作模型

1. **使用者指定**（`--impl-model` 有帶）：以使用者指定為準。依 `spec-model` 第三節盡可能驗證其存在性與可用性（CLI 自陳比對，可行時 smoke test）；無法驗證也不得拒絕使用者的選擇，改在 `model_reason` 註明「使用者以 `--impl-model` 指定，未能於本機驗證可用性」。`model_reason` 必須明確寫出**這是使用者指定，非本 skill 推薦結果**。
2. **未指定**：依 `/jsc-shared:spec-model` 第二節「依清單實作／規格落地」任務列比對必要標籤 `#均衡實作` `#實作` `#本機可用`（加分標籤 `#中成本`），選出推薦模型；`model_reason` 寫成一段自然語言理由，**結合階段 2 的需求彙整內容**判斷（例如任務量體、是否需要跨檔案架構判斷、粒度是否已拆解到可直接動手），而不是照抄標籤名稱。
3. 記下最終的實作模型 `id`、`alias`（若有）、`model_reason`，供階段 4 使用。

## 階段 4：產生 todo.md

格式**完全比照** `/home/coder/plugins/todo.md` 現有樣式，逐項對齊：

### frontmatter

```yaml
---
model: <實作模型 id>
model_alias: <實作模型 alias，若無 alias 則省略此欄>
model_reason: <階段 3 產出的理由，含「使用者指定」註記時比照>
analyzed_by: <階段 1 確認的分析模型 id，原樣含變體標記>
analyzed_at: <yyyy/MM/dd HH:mm:ss，依 spec-time-log，Asia/Taipei>
scope: <階段 2 產出的 scope>
---
```

### 「給執行本清單 Agent 的強制規則」區塊

固定內容，只代換 `<model>`／`<alias>` 與時間戳，五條規則與錯誤訊息格式**逐字比照**、不可簡化或改寫措辭：

````markdown
## 0. 給執行本清單 Agent 的強制規則（先讀完再動手）

| 規則 | 內容 |
| --- | --- |
| **模型鎖定** | 本檔 frontmatter 的 `model` 是**強制**的，不是建議。開工前先自我確認當前模型 id。 |
| **不符就停** | 當前模型 ≠ `<model>` 時，**立刻停止、不做任何檔案修改**，輸出下方錯誤訊息並要求使用者切換。 |
| **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 |
| **附加不覆蓋** | 若之後要往本檔追加新需求：`model` 相同 → 附加到檔尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 |
| **完成即勾選** | 每完成一項就地把該行的 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」（Asia/Taipei，依 `/jsc-shared:spec-time-log`）。**不得留待多項一起補勾**；無法安全完成的項目維持未勾選並標註「需人工確認」，不得略而不報。 |

```
[<yyyy/MM/dd HH:mm:ss>][模型檢查][ERR]: 本清單指定 <model>（<alias>），當前模型為 <current-model-id>。
請執行 /model <alias> 切換後重新載入本清單，本次不進行任何修改。
```

> 當前模型 id 的取得方式：Claude Code 沒有提供模型 id 的環境變數，agent 依自身系統提示所述的 exact model ID 自我回報即可；無法確定時請使用者以 `/status` 確認，**不要用猜的**。
````

### checklist（依 `/jsc-shared:spec-todo-list` 排序與具體化）

- 逐項 `- [ ] **編號 短標題**：具體內容`，內容需動詞＋對象＋驗收條件齊備，能舉證對應 `path:line` 或需求彙整中的哪一句。完成後改為 `- [x] **編號 短標題**：具體內容（完成：yyyy/MM/dd HH:mm:ss）`，依上方「完成即勾選」規則逐項就地更新，不得留待多項一起補勾。
- 依影響範圍由小到大排序（XS/S/M/L/XL，見 `spec-todo-list`），範圍相同時前置依賴排前面。
- **編號規則**：清單有自然的分組（例如多個獨立工作方向）時，用「群組代號＋序號」（如 `A0-1`、`B1-2`，仿本檔範例）；沒有分組時用整數流水號（`1`、`2`、`3`…）。日後附加新項目時，編號延續既有規則、不得重複或跳號造成混淆。
- 清單分成多個彼此有先後依賴的群組時，仿照本檔範例在 checklist 前加一段「### 執行順序」註明群組間的強制先後與理由；若清單本身沒有這種分階段結構，省略此小節即可，不必為了套版而硬分組。
- 不得把任何需求彙整未提及、也無法合理推得的項目塞進清單；有疑慮的項目標「需人工確認」。

## 階段 5：檔案已存在的處理（需求核心，不可簡化）

寫檔前先讀 `--file`（預設 `./todo.md`）目前是否存在、若存在再解析其 frontmatter：

| 狀況 | 動作 |
| --- | --- |
| 檔案不存在 | 直接建立，寫入階段 4 產出的完整內容。 |
| 存在 且 frontmatter `model` **相同** | **附加到檔案最後**：加一條 `---` 分隔與 `## 追加（<yyyy/MM/dd HH:mm:ss>）` 標題，接新的 checklist 項目（依既有編號規則延續）。frontmatter 只更新 `analyzed_at`，**不動 `model`／`model_alias`／`model_reason`**。 |
| 存在 且 frontmatter `model` **不同** | **停下來用 `AskUserQuestion` 詢問使用者是否覆蓋**，見下方選項。**未得同意不得寫入任何內容。** |
| 存在 但**沒有** frontmatter | 視為「不同模型」處理，走上一列同樣的詢問流程。 |

- **詢問選項**（依 `/jsc-shared:spec-ask-user`，4 個以內、含「其他」）：`覆蓋（改用新模型）`／`保留舊檔改用舊模型附加`／`取消`／`其他`。
  - 選「覆蓋」→ 以階段 3～4 產出的新內容整份覆寫，`model`／`model_alias`／`model_reason` 全部換新。
  - 選「保留舊檔改用舊模型附加」→ **放棄階段 3 選出的新實作模型**，改沿用舊檔 frontmatter 的 `model`；階段 4 產生的 checklist 內容改為附加在舊檔最後（同「model 相同」列的附加格式）。
  - 選「取消」→ 不寫入任何內容，回報「已取消，`<path>` 未變更」。
  - 選「其他」→ 依使用者實際輸入處理，仍不得在未取得明確同意前寫入。
- `--append`／`--overwrite` 已明確回答這個分支時（見〔參數〕表），依 `spec-ask-user`「已從其他管道得知答案時跳過詢問」直接照該旗標執行，不再彈出 `AskUserQuestion`；`--yes` 單獨出現**不算**已回答，仍要問。

## 階段 6：交付

輸出摘要表格：

| 項目 | 內容 |
| --- | --- |
| 分析模型 | 階段 1 確認的模型（`analyzed_by`） |
| 實作模型 | 階段 3 選出的模型（`model` / `model_alias`），並註明是推薦還是使用者指定 |
| 項目數 | 本次新增的 checklist 項目數 |
| 檔案路徑 | 實際寫入的絕對路徑 |
| 本次動作 | 新建／附加／覆蓋 三者之一 |

並在最後明確提醒使用者：

> 請以 `<alias>`（找不到 alias 時用完整 id）模型開新 session 執行本清單：`<path>`。

---

## 呼叫方式

依 `/jsc-shared:spec-skill-invocation` 的統一呼叫方式，本 skill 的實際參數格式與範例：

| 助理 | 呼叫 |
| --- | --- |
| Claude Code / Antigravity | `/jsc-shared:todo --source "把 X 模組改成非同步"`、`/jsc-shared:todo --source ./RFC.md --file ./plans/x.todo.md`、`/jsc-shared:todo --source 123 --impl-model sonnet`、`/jsc-shared:todo --source ./RFC.md --append` |
| Codex | `$todo --source "..."`，或用 `/skills` 選單 |
| OpenCode | 描述需求（如「幫我把這段需求分析清楚，寫成一份鎖定模型的 todo.md」）自動觸發 |