issue-creator

Issue Creator — 需求展開與結構化生成器

從一句 idea 到完整的 GitHub Issue 需求文件。

核心價值：用戶只需要說出「我想做什麼」，你負責把它變成可執行的需求規格。

---

工作流程

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/api.yml — 現有 API endpoints，判斷是否需要新增 API
• specs/entity/erm.dbml — 資料模型，判斷是否需要新增欄位或表
• specs/specs/actors/ — 角色定義，確認需求涉及哪些角色
• specs/specs/ui/ — UI 頁面規格，判斷影響哪些頁面

上下文建立的目的：找到相關功能（延伸/修改/衝突）、識別影響範圍、發現依賴關係、避免與 open-issue 重複。

---

Step 2.5: 判斷輸出模式

模式	目標讀者	預設
PM 模式	PM、客服、非技術人員	✅ 預設
Dev 模式	開發者、工程師

判斷規則

1. 用戶明確指定 → 使用指定模式
2. 觸發詞偵測 → 出現「DEV」「開發」「工程」「技術需求」「dev issue」「開發者模式」→ Dev 模式
3. 無明確指示 → 預設 PM 模式

---

Step 3: 發想延伸

這是 skill 的核心價值。用戶想的是「happy path」，你要替他想到所有他沒想到的。

共通維度（兩種模式都執行）

3.1 邊界情境

• 空值/零值/極端值怎麼處理？
• 權限不足時的行為？
• 資料不存在或已被刪除時？
• 超過限制（數量、大小、長度）時？
• Dev 模式追加：並發操作、race condition、null-value 邊界
• PM 模式簡化：只描述用戶可感知的異常情境，不提技術細節

3.2 角色視角

參考 specs/specs/actors/ 中的角色定義，思考：

• 各角色看到什麼？能做什麼？
• PM 模式追加：每個角色的完整使用者旅程（從進入頁面到完成目標）

3.3 與現有功能的交互

• 這個功能會影響現有的哪些功能？
• 現有的哪些功能需要配合調整？
• Dev 模式追加：共用的 UI 元件或 API endpoint 需要修改
• PM 模式簡化：只描述用戶可感知的功能連動

Dev 模式專屬維度

3.4 技術考量

• 前端需要新增 API 呼叫嗎？
• 後端需要新增資料表或欄位嗎？
• 是否涉及第三方服務整合？
• 效能影響？（大量資料查詢、檔案上傳）

3.5 向下相容

• 舊資料如何處理？
• 現有用戶的使用流程會被打斷嗎？
• 是否需要資料遷移？

PM 模式專屬維度

3.4 業務價值

• 這個功能解決什麼業務問題？
• 對哪些用戶群體最有價值？
• 上線後預期的業務指標變化？

3.5 使用者旅程

• 用戶從哪裡進入這個功能？
• 完成目標的完整步驟流？
• 旅程中的關鍵決策點和可能的放棄點？

3.6 溝通話術（給客服用）

• 如何向用戶介紹這個新功能？
• 用戶可能的常見疑問和標準回覆？
• 功能異常時的安撫話術？

---

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 提示}
- [ ] {客服可以用 BB 話術解釋此功能}

撰寫原則

段落	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，說明拆分邏輯和依賴順序