docs(doc-issues-analyze): 更新說明為分析後排序留言、實作改由 code plugin 的 code-issues 負責

skills/doc-issues-analyze/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: doc-issues-analyze
-description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取，附件內容一併納入需求分析），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，在產生保存議題前必須完整釐清需求、任何不清楚的部分都要詢問使用者、絕不臆測或編造，確認清楚後才將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時母議題必須所有子議題關閉後才可關閉，優先以 issue dependency 阻擋），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中/待處理/進行中/待測試/已完成），把議題移到「待處理」欄位（不往回移、介面不支援時改列建議清單請人工調整）；再依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
+description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取，附件內容一併納入需求分析），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，在產生保存議題前必須完整釐清需求、任何不清楚的部分都要詢問使用者、絕不臆測或編造，確認清楚後才將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時母議題必須所有子議題關閉後才可關閉，優先以 issue dependency 阻擋），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中/待處理/進行中/待測試/已完成），把議題移到「待處理」欄位（不往回移、介面不支援時改列建議清單請人工調整）；最後依到期日與相依關係排序小功能議題並把排序結果留言到保存議題。本 skill 到「議題拆分完成＋排序留言」為止，**不實作程式碼**（不修改原始碼、不 commit、不 push、不開 PR），實作交由 /jsc:code-issues。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。不適用於：實作議題程式碼（用 code-issues）、要把彙整結果與實作草稿落地成文件檔案交付的流程（用 doc-issues-analyze-to-file；本 skill 全程不落地任何檔案）。
 ---
 
 # 分析多來源需求並保存為議題
 
-你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 `develop` 或 `master`；**實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR**。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
+你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日與相依關係排序，並把排序結果留言到保存議題；**本 skill 不實作程式碼**——不修改原始碼、不 commit、不 push、不開 PR，後續實作交由 `/jsc:code-issues` 或使用者另行處理。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
 
 ## 共用規範（generic plugin，必要前置）
 
@@ -18,7 +18,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
 
 ## 絕對準則（不可違反）
 
-- **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、實作進度、交付摘要）一律留在**對話內容**與 **subagent 的回傳值**，並透過 `tea` 或 Gitea API **保存到議題描述或留言**。例外只有兩個：（1）使用者確認實作某議題後、在該議題範圍內對**目標 repository 原始碼**進行的正常程式修改與 git commit；（2）為了讀取議題附件（圖片等二進位檔）而**唯讀暫存下載到系統暫存目錄**，讀取完畢後立即刪除，不得下載到工作目錄或任何 repo 內、不得用暫存檔傳遞其他中間成果。除此之外不產生任何本機檔案。
+- **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、交付摘要）一律留在**對話內容**與 **subagent 的回傳值**，並透過 `tea` 或 Gitea API **保存到議題描述或留言**。例外只有一個：為了讀取議題附件（圖片等二進位檔）而**唯讀暫存下載到系統暫存目錄**，讀取完畢後立即刪除，不得下載到工作目錄或任何 repo 內、不得用暫存檔傳遞其他中間成果。除此之外不產生任何本機檔案。
 
 ## 前置：輸入與工具
 
@@ -27,7 +27,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
   - **議題編號**：Gitea issue 編號或 issue URL，可多筆。
   - **檔案文件**：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。
 - **保存目標**：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。
-- **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，實作參考以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
+- **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，程式碼分析參考（僅供研究、補充議題描述，不修改）以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
 - **工具選擇**：依 `/jsc:spec-gitea` 的工具選擇流程（檢查 `tea`／`tea login list`／`GITEA_TOKEN` 後詢問使用者用 `tea` 或 `api`；已明確指定工具時才可跳過詢問；不依賴 `jq`，JSON 改用 tea 結構化輸出或交給 subagent 解析）。
 - **議題必須連同留言與附件一起讀取**：處理任何議題（含專案底下展開的議題）時，除了 `title`／`body` 等欄位，必須一併讀取**所有留言（comments）**與**所有附件（attachments/assets，含議題本身與各留言的附件）**，其內容都是需求分析的依據：
   - 附件清單：`tea` 目前沒有附件指令，一律走 API — 議題附件 `GET {base}/repos/{owner}/{repo}/issues/{index}/assets`、留言附件 `GET {base}/repos/{owner}/{repo}/issues/comments/{id}/assets`，取得每個附件的檔名、類型與下載 URL。
@@ -128,20 +128,12 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
 - 依 `/jsc:spec-project-board` 執行（欄位語意以看板實際名稱為準、不往回移、先 GET 探測端點且 404／501 視為不支援、不得對未確認端點寫入、不得新建欄位）：把議題移動到「待處理」欄位，代表需求分析已完成、等待實作；議題已在「待處理」或更後面的欄位時維持原欄位。
 - 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳。
 
-## 第 4 步：依到期日排序並逐議題實作
+## 第 4 步：依到期日排序並交棒實作
 
 將第 3 步產生的小功能議題依到期日由早到晚排序；若到期日相同，依相依關係排序，前置議題必須排在後置議題前。排序結果必須使用 `tea` 或 Gitea API 留言到保存議題或相關小功能議題，不得寫入本機檔案。
 
-開始實作前必須逐個議題詢問使用者，至少提供該議題的標題、URL（若已建立）、到期日、相依關係、預計修改範圍與驗證方式。未取得使用者確認前，不得修改任何原始碼、不得 commit、不得 push、不得開 PR。使用者確認開始實作某一議題後，即授權在該議題範圍內自行 commit、push 工作分支並開 PR，不需要對每個 git 動作再次詢問。
+**本 skill 的範圍到「議題拆分完成＋排序留言」為止，不實作程式碼**：不修改任何原始碼、不 commit、不 push、不開 PR、不關閉議題。排序留言完成後：
 
-使用者確認某一議題後，才可對該議題執行：
-
-- 建立或切換工作分支，分支名稱應包含議題編號或小功能識別。
-- 依議題描述實作，過程中定期將進度留言到該議題；至少包含開始實作、主要變更完成、驗證結果、PR 連結。
-- 只修改該議題必要範圍；若發現需要擴大範圍或改動其他議題，先停止並詢問使用者。
-- 執行適合專案的測試／建置／驗證；失敗時留言說明失敗原因與下一步。
-- 完成後提交變更並推送工作分支，向 `develop` 開 PR；若遠端沒有 `develop`，改向 `master` 開 PR。不得直接 push 到 `develop` 或 `master`。
-- PR 內容必須連結對應小功能議題，並摘要變更、測試結果、風險與需人工確認項目。
-- **關閉順序（子母議題）**：實作完成只關閉（或由 PR 合併帶關鍵字自動關閉）該小功能**子議題**，並同步勾選母議題子議題清單中的對應項目（若有）；**母議題必須等所有子議題都關閉後才可關閉** — 有 dependency 阻擋時由 Gitea 強制，否則依母議題的「關閉前檢查」人工確認。所有子議題關閉後，回報母議題已可關閉並詢問使用者是否關閉，不得擅自關閉母議題。
-
-若小功能議題尚未實際建立到 Gitea，本步只能產生排序與實作計畫，不得開始實作；必須先回到建立小功能議題的確認流程。
+- 回報整體結果：保存議題連結、小功能議題清單（標題／到期日／相依關係）、看板欄位調整狀況、標註「需人工確認」的項目。
+- 提示使用者後續可用 `/jsc:code-issues` 對這些小功能議題逐項實作（該 skill 會彙整 TODO、逐項實作並留言進度）；是否實作、何時實作由使用者另行決定，不在本 skill 範圍內。
+- **子母議題關閉規則的後續遵守**：提醒使用者（或後續實作流程）——子議題全部關閉前不得關閉母議題；有 dependency 阻擋時由 Gitea 強制，否則依母議題的「關閉前檢查」人工確認。