Merge pull request 'feat/guided-requirement-completion/main' (#87) from feat/guided-requirement-completion/main into master

Reviewed-on: #87 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
2026-09-23 02:28:53 +00:00
parent fdd5696c7b 2b61c4e235
commit 4d360ad266
2 changed files with 74 additions and 5 deletions
@@ -7,23 +7,33 @@ description: 僅由 /sdlc-plan 指令叫用。把一段口語需求轉成結構

 ## 步驟

+開始前讀取 `references/requirements-discovery.md`。它是需求內容品質與建立前完整性閘門的規則正本；本流程只補充操作順序與 Gitea 交付步驟。
+
 ### 1. 列出九段落依據與缺漏〔可委派〕

-讀齊輸入，列出總覽、背景、目標、非目標、領域名詞表、文件、驗收標準、影響範圍與未決事項中已有依據與缺漏。這一步只產出可核對的清單；你的環境若能把工作交給子代理，就交出去，只把清單帶回來；不能就自己做。
+讀齊輸入，列出總覽、背景、目標、非目標、領域名詞表、文件、驗收標準、影響範圍與未決事項中已有依據與缺漏。對每一段不只檢查是否非空，還要依需求補全規則檢查實質內容。這一步只產出可核對的清單；你的環境若能把工作交給子代理，就交出去，只把清單帶回來；不能就自己做。

 ### 2. 一次問一題補齊缺漏

-一次問一題補齊缺漏；未獲回答的內容放入「未決事項」，不得自行編造。
+依需求補全規則挑出下一個最高價值的需求缺口。每次只問一題，並同時列出目前理解、缺少內容、為什麼需要，以及建議選項或短範例；明確允許使用者自由改寫答案。

-### 3. 填入需求議題模板
+能從輸入、既有議題或可取得的 repo 內容查證的事項先自行查證；只有需要需求擁有者決策的事項才提問。不得把推測或實作方案寫成已確認需求。
+
+每次收到回答後更新工作稿，重新檢查角色、情境、行為、可觀察結果，以及主要成功情境與適用的失敗／邊界情境。未回答、「不知道」或「尚未決定」仍是缺口，繼續一次問一題；只有使用者明確確認「不適用」並說明原因，才可標記該項完成。
+
+### 3. 建立前完整性閘門
+
+套用 `references/requirements-discovery.md` 的完整性閘門。九段落都必須有實質內容，或由使用者確認不適用並說明原因；不得留下未回答或「尚未決定」的缺口。未通過閘門前不得套用模板、查標籤或建立議題。
+
+### 4. 填入需求議題模板

 套用 `templates/requirement-issue.md`，填入總覽、背景、目標、非目標、領域名詞表、文件、驗收標準、影響範圍與未決事項；全程使用繁體中文。

-### 4. 取得既有標籤
+### 5. 取得既有標籤

 用 `scripts/labels-list.js` 取得既有標籤，只能選既有標籤。

-### 5. 試跑並建立議題
+### 6. 試跑並建立議題

 寫入前先執行：

@@ -0,0 +1,59 @@
+# 需求補全規則
+
+這份文件是 `/sdlc-plan` 判斷需求內容是否足夠清楚、可驗收的規則正本。
+
+## 需求的四個必要維度
+
+每個需要實作的需求都要能回答：
+
+1. **角色** — 誰需要這個結果，或誰執行這個行為？
+2. **情境** — 在什麼觸發條件、前置條件或使用情境下發生？
+3. **行為** — 角色做了什麼，或系統需要處理什麼？
+4. **可觀察結果** — 外部使用者、呼叫端或驗收者能觀察到什麼結果？
+
+只寫功能名稱、畫面名稱、API 名稱或實作方法，不足以視為完成。
+
+## 情境覆蓋
+
+- 至少確認主要成功情境。
+- 若需求有權限、取消、重試、空值、重複執行、並行、極大量或外部來源失敗等可能性，逐一確認適用的失敗或邊界情境。
+- 不適用的情境必須由使用者明確確認「不適用」，並說明原因；agent 不得自行判定。
+
+## 提問格式
+
+一次只問一個最高價值的缺口。每題依序提供：
+
+- **目前理解**：根據輸入與已確認回答整理的一句話。
+- **缺少內容**：指出哪個必要維度或情境仍不清楚。
+- **為什麼需要**：說明它會影響哪個目標、範圍或驗收結果。
+- **建議回答**：提供具體選項或短範例。
+- **自由回答**：明確允許使用者改寫或提供其他答案。
+
+建議選項是協助理解，不是替使用者做決策。
+
+## 查證與提問邊界
+
+- 能從輸入、既有議題或可取得的 repo 內容查證的事項，先自行查證。
+- 只有需要需求擁有者決策的事項才提問。
+- 不把架構、資料表、模組或其他實作方案當成需求答案；這些交給 `/sdlc-analyze`。
+- 不把 agent 的推測寫成使用者已確認的需求。
+
+## 回答狀態
+
+- 具體回答可填入工作稿，並重新檢查所有必要維度與情境。
+- 使用者明確確認「不適用」且提供原因，可標記該項已完成。
+- 未回答、拒絕回答、「不知道」或「尚未決定」都仍是缺口，不得填成已確認。
+- 仍有缺口時不得建立需求議題；應繼續一次問一題。
+
+## 建立前完整性閘門
+
+建立需求議題前必須確認：
+
+- 九個段落都有實質內容，或使用者已確認不適用並說明原因。
+- 需求的角色、情境、行為與可觀察結果完整。
+- 主要成功情境已確認；適用的失敗與邊界情境已確認。
+- 沒有未回答或「尚未決定」的阻塞缺口。
+- 驗收標準描述外部可觀察結果，不綁定不必要的實作細節。
+- 內容前後一致，且非目標足以限制範圍。
+
+通過閘門後才可套用需求議題模板、查標籤與建立議題。