issue-spec-prep

name	issue-spec-prep
description	在 branch-ticket-issue-doc 已於所選開發工作區建立 docs/issues/<ticket-id>.md、且 Codex 需要建立或更新 docs/issues/specs/<ticket-id>.md 作為該 issue 的實作 spec 時使用此 skill；先讀 issue 文件，僅在必要時檢視程式碼，且不實作程式碼變更。

Issue Spec Prep

在 branch-ticket-issue-doc 之後使用此 skill。

目標：從 issue 文件與當前 worktree 的程式碼脈絡，建立或更新 docs/issues/specs/<ticket-id>.md。

在此處不要變更產品程式碼。在此處不要執行實作重構。

前置條件

1. 確認當前目錄是 ticket-id-dev-prep 所選的開發工作區。
2. 從使用者輸入、分支名稱或既有 issue 文件解析 ticket id。
3. 先讀取 docs/issues/<ticket-id>.md。
4. 若 issue 文件缺失，停下並先執行 branch-ticket-issue-doc。
5. 若 docs/issues/specs/ 不存在則建立。

工作流程

1. 讀取 docs/issues/<ticket-id>.md。
2. 擷取：
   • 問題陳述
   • 預期與實際行為
   • 受影響的流程
   • 已知事實、推論與待解問題
3. 只檢視足以讓 spec 可執行的程式碼：
   • 可能的檔案或模組
   • 當前邏輯邊界
   • 既有測試或缺漏的測試面
   • 共用工具或重複的流程
4. agy 優先策略：收集完 issue doc 內容與程式碼觀察後，優先委派 antigravity-cli（agy）生成 spec 文件本文：
   • 透過 Bash 以 stdin 管道委派（printf '%s' "<填入下方 prompt>" | agy -p --print-timeout 180s），prompt 如下（以實際資料填入；務必在結尾要求「只輸出 spec 本文，不要任何開場白或人設評論」）：

     你是一位資深 Flutter 工程師，請根據以下問題描述與程式碼觀察，用繁體中文撰寫一份實作規格文件（保留英文技術術語）。
     
     Ticket: <ticket-id> - <ticket summary>
     
     Issue 文件內容：
     <docs/issues/<ticket-id>.md 完整內容>
     
     程式碼觀察（已檢視的相關模組、邏輯邊界、測試缺口）：
     <Claude 的 rg / file read 觀察摘要>
     
     請嚴格按照以下 markdown 結構輸出，每個段落用簡潔的條列式說明：
     
     # <TICKET-ID> Spec
     
     ## 背景
     
     ## 目標
     
     ## 非目標
     
     ## 目前行為
     
     ## 目標行為
     
     ## 修正策略
     
     ## 影響範圍
     
     ### Affected Files / Modules
     
     ## Acceptance Criteria
     
     ## Test Plan
     
     ### Automated
     
     ### Manual
     
     ## Regression Risk
     
     ## Open Questions
     
     規則：
     - Acceptance Criteria 必須描述可觀察的行為
     - Test Plan 需具體指出 unit / widget / bloc / integration / manual 類型
     - 若有未知項目會阻塞實作，在 Open Questions 中清楚標記
     - 不要發明 issue 文件中未提及的需求
     只輸出 spec 文件內容，不要其他說明。
     

   • 若 agy 成功回傳包含 ## 背景 與 ## Acceptance Criteria 的 spec 結構，採用其內容。
   • 後處理（必做）：agy 會讀取全域 CLAUDE.md 而附加 Linus 人設框架，且可能在生成時順手建立暫存檔。採用前須剝除人設包裝、只取目標 spec 結構；並確認 agy 未在工作區誤建檔案（如有則刪除）。docs/issues/specs/<ticket-id>.md 一律由 Claude 自行 Write 寫入，不依賴 agy 落檔。
   • 若 agy 不在 PATH、呼叫失敗或回傳格式不合法，回退至步驟 5 自行撰寫 spec。
5. （Fallback）自行撰寫並建立或更新 docs/issues/specs/<ticket-id>.md，依照 Spec Template。
6. 讓 acceptance criteria 保持可測試。
7. 讓 open questions 保持可見；不要把未知項目轉成需求。
8. 在實作前停下。

檔案命名

使用：

docs/issues/specs/<TICKET-ID>-<description-suffix>.md

其中 <description-suffix> 取自當前分支名稱的最後一段路徑，並移除開頭的 ticket id 部分。

範例：

• Branch：fix/202605/BUG-2362-some-feature-fix
• 最後一段：BUG-2362-some-feature-fix
• Description suffix：some-feature-fix
• 檔案：docs/issues/specs/BUG-2362-some-feature-fix.md

執行以下指令解析 suffix：

git rev-parse --abbrev-ref HEAD | sed 's|.*/||' | sed 's/^[A-Z][A-Z]*-[0-9]*-//'

保留 ticket id 的大小寫。

Spec Template

使用此結構：

# <TICKET-ID> Spec

## 背景

## 目標

## 非目標

## 目前行為

## 目標行為

## 修正策略

## 影響範圍

### Affected Files / Modules

## Acceptance Criteria

## Test Plan

### Automated

### Manual

## Regression Risk

## Open Questions

偏好簡短、具體的條列。

Spec 規則

• 需求以 issue 文件為依據。
• 利用程式碼檢視來提升可行性，而非發明產品意圖。
• 只在已檢視或有強烈跡象時提及確切檔案。
• Acceptance criteria 必須描述可觀察的行為。
• Test plan 應指明可能的 unit、widget、bloc、integration 或 manual 檢查。
• 若某個 open question 會阻塞實作，明確說明。

輸出規則

偏好的輸出：

1. Spec：建立或更新的路徑
2. 依據：issue 文件路徑與已檢視的程式碼脈絡
3. 修正方向：簡短摘要
4. 測試重點
5. 阻塞：僅當 open questions 阻塞實作時
6. Next：只有在沒有阻塞性問題殘留時，實作才能開始

風格規則

• 主要語言：zh-tw
• 保留必要的 en-us 技術術語，例如 Acceptance Criteria、Test Plan、API、UI、Widget、Bloc
• 保持精簡且聚焦於 spec