refactor(skills 共用規範): 抽出共用規範至 generic spec-*，以引用＋一行 fallback 摘要取代重複內容

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

skills/doc-issues-sync/SKILL.md

@@ -7,6 +7,15 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 
 你要讀取使用者提供的一個 Gitea **專案（project）**或**單一議題**，取得要同步的議題清單，然後一個議題派一個 subagent，**以目前工作目錄下的所有檔案為依據**，勾稽並更新每個議題的 TODO（markdown 任務清單）與標籤，最後把 TODO 的異動整理成留言。例外：輸入為專案且使用者指定「關閉專案／專案完成」時，進入**專案完成模式**（見第 1 步之後的專節），跳過標籤分組與逐議題勾稽，改為批次搬移至「已完成」並關閉議題。**修改議題正文、變更議題標籤、留言都是對外且不易復原的動作，subagent 只回傳同步計畫（不落地任何檔案），實際寫入 Gitea 前必須先讓使用者確認**。請依下列階段依序完成。
 
+## 共用規範（generic plugin，必要前置）
+
+執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
+
+- `/jsc:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。
+- `/jsc:spec-execution`：不臆測／需人工確認。
+- `/jsc:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（分頁完整讀取、GET 探測版本相依端點）。
+- `/jsc:spec-project-board`：看板欄位語意對應與建議欄位規則、404／501 視為不支援、不得新建欄位。
+
 ## 絕對準則（不可違反）
 
 - **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（議題清單、需求分析、追加後的正文、標籤異動、勾稽結果、留言內容）一律留在**對話內容**與 **subagent 的回傳值**裡。最終產物只透過 `tea` 或 Gitea API **寫回議題正文／標籤／留言**，除此之外不產生任何本機檔案。
@@ -18,10 +27,10 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 - **工具優先序**：
   1. 若該 host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment`、`tea labels` 等），並以 `--login <name> --repo <owner>/<repo>` 指定目標。
   2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定；未設定則停下請使用者提供）。
-- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
+- **不要依賴 `jq`**：依 `/jsc:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。
 - **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。
-- **專案進度欄位（project column）**：若議題屬於某個專案看板（project board），且看板欄位名稱可對應進度語意（例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，不得假設看板一定有這五欄），本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整；對應規則見第 3.5 步。欄位語意對不上或介面不支援時不移動，只回報建議。
-- **議題描述流程圖**：若要補進議題正文或進度留言的內容有助於理解（例如需求流程、TODO 之間的先後／相依），盡量加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）以視覺化呈現；流程圖必須忠實反映議題需求與 TODO 現況，不得杜撰未提及的流程。
+- **專案進度欄位（project column）**：依 `/jsc:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。
+- **議題描述流程圖**：依 `/jsc:spec-output` — 補進議題正文或進度留言的內容有助理解時（需求流程、TODO 先後／相依），加入 Mermaid 流程圖，忠實反映議題需求與 TODO 現況、不得杜撰。
 
 ## 第 0 步：解析輸入、判斷專案或議題、準備工具
 
@@ -81,12 +90,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 3. **3.2 依需求更新可用標籤**：依議題需求性質，從該 repo **既有標籤**中挑選應掛上（或應移除）的標籤，回傳內容中列出「建議的標籤異動」（新增哪些、移除哪些、維持哪些）。**不自行新建標籤**，除非使用者要求；找不到合適標籤就維持原樣並標註。
 4. **3.3 逐條勾稽未完成 TODO 是否已完成**：對所有**未完成**的 TODO（含 3.1 新增的），逐條依工作目錄下的檔案內容判斷是否已完成。已完成者標記為 `- [x]` 並在回傳內容記下判斷依據（以 `path:line` 指出對應實作位置）；無法從檔案可靠判斷者維持未完成並標註「需人工確認」。
 5. **3.4 整理 TODO 異動留言**：若本議題有任何 TODO 異動（**新增**的 TODO，或**狀態變更**——由未完成改為完成），整理成一則留言內容，包含：本次新增了哪些 TODO、哪些 TODO 判定為完成（附對應實作位置）、哪些仍未完成（含原因／需人工確認）。若沒有任何 TODO 異動，回傳標明「無異動、不需留言」。
-6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則（欄位名稱以看板實際名稱為準，語意相近即可對應）：
-   - 需求仍不明確、TODO 明顯不足以追蹤需求而需大量補列 → 「分析中」。
-   - 需求與 TODO 齊全，但工作目錄中尚無任何對應實作 → 「待處理」。
-   - 部分 TODO 已勾稽為完成（已有部分實作）→ 「進行中」。
-   - 所有 TODO 勾稽為已完成，但仍有「需人工確認」項目或尚待驗證 → 「待測試」。
-   - 所有 TODO 已完成且無需人工確認 → 「已完成」。
+6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則依 `/jsc:spec-project-board` 的建議欄位表（分析中／待處理／進行中／待測試／已完成，欄位名稱以看板實際名稱為準、語意相近即可對應）。
    回傳內容需含：目前欄位、建議欄位、判斷依據。建議欄位與目前欄位相同時標明「欄位無異動」；看板欄位語意對不上（或取不到欄位資訊）時標明「無法對應、維持原欄位」並列出實際欄位名稱，不得硬套。議題不屬於任何專案看板時跳過本項。
 
 每個 subagent **回傳**一份結構化同步計畫（**不落地成檔案**），至少包含：議題參照與標題、追加後的完整正文（標明新增與勾稽的變更）、建議的標籤異動、TODO 異動留言內容（或「無異動」）、專案進度欄位建議（目前欄位／建議欄位／判斷依據，或「不屬於專案看板」「無法對應」）、以及所有「需人工確認」項目。
@@ -123,11 +127,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
   - 更新前先重新讀一次議題正文，若與 subagent 讀到的版本已不同（他人期間有改動），停下該議題並回報，避免覆蓋他人變更。
 - **標籤異動**：套用建議的新增／移除。
   - tea：`tea labels`／issue 編輯對應指令；API：`POST`/`DELETE {base}/repos/{owner}/{repo}/issues/{index}/labels`（用既有 label id）。
-- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，把議題移到建議欄位。
-  - 先探測可用介面：`tea` 目前沒有 project 看板指令；Gitea REST 的 project／column 端點依版本而異，先以 GET 探測對應端點是否存在（回 404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。
-  - 介面可用 → 呼叫對應端點把議題移至建議欄位，一次一個議題並確認回應成功。
-  - 介面不可用 → 不視為錯誤：跳過移動，改在第 7 步回報中列出「議題 → 建議欄位」清單，請使用者到看板手動拖曳。
-  - 只在建議欄位確實存在於看板且語意對應明確時移動；有疑慮就不動並回報。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。
+- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，依 `/jsc:spec-project-board` 把議題移到建議欄位（先 GET 探測端點、404／501 視為不支援且不得對未確認端點寫入；介面可用時一次一個議題並確認回應成功；不可用時不視為錯誤，改在第 7 步回報列「議題 → 建議欄位」清單請使用者手動拖曳；只在欄位確實存在且語意對應明確時移動，有疑慮就不動並回報）。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。
 - **留言**：對有 TODO 異動的議題張貼留言。
   - tea：`tea comment --repo <owner>/<repo> --login <name> <index> "<留言內容>"`；API：`POST {base}/repos/{owner}/{repo}/issues/{index}/comments`，body `{"body":"<留言內容>"}`。
   - 無異動的議題不留言。
@@ -146,8 +146,6 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 - 「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」一律以**工作目錄下的檔案**為依據；無法可靠判斷就標「需人工確認」，不得臆測或編造需求未涵蓋的內容。
 - subagent 與各步驟只讀檔案與議題、只回傳結構化內容，**不得在磁碟寫任何檔案、不得修改任何工作目錄原始碼**。
 - 標籤只從既有標籤挑選，不自行新建（除非使用者要求）。
-- 進度欄位調整只在議題確實屬於專案看板、建議欄位存在於看板且語意對應明確、並經第 5 步使用者確認後執行；不得新建欄位、不得對未確認存在的 API 端點做寫入。介面不支援時只回報建議清單，不視為錯誤。
+- 進度欄位調整依 `/jsc:spec-project-board`，且必須經第 5 步使用者確認後執行。
 - 專案完成模式只在輸入為專案且使用者**明確**指定關閉／完成時進入；語意不明就用 AskUserQuestion 確認，不得自行認定。批次關閉議題前必須經使用者確認；含未完成 TODO 的議題要在確認時明確標出。不得透過此模式關閉不屬於該專案的議題。
-- 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。
-- 留言與回傳內容不得洩漏個資（PII）；若議題內容含個資，於回傳內容與留言中僅保留必要資訊或去識別化。
-- 回傳內容與留言以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。
+- JSON 解析（不依賴 `jq`）依 `/jsc:spec-gitea`；個資保護（PII）與語言規範依 `/jsc:spec-output`。