2026-07-14 07:09:11 +00:00
3 changed files with 3 additions and 0 deletions
@@ -15,6 +15,7 @@ description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gite
  2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定）。
 - **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
 - **工作目錄**：所有草稿與文件放在 `.docs/doc-issues-analyze-to-file/`。
+- **議題描述流程圖**：產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，若有助於理解，盡量加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染），把該階段的處理流程、狀態轉移或與其他階段的相依關係視覺化；流程圖必須忠實反映需求與拆分結果，不得杜撰未提及的流程。

 ## 第 0 步：解析 issue URL 與準備工具

@@ -23,6 +23,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
 - **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
 - **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。
 - **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。
+- **議題描述流程圖**：產生保存議題或小功能議題的描述時，若有助於理解，盡量在描述中加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染），把需求流程、狀態轉移或議題間的相依／阻擋關係視覺化；流程圖必須忠實反映需求與拆分結果，不得杜撰未提及的流程。

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

@@ -20,6 +20,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
  2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定；未設定則停下請使用者提供）。
 - **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
 - **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。
+- **議題描述流程圖**：若要補進議題正文或進度留言的內容有助於理解（例如需求流程、TODO 之間的先後／相依），盡量加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）以視覺化呈現；流程圖必須忠實反映議題需求與 TODO 現況，不得杜撰未提及的流程。

 ## 第 0 步：解析輸入、判斷專案或議題、準備工具