code/skills/issues/SKILL.md

name, description, argument-hint

name	description	argument-hint
issues	處理一或多個 Gitea 議題的實作流程：先選擇使用 `tea` 或 Gitea REST API + `GITEA_TOKEN`（已選定則跳過），再確認議題所在專案（已知則跳過）與要處理的議題編號（一或多個）；接著讀取議題描述與留言、彙整需求，整理 TODO 列表並依影響範圍由小到大排序，既有 TODO 不足以達成議題需求時補上新 TODO 並附加到議題描述；最後逐項實作 TODO，每完成一項就把進度留言到議題。全程不建立任何草稿檔，中間成果一律用議題描述或留言保存，並盡量以表格與 Mermaid 圖呈現。當使用者說處理議題、實作議題、依議題 TODO 開工、把議題需求整理成 TODO 並逐項完成、議題進度留言，或提到 issues、issue 實作、Gitea 議題處理時觸發。不適用於：把需求拆分成多個新議題（用 issues-analyze）、只同步議題狀態不實作（用 issues-sync）、或與 Gitea 無關的本機 TODO 管理。	[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes]

issues — 彙整議題 TODO 並逐項實作、留言進度

五階段 skill：先做工具選擇（tea 或 Gitea REST API + GITEA_TOKEN），再確認議題所在專案與要處理的議題編號，接著讀取議題並彙整 TODO 列表（依影響範圍小→大排序，缺漏的 TODO 附加到議題描述），最後逐項實作 TODO，每完成一項就把進度留言到議題。

階段	動作	可跳過條件
A. 工具選擇	檢查 tea / GITEA_TOKEN → 詢問使用者要用 tea 或 api	使用者已明確選定（--tool 或對話中已選）
B. 確認專案	詢問議題所在專案（owner/repo），可用目前 repo 的 origin 當預設選項	已知專案（--repo、對話已提供、或使用者確認採用 origin）
C. 選擇議題	詢問要處理的議題編號，一個或多個	已提供（--issues 或對話中已列出）
D. 彙整 TODO	讀議題描述＋留言 → 彙整需求 → TODO 依影響範圍小→大排序 → 不足以達成需求的缺漏 TODO 附加到議題描述	—
E. 逐項實作	依排序實作每項 TODO → 每完成一項：勾選議題描述 checkbox ＋ 留言進度到議題	—

---

共用規範（必要前置）

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

本 skill 特有補充：

• 階段 E 在議題範圍內對目標 repo 原始碼的正常程式修改，是 spec-no-scratch-files 不落地準則的唯一例外（不算草稿檔）。
• 必要決策（會中斷詢問）：工具皆不可用、專案不明、議題編號缺失、TODO 與需求衝突需人工裁示、實作失敗需使用者決策。
• 階段 A／B／C 的詢問在「可跳過條件」成立時必須跳過，不要重複確認已知資訊。

---

參數

格式：[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes]

• --tool <tea|api>：指定工具，帶此參數時跳過階段 A 的詢問（仍需驗證該工具可用）。
• --repo <owner/repo>：議題所在專案，帶此參數時跳過階段 B 的詢問。
• --issues <編號,以逗號分隔>：要處理的議題編號，可一個或多個（例 --issues 12 或 --issues 12,15,18），帶此參數時跳過階段 C 的詢問。
• --host <gitea 主機>：gitea 主機（如 gitea.jsc.idv.tw）；省略時依 --repo 的 URL、目前 repo 的 origin 或 tea login 對應 host 決定，無法決定時詢問。
• --yes：全自動；即使未帶此參數，也依「自動執行原則」盡量不中斷。

---

階段 A：工具選擇（已選定則跳過）

若使用者已透過 --tool 或對話明確選定工具，跳過詢問，只做該工具的可用性驗證。

依 /jsc-shared:spec-gitea 的工具選擇流程執行。

階段 B：確認議題所在專案（已知則跳過）

若已透過 --repo、對話內容或先前階段確知專案，跳過詢問。

1. 若目前工作目錄是 git repo，解析 git remote get-url origin 取得 host／owner／repo 作為預設選項提供給使用者。
2. 詢問使用者議題所在專案（owner/repo 或 repo URL）；使用者只給名稱時，確認 host／owner 補齊完整座標。
3. 驗證專案可讀：
   • tea：tea repos <owner>/<repo> 或 tea issues list --repo <owner>/<repo> --limit 1
   • api：GET https://<host>/api/v1/repos/<owner>/<repo>
4. 確認本機是否已 clone 該 repo（實作階段需要）；找不到本機 repo 時詢問路徑或是否需要 clone，不臆測位置。

階段 C：選擇要處理的議題編號（一個或多個）

若已透過 --issues 或對話提供編號，跳過詢問。

1. 先列出該專案開啟中的議題供使用者參考（編號、標題、標籤、里程碑），以表格呈現：
   • tea：tea issues list --repo <owner>/<repo> --state open --output csv --fields index,title,labels,milestone
   • api：GET {base}/issues?state=open&type=issues（有分頁必須完整分頁讀取）
2. 詢問使用者要處理哪些議題編號，接受一個或多個。
3. 逐一驗證每個編號存在且為 issue（非 pull request）；不存在或已關閉的編號回報並請使用者確認是否仍要處理。

階段 D：彙整需求與 TODO 列表（依影響範圍小→大排序）

對每一個選定議題執行：

D1. 讀取議題完整內容並彙整需求

依 /jsc-shared:spec-issue-read 讀取議題完整內容（描述、所有留言、所有附件）並彙整需求；title／state／labels／milestone／assignees 一併取得供階段 B／C 與後續留言引用。

D2. 盤點既有 TODO 並產生排序後的 TODO 列表

依 /jsc-shared:spec-todo-list 盤點議題描述既有 TODO、產生新 TODO（格式、可驗收性、禁止編造、依影響範圍小→大排序、舉證 path:line 或需求語句）。

• 勾稽需求覆蓋度：逐條比對 D1 需求彙整與 TODO 列表；若既有 TODO 不足以達成議題描述與需求，補上缺漏的 TODO（標註「新增」）。
• 有助理解時，在留言或描述中加入 Mermaid 流程圖呈現 TODO 之間的依賴與執行順序。

D3. 缺漏 TODO 附加到議題描述

• 若 D2 有新增 TODO，依 /jsc-shared:spec-todo-list 的區塊格式規則，用 tea 或 API 更新議題描述：
  • tea：tea issues edit <index> --repo <owner>/<repo> --description <更新後全文>（tea 版本不支援時改用 API）
  • api：PATCH {base}/issues/{index}，body 以 UTF-8 JSON 檔帶入 {"body": "..."}
• 更新前先向使用者以表格摘要「新增了哪些 TODO、為什麼需要」；帶 --yes 時直接執行並回報。
• 沒有新增 TODO 時不改動議題描述。

若議題描述或其中的 TODO 清單帶有等價於 model: frontmatter 的模型宣告（或本 skill 未來擴充為讀取帶 model: frontmatter 的檔案），依 /jsc-shared:spec-model 的『讀到帶 model: frontmatter 的清單檔時的檢查義務』先做模型檢查，再進入階段 E。

階段 E：逐項實作 TODO，每完成一項留言到議題

依 D2 排序（多議題時先完成一個議題的所有 TODO，再進入下一個議題；有跨議題依賴時先處理被依賴者）逐項執行：

1. 實作：在本機 repo 依 TODO 內容實作，只修改該 TODO 必要範圍；發現需要擴大範圍或牽動其他 TODO 時，先停止並詢問使用者。
2. 驗證：執行適合專案的建置／測試／驗證；失敗時修正到通過，無法通過則記錄原因並在留言中標註「待人工處理」。
3. 更新議題描述：把該 TODO 的 checkbox 由 - [ ] 勾成 - [x]（同 D3 的更新方式）；勾選與留言回報依 /jsc-shared:spec-todo-list 的完成回報規則。
4. 留言進度到議題（每完成一項就留言，不可累積到最後一次補）：
   • tea：tea comment <index> --repo <owner>/<repo> <內容>
   • api：POST {base}/issues/{index}/comments，body 以 UTF-8 JSON 檔帶入
   • 留言內容以表格呈現：本項 TODO、影響範圍、主要變更（檔案／模組）、驗證方式與結果、整體進度（已完成 n/總數 m）；有助理解時附 Mermaid 圖。
5. 全部 TODO 完成後，對每個議題留下總結留言：TODO 完成統計表、變更檔案清單、驗證總結、待人工處理項目（若有）。

本 skill 範圍到「實作＋留言」為止；是否 commit、push、開 PR 或關閉議題不在本 skill 自動範圍，由使用者另行指示（可搭配 review-resolve 的分類提交與 PR 流程）。

---

總結

各階段執行後輸出：

• 階段 A：選定工具（tea 或 api）、可用性檢查結果（token 只顯示已設定／未設定）、是否因已選定而跳過詢問。
• 階段 B：議題所在專案（host／owner／repo）、本機 repo 位置、是否因已知而跳過詢問。
• 階段 C：處理的議題編號清單（含標題），是否因已提供而跳過詢問。
• 階段 D：每個議題的需求彙整重點、TODO 列表（含影響範圍排序）、新增了幾項 TODO 並是否已附加到議題描述。
• 階段 E：每項 TODO 的完成狀態與留言連結（或編號）、驗證結果、待人工處理項目；提醒後續可自行決定 commit／PR／關閉議題。

---

呼叫方式

格式：[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes] — 全部可省略；省略時依階段 A／B／C 詢問（已知資訊一律跳過詢問）。token 一律由環境變數 GITEA_TOKEN 提供。

各助理呼叫方式依 /jsc-shared:spec-skill-invocation（本 skill 為 /jsc-code:issues），常用範例：

• Claude Code / Antigravity：/jsc-code:issues，或 /jsc-code:issues --tool api --repo plugins/code --issues 12,15 --yes
• Codex：$issues，或 $issues --tool tea --repo plugins/code --issues 12，或用 /skills 選單
• OpenCode：描述需求（如「用 GITEA_TOKEN 讀 plugins/code 的 12、15 號議題，整理需求成 TODO 依影響範圍小到大排序、缺的補進議題描述，然後逐項實作、每完成一項留言進度」）自動觸發