doc/skills/doc-issues-analyze/SKILL.md

name, description

name

description

doc-issues-analyze

讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取，附件內容一併納入需求分析），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，在產生保存議題前必須完整釐清需求、任何不清楚的部分都要詢問使用者、絕不臆測或編造，確認清楚後才將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時母議題必須所有子議題關閉後才可關閉，優先以 issue dependency 阻擋），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中/待處理/進行中/待測試/已完成），把議題移到「待處理」欄位（不往回移、介面不支援時改列建議清單請人工調整）；再依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。

分析多來源需求並保存為議題

你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 develop 或 master；實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR。所有中間成果都不准落地成草稿檔，必須一律使用 tea 或 Gitea API 保存到議題描述或留言。

絕對準則（不可違反）

• 全程不得在磁碟落地任何檔案：不建立 .docs/、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、實作進度、交付摘要）一律留在對話內容與 subagent 的回傳值，並透過 tea 或 Gitea API 保存到議題描述或留言。例外只有兩個：（1）使用者確認實作某議題後、在該議題範圍內對目標 repository 原始碼進行的正常程式修改與 git commit；（2）為了讀取議題附件（圖片等二進位檔）而唯讀暫存下載到系統暫存目錄，讀取完畢後立即刪除，不得下載到工作目錄或任何 repo 內、不得用暫存檔傳遞其他中間成果。除此之外不產生任何本機檔案。

前置：輸入與工具

• 輸入來源：使用者必須選擇要讀取的來源種類，可多選且數量必須 >= 1：
  • 專案編號：Gitea project 編號或可定位 project 的 URL／識別資訊；若選取專案編號，必須只讀取該專案下開啟中的議題（含可取得的卡片／欄位／描述）；也可作為保存整理結果的目標專案。
  • 議題編號：Gitea issue 編號或 issue URL，可多筆。
  • 檔案文件：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。
• 保存目標：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。
• repositories 位置：可另外指定本機含多個專案的資料夾；若未指定，實作參考以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
• 工具選擇：在解析與讀取 Gitea 來源前，先檢查本機是否可用 tea、tea login list 是否有對應 login、以及環境變數 GITEA_TOKEN 是否已設定；接著詢問使用者要使用 tea 或 Gitea REST API + curl + token。使用者已明確指定工具時才可跳過詢問。
• 不要依賴 jq（環境未安裝）：需要解析 JSON 時，用 tea 的結構化輸出（例如 --fields ... --output csv），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 jq。
• 議題必須連同留言與附件一起讀取：處理任何議題（含專案底下展開的議題）時，除了 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。
  • 文字類附件（Markdown、純文字、CSV、JSON 等）：以 curl 直接取得內容到對話中分析，不落地。
  • 圖片或其他二進位附件：依絕對準則的例外唯讀暫存下載到系統暫存目錄讀取（例如圖片以視覺方式讀取內容），讀取完畢後立即刪除暫存檔。
  • 無法讀取的格式（或僅有 tea 而無 token 可下載附件）：在保存議題內容中列出附件檔名與 URL 並標註「附件無法讀取，需人工確認」，不得忽略附件的存在，也不得臆測其內容。
• 禁止草稿落地：所有流程都不准建立 .docs/ 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 tea 或 Gitea API 保存到對應議題描述或留言。
• TODO list：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 ## TODO 區塊，使用 Markdown checklist（- [ ] ...）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。
• 議題描述流程圖：產生保存議題或小功能議題的描述時，若有助於理解，盡量在描述中加入 Mermaid 流程圖（```mermaid flowchart／stateDiagram，Gitea 可直接渲染），把需求流程、狀態轉移或議題間的相依／阻擋關係視覺化；流程圖必須忠實反映需求與拆分結果，不得杜撰未提及的流程。

第 1 步：工具可用性檢查與使用方式選擇

先檢查可用工具並選擇後續使用方式。除非使用者已明確指定 tea 或 api，否則不得自行決定。

1. 檢查 tea 是否存在：command -v tea。
2. 若 tea 存在，執行 tea login list，記錄可用 login 與其 host；若失敗，記錄失敗原因但不要中止。
3. 檢查 GITEA_TOKEN 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容。
4. 依檢查結果詢問使用者要使用哪一種方式：
   • tea：只有在 tea 可執行時才可選；後續解析來源後仍需確認來源 host 有對應 login。
   • api：只有在 GITEA_TOKEN 已設定時才可選；後續使用 Gitea REST API + curl，帶標頭 Authorization: token $GITEA_TOKEN。
5. 若兩種方式都不可用，停止並回報缺少 tea login 或 GITEA_TOKEN；不要要求使用者把 token 貼進對話。

第 2 步：選擇讀取來源、讀取內容並保存議題內容

這是必要決策。若使用者尚未明確提供來源種類，必須先詢問要讀取哪些來源種類，並要求至少選一種：

1. 專案編號。
2. 議題編號。
3. 檔案文件。

選定後收集對應輸入：

• 選「專案編號」：收集 project 編號或 project URL，並確認其 host／owner／repo／project id（若資訊不足，先詢問補齊）；後續必須只讀取該專案下開啟中的議題。
• 選「議題編號」：收集 issue 編號或 issue URL；若只提供編號，必須確認其 host／owner／repo。
• 選「檔案文件」：收集本機檔案路徑並確認存在；不存在的檔案先回報並請使用者修正。

合併整理後一定要建立一張保存議題：

• 若已提供專案編號，詢問是否使用該專案作為保存目標；使用者可改指定其他專案。
• 若未提供專案編號，必須詢問保存用專案編號或 project URL。
• 不得在缺少保存目標專案時繼續到對外建立議題的步驟。

接著執行：

1. 解析每一筆來源：
   • 專案：解析出 host、owner、repo、project id 或可定位 project 的資訊。
   • 議題：解析出 host、owner、repo、index（例如 https://<host>/<owner>/<repo>/issues/<index>）。
   • 檔案：解析出本機絕對路徑、檔名與格式。
2. 依第 1 步選定的工具建立每筆 Gitea 來源的存取設定：
   • tea：找出對應 host 的 login，後續命令一律帶 --login <name> --repo <owner>/<repo>。
   • api：base 為 https://<host>/api/v1/repos/<owner>/<repo>。
   • 若多筆專案／議題分屬不同 host，選擇 tea 時必須確認每個 host 都有對應 login；選擇 api 時同一個 GITEA_TOKEN 必須可存取全部專案／議題，否則在讀取階段回報權限不足並停止。
3. 顯示本次處理的基本資料，至少包含：
   • 選定工具：tea 或 api。
   • 若選 tea：每個 host 對應的 login 名稱；若選 api：顯示 GITEA_TOKEN 已設定，不顯示 token 內容。
   • 讀取來源種類：專案編號／議題編號／檔案文件，至少一種。
   • 來源專案：每筆 project 的 host、owner、repo、project id（若有）。
   • 來源議題：每筆 issue 的 URL、host、owner、repo、index（若有）。
   • 來源檔案：每筆檔案的路徑與格式（若有）。
   • 保存目標專案：host、owner、repo、project id。
   • target repositories 來源：使用者指定的 repositories 位置，或「以來源議題所在 repo／保存目標 repo 為準」。
4. 若使用者指定了 repositories 位置，先確認該路徑存在並列出其中的專案；若未指定，記錄「以來源議題所在 repo／保存目標 repo 為準」，並確認本機是否已 clone 對應 repo（沒有就在保存議題留言中標註需人工提供或 clone）。
5. 依選定來源讀取內容：
   • 專案：讀取 project 描述、欄位／卡片、project metadata，並只讀取該專案下開啟中的議題（若 API 有分頁必須完整分頁讀取；每筆議題都依「議題必須連同留言與附件一起讀取」完整讀取）。若 Gitea 版本不支援 project API 或無法由 project 取得開啟中的 issue 清單，標註「此 Gitea 版本不支援 project API，需人工處理」，並請使用者改提供議題編號或可匯出的 project 文件。
   • 議題：對每一筆 issue，讀取完整內容：title、body、state、labels、milestone、assignees、所有 comments、以及議題與各留言的所有附件（讀取方式見前置「議題必須連同留言與附件一起讀取」）；若 Gitea 版本支援，另讀該 issue 所屬 project。
   • 檔案文件：讀取文件全文；若格式無法直接讀取，標註需人工轉換或提供純文字／Markdown。
6. 同時盤點該 repo 既有的分類資源，供後續階段沿用：
   • 標籤：GET {base}/labels（tea：tea labels list）
   • 里程碑：GET {base}/milestones（tea：tea milestones list）
   • 專案（若該 Gitea 版本有此 API）：GET {base}/projects；若不支援就記錄「此 Gitea 版本不支援 project API，需人工處理」。
7. 需求釐清（產生保存議題前的必要關卡）：讀取完所有來源後、建立或更新保存議題前，必須先完整釐清需求才可以繼續：
   • 逐一盤點來源內容中所有不清楚、有歧義、互相矛盾、缺少上下文或無法確定的部分（包含：需求範圍不明、驗收條件缺漏、來源之間說法不一致、附件無法讀取造成的資訊缺口、名詞或系統指涉不明等）。
   • 只要有任何不清楚的部分，都必須以 AskUserQuestion 或對話詢問使用者，直到全部釐清；問題可分批詢問，但不得略過任何一項。
   • 絕對不可以幻想：不得用臆測、腦補或「合理推測」填補資訊缺口來代替詢問；使用者明確表示某項「先保留、之後再確認」時，才可在保存議題中將該項標註「需人工確認」後繼續。
   • 所有不清楚的部分都已由使用者釐清（或明確指示保留標註）之前，不得進入下一項建立或更新保存議題。
8. 把所有來源內容彙整成保存議題內容，使用 tea 或 Gitea API 建立或更新保存議題；不得寫入本機草稿檔。保存議題描述至少包含：
   • 來源清單：每筆專案／議題／檔案的來源資訊、標題或名稱、狀態、現有 labels／milestone／project（若適用），以及議題的留言數與附件清單（檔名；無法讀取的附件標註「需人工確認」）。
   • 完整需求描述：整合專案、議題（含留言與附件內容）、檔案文件的內容，去除重複、補齊上下文，形成單一連貫的需求敘述。
   • 驗收條件／預期結果：能從來源內容推得的，逐條列出；不能確定的標註「需人工確認」。
   • 保存議題分類：labels／milestone／project 掛載方式。
   • ## TODO：根據保存議題描述內容產生 Markdown checklist，放在描述最後。

需求彙整只做整理與歸納，不得編造來源內容未提及的需求；無法確定處必須依上方「需求釐清」關卡先詢問使用者，只有使用者明確指示保留的項目才可標註「需人工確認」後寫入。

第 3 步：拆分小功能議題

將第 2 步保存到議題的內容拆分成多個小功能議題，使用 tea 或 Gitea API 建立／更新小功能議題或將小功能清單留言到保存議題；不得寫入本機草稿檔。每個小功能議題至少包含：

• 標題：能清楚表示單一小功能交付範圍。
• 描述：描述內容必須先詢問使用者想要包含哪些段落或資訊，至少提供可選項，例如需求背景、功能範圍、驗收條件、技術提示、測試方式、相依關係、風險與備註；依使用者選擇組成描述，不得自行固定格式。每個小功能議題建立或更新前，都必須逐一詢問使用者該議題描述是否有補充內容；使用者提供補充時，必須整合到該小功能議題描述中，若使用者明確表示沒有補充才可繼續建立或更新。描述最後必須加入 ## TODO 區塊，根據該小功能描述內容產生 Markdown checklist。
• 阻擋關閉：小功能議題建立後必須以可追溯方式阻擋其被直接關閉，直到驗收條件完成。可用方式包含加上既有 blocking／blocked 類標籤、在 body 中加入「關閉前檢查清單」、建立與保存議題的追溯連結，或依 Gitea 支援能力設定 issue dependency；不得使用不存在的標籤或 API，找不到支援方式時標註需人工處理。若小功能有前後相依，較先完成的前置議題必須阻擋較後完成的後置議題（前置 issue blocks 後置 issue；後置 issue is blocked by 前置 issue），不得反向設定。
• 複雜度：依工作量、跨模組程度、風險、未知數與測試成本評估為 S／M／L／XL。
• 到期日：根據複雜度評估 due date，預設從建立日往後推算：S 3 個工作天、M 5 個工作天、L 10 個工作天、XL 15 個工作天；若遇週末順延到下一個工作天。若小功能有相依關係，必須先排定相依順序，後置功能的到期日不得早於其前置功能的到期日，且應從最後一個前置功能的到期日之後再依自身複雜度推算。若 Gitea API 不支援 due date，寫入 issue body 並回報需人工設定。
• 相依關係：列出與保存議題、來源議題與其他小功能議題的關聯；若有前後依賴，必須標明前置功能、後置功能、阻擋方向與到期日排程依據。

子母議題關閉規則：若本次拆分實際建立了子母關係（保存議題為母議題、拆出的小功能議題為子議題），母議題必須在所有子議題都關閉後才可關閉，建立子議題時就要把這個限制落實：

• 優先用 Gitea issue dependency 實作：把母議題設為 blocked by 每一個子議題（API POST {base}/issues/{母議題 index}/dependencies，body 帶子議題資訊；先以 GET 探測該實例是否啟用 dependency 功能，404／501 視為不支援），讓 Gitea 在子議題尚未全部關閉前直接阻止關閉母議題。
• dependency 不支援或未啟用時：在母議題描述加入「子議題清單」markdown 任務清單（每項連結一個子議題，例如 - [ ] #<index> <子議題標題>）與「關閉前檢查：所有子議題皆已關閉」字樣，並在回報中標註此限制需人工遵守；不得對未確認存在的端點做寫入。
• 後續新增或補拆子議題時，必須同步補上對應的 dependency 或母議題子議題清單項目，不得遺漏。

決定要對照的 target repositories：使用者指定位置底下的所有專案、來源議題所在 repo，或使用者指定 repo。可研究相關專案程式碼以補充小功能議題描述，但所有分析結果必須直接保存到小功能議題描述或留言，不得建立本機草稿檔。

分析完成後：把議題移到看板「待處理」欄位。保存議題與所有小功能議題都建立／更新完成後（即分析階段結束），對其中**確實屬於某個專案看板（project board）**的議題調整進度欄位：

• 若看板欄位名稱可對應進度語意（例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板實際欄位名稱為準，語意相近即可對應，不得假設看板一定有這五欄），把議題移動到「待處理」欄位，代表需求分析已完成、等待實作。
• 不往回移：議題已在「待處理」或更後面的欄位（進行中／待測試／已完成）時維持原欄位，只有在「分析中」或未指定欄位時才移動。
• 移動前先探測可用介面：tea 目前沒有 project 看板指令；Gitea REST 的 project／column 端點依版本而異，先以 GET 探測端點是否存在（404／501 視為該實例不支援），不得對未確認存在的端點做寫入。
• 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳；不得新建欄位。

第 4 步：依到期日排序並逐議題實作

將第 3 步產生的小功能議題依到期日由早到晚排序；若到期日相同，依相依關係排序，前置議題必須排在後置議題前。排序結果必須使用 tea 或 Gitea API 留言到保存議題或相關小功能議題，不得寫入本機檔案。

開始實作前必須逐個議題詢問使用者，至少提供該議題的標題、URL（若已建立）、到期日、相依關係、預計修改範圍與驗證方式。未取得使用者確認前，不得修改任何原始碼、不得 commit、不得 push、不得開 PR。使用者確認開始實作某一議題後，即授權在該議題範圍內自行 commit、push 工作分支並開 PR，不需要對每個 git 動作再次詢問。

使用者確認某一議題後，才可對該議題執行：

• 建立或切換工作分支，分支名稱應包含議題編號或小功能識別。
• 依議題描述實作，過程中定期將進度留言到該議題；至少包含開始實作、主要變更完成、驗證結果、PR 連結。
• 只修改該議題必要範圍；若發現需要擴大範圍或改動其他議題，先停止並詢問使用者。
• 執行適合專案的測試／建置／驗證；失敗時留言說明失敗原因與下一步。
• 完成後提交變更並推送工作分支，向 develop 開 PR；若遠端沒有 develop，改向 master 開 PR。不得直接 push 到 develop 或 master。
• PR 內容必須連結對應小功能議題，並摘要變更、測試結果、風險與需人工確認項目。
• 關閉順序（子母議題）：實作完成只關閉（或由 PR 合併帶關鍵字自動關閉）該小功能子議題，並同步勾選母議題子議題清單中的對應項目（若有）；母議題必須等所有子議題都關閉後才可關閉 — 有 dependency 阻擋時由 Gitea 強制，否則依母議題的「關閉前檢查」人工確認。所有子議題關閉後，回報母議題已可關閉並詢問使用者是否關閉，不得擅自關閉母議題。

若小功能議題尚未實際建立到 Gitea，本步只能產生排序與實作計畫，不得開始實作；必須先回到建立小功能議題的確認流程。