| name | issue-creator |
| description | 從用戶的粗略需求出發，結合專案 specs（features、activities、open-issue）自動延伸，生成結構化 GitHub Issue 需求文件。觸發：「建立需求」、「開 issue」、「寫需求」、「新功能需求」、「feature request」、「我想做一個功能」、「需求文件」。預設 PM 模式；提到「DEV」、「開發」、「工程」、「技術需求」、「dev issue」時切換 Dev 模式。模式詳述見 SKILL.md。 |
Issue Creator — 需求展開與結構化生成器
從一句 idea 到完整的 GitHub Issue 需求文件。
核心價值：用戶只需要說出「我想做什麼」，你負責把它變成可執行的需求規格。
邊界區分：「新功能 idea」語句可能同時觸發本 skill 與 zenbu-powers:brainstorming，依產出物分流——
要產出 GitHub Issue 需求文件（可直接貼上 GitHub 的結構化需求）→ 本 skill（issue-creator）；
要探索方案、比較 approach、寫 design.md（含設計審查 gate）→ zenbu-powers:brainstorming。
工作流程
Step 1: 理解用戶的 idea
Step 2: 掃描 specs/ 建立專案上下文
Step 2.5: 判斷輸出模式（PM 預設 / Dev）
Step 3: 發想延伸 — 共通維度 + 模式專屬維度
Step 4: 生成結構化需求（依模式切換模板）
Step 5: 直接輸出到終端機
Step 1: 理解用戶的 idea
用戶的輸入可能是：
- 一句話：「我想加一個課程評分功能」
- 一段描述：包含部分背景和期望行為
- 一個 bug 轉需求：「現在 XX 行為不對，應該改成 YY」
無論輸入多粗略，不要回問太多問題。先根據專案上下文做出合理假設，把完整需求生出來，讓用戶在看到成品後修改，比來回問答更高效。
如果需求有明顯的歧義（例如同一句話可以解讀成兩種完全不同的功能），才簡短確認。
Step 2: 掃描 specs/ 建立專案上下文
讀取 ./specs 目錄結構，建立對現有系統的理解：
必讀
specs/features/ — 所有已定義的 Gherkin feature files，理解系統現有功能邊界specs/activities/ — 業務流程定義，理解功能在流程中的位置specs/open-issue/ — 進行中的需求，避免重複或衝突
按需讀取
specs/api.yml — 現有 API endpoints，判斷是否需要新增 APIspecs/erm.dbml — 資料模型，判斷是否需要新增欄位或表specs/actors/ — 角色定義，確認需求涉及哪些角色specs/ui/ — UI 頁面規格，判斷影響哪些頁面
上下文建立的目的：找到相關功能（延伸/修改/衝突）、識別影響範圍、發現依賴關係、避免與 open-issue 重複。
Step 2.5: 判斷輸出模式
| 模式 | 目標讀者 | 預設 |
|---|
| PM 模式 | PM、非技術人員 | ✅ 預設 |
| Dev 模式 | 開發者、工程師 | |
判斷規則
- 用戶明確指定 → 使用指定模式
- 觸發詞偵測 → 出現「DEV」「開發」「工程」「技術需求」「dev issue」「開發者模式」→ Dev 模式
- 無明確指示 → 預設 PM 模式
Step 3: 發想延伸
這是 skill 的核心價值。用戶想的是「happy path」，你要替他想到所有他沒想到的。
共通維度（兩種模式都執行）
3.1 邊界情境
- 空值/零值/極端值怎麼處理？
- 權限不足時的行為？
- 資料不存在或已被刪除時？
- 超過限制（數量、大小、長度）時？
- Dev 模式追加：並發操作、race condition、null-value 邊界
- PM 模式簡化：只描述用戶可感知的異常情境，不提技術細節
3.2 角色視角
參考 specs/actors/ 中的角色定義，思考：
- 各角色看到什麼？能做什麼？
- PM 模式追加：每個角色的完整使用者旅程（從進入頁面到完成目標）
3.3 與現有功能的交互
- 這個功能會影響現有的哪些功能？
- 現有的哪些功能需要配合調整？
- Dev 模式追加：共用的 UI 元件或 API endpoint 需要修改
- PM 模式簡化：只描述用戶可感知的功能連動
Dev 模式專屬維度
3.4 技術考量
- 前端需要新增 API 呼叫嗎？
- 後端需要新增資料表或欄位嗎？
- 是否涉及第三方服務整合？
- 效能影響？（大量資料查詢、檔案上傳）
3.5 向下相容
- 舊資料如何處理？
- 現有用戶的使用流程會被打斷嗎？
- 是否需要資料遷移？
PM 模式專屬維度
3.4 業務價值
- 這個功能解決什麼業務問題？
- 對哪些用戶群體最有價值？
- 上線後預期的業務指標變化？
3.5 使用者旅程
- 用戶從哪裡進入這個功能？
- 完成目標的完整步驟流？
- 旅程中的關鍵決策點和可能的放棄點？
Step 4: 生成結構化需求
依據 Step 2.5 判斷的模式，選擇對應模板。每個段落都要有實質內容，不要留佔位符。
Dev 模式模板
## 背景資訊
{描述目前系統的相關現狀。包含：}
{- 現有功能是怎麼運作的}
{- 為什麼需要這個新功能/改動}
{- 相關的現有 specs 引用（列出路徑）}
## 任務目標
{用「動詞 + 對象 + 條件」格式，條列式：}
{- 新增「XX」按鈕，點擊後開啟 YY 面板}
{- 當 ZZ 條件成立時，自動觸發 AA 動作}
## 情境案例
{每個情境：前提條件 → 操作步驟 → 預期結果}
### 情境 1: {Happy Path}
- 前提：...
- 操作：...
- 預期：...
### 情境 2: {邊界情境}
- 前提：...
- 操作：...
- 預期：...
### 情境 3: {錯誤處理}
- 前提：...
- 操作：...
- 預期：...
## 影響範圍
### 前端
| 檔案 | 變更類型 | 說明 |
|------|---------|------|
| `js/src/...` | 新增/修改 | ... |
### 後端
| 檔案 | 變更類型 | 說明 |
|------|---------|------|
| `inc/classes/...` | 新增/修改 | ... |
### 資料庫
{是否需要新增欄位/表？如果不需要就寫「無影響」}
## 注意事項
{開發時容易踩的坑：相容性、效能、安全性（權限/驗證）、第三方限制}
## 驗收標準
- [ ] {具體的驗證項目 1}
- [ ] {具體的驗證項目 2}
- [ ] {具體的驗證項目 3}
PM 模式模板
## 背景資訊
{用非技術語言描述目前的現況：}
{- 用戶現在怎麼完成這件事}
{- 這個改動帶來什麼好處}
{- 相關的現有功能（用功能名稱，不用檔案路徑）}
## 任務目標
{用「用戶可以...」的格式，條列式說明：}
{- 用戶可以在 XX 頁面看到 YY 按鈕}
{- 用戶點擊後可以完成 ZZ 操作}
## 使用者旅程
### 旅程 1: {主要流程}
- 角色：{具體角色名，如「學員小明」}
- 目標：{用戶想完成什麼}
- 步驟：{進入頁面 → 操作 → 看到結果}
- 開心路徑結果：{預期的成功畫面}
### 旅程 2: {異常流程}
- 角色：{具體角色名}
- 情境：{什麼情況下會遇到問題}
- 系統回應：{用戶看到什麼提示}
### 旅程 3: {其他角色}
- 角色：{不同角色名}
- 目標：{這個角色想完成什麼}
- 步驟：{進入頁面 → 操作 → 看到結果}
## 業務影響
{這個功能影響哪些業務面向：}
- 影響的用戶群體：{哪些角色、大約多少人}
- 影響的現有流程：{哪些操作流程會改變}
- 預期效益：{省時、減少客訴、提升轉換率等}
## 風險與注意事項
{非技術面的風險：}
{- 用戶可能混淆的操作}
{- 需要公告或教學引導的地方}
{- 與現有使用習慣衝突的改動}
## 驗收標準
{用「用戶可以...」的語言，checkbox 格式}
- [ ] {用戶可以在 XX 看到 YY}
- [ ] {當 ZZ 時，用戶會看到 AA 提示}
撰寫原則
| 段落 | Dev 模式 | PM 模式 |
|---|
| 背景資訊 | 引用 specs 檔案路徑 | 用功能名稱，不提路徑 |
| 目標描述 | 「動詞 + 對象 + 條件」 | 「用戶可以...」 |
| 情境/旅程 | 「前提→操作→預期」，引用具體數據 | 角色故事，給角色取名字 |
| 影響範圍 | 列出可能修改的檔案（不確定標「待確認」） | 描述受影響的用戶群和流程 |
| 注意事項 | Step 3 提取 3-5 個技術注意點 | 聚焦 UX 風險和溝通需求 |
| 驗收標準 | 技術可驗證語言 | 用戶可觀察行為 |
至少 3 個情境/旅程。參考現有 feature files 中的 Background 資料作為範例數據。如果影響範圍無法判斷就省略。
Step 5: 輸出
直接將完整的 markdown 輸出到終端機上。不要寫入檔案，讓用戶自行複製到 GitHub Issue。
輸出前標示模式：以下是生成的需求文件（{PM 模式 / Dev 模式}），可直接複製到 GitHub Issue：
輸出後提示：如需調整，請告訴我哪個段落要修改。如需切換模式，請說「切換 Dev 模式」或「切換 PM 模式」。
特殊情境處理
- idea 太模糊：不確定處用
⚠️ 待確認：... 標記，列出假設放在需求最前面，仍生成完整結構讓用戶修改
- 與現有功能衝突：在背景資訊中指出衝突點，在注意事項中說明處理方式
- 跨多個模組：建議拆分成多個 issue，說明拆分邏輯和依賴順序
