---
name: spec-issue-read
description: JSC plugins 共用「Gitea 議題讀取與需求彙整規範」：讀取議題必須含描述、所有留言與所有附件內容（不得只讀描述）、留言與附件分頁完整讀取（分頁規則見 spec-gitea，不重複細節）、彙整議題需求時不得臆測缺漏的部分，須詢問使用者或如實標記「未提及」。當其他 skill 內文引用 spec-issue-read 或 /jsc-shared:spec-issue-read、或讀取 Gitea 議題／彙整議題需求時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
---

# spec-issue-read — 共用 Gitea 議題讀取與需求彙整規範

所有 JSC skills 讀取 Gitea 議題並據以彙整需求時，一律遵守以下規範。

## 議題必須完整讀取，不能只讀描述

讀取任一議題（含專案看板底下展開的議題）時，至少必須取得：

| 欄位 | 說明 |
| --- | --- |
| `title`／`body`／`state` | 議題標題、描述、狀態 |
| `labels`／`milestone`／`assignees` | 既有分類與指派資訊 |
| **所有留言（comments）** | 不得只取第一頁或前幾則，見下節分頁規則 |
| **所有附件（attachments/assets）** | 議題本身與**每一則留言**各自的附件都要讀，見下節附件讀取 |

- `tea`：`tea issues <index> --repo <owner>/<repo> --comments` 取得本文與留言；`tea` 目前沒有附件指令，附件一律改走 API。
- `api`：`GET {base}/issues/{index}` 取得本文，`GET {base}/issues/{index}/comments` 取得留言。
- 留言中若有需求補充、變更或取消，必須納入需求彙整，並以**最新留言**為準；只讀描述、略過留言即視為讀取不完整，不得據此彙整需求或判定 TODO 完成度。

## 附件讀取

- 附件清單一律走 API（`tea` 無此功能）：
  - 議題附件：`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 並標註「附件無法讀取，需人工確認」，不得忽略附件的存在，也不得臆測其內容 |

## 分頁必須完整讀取

留言與附件清單都是分頁 API，完整分頁規則（持續累加 `page` 直到回傳筆數小於 `limit` 或回空陣列為止，不可只取第一頁）一律依 `/jsc-shared:spec-gitea` 的「API 呼叫慣例」執行，本規範不重複細節。

## 彙整需求時不得臆測

- 把議題描述與所有留言（含附件內容）整理成需求彙整（目標、驗收條件、限制條件）時，**只做歸納，不編造來源未提及的需求**。
- 來源之間說法不一致、範圍不明、驗收條件缺漏、附件無法讀取造成的資訊缺口等，一律先詢問使用者澄清；來不及或無法立即詢問時，如實在彙整內容中標記「未提及」或「需人工確認」，不得自行補完、猜測或以常見做法代填。
- 議題描述既有的 Markdown checklist（`- [ ]`／`- [x]`）視為既有 TODO 的一部分納入盤點；已勾選項目視為已完成，不重做，也不得因臆測而改判其完成狀態。