@educa-corp/sdd-framework 0.1.0

package/commands/propose-scenario.tmpl

@@ -0,0 +1,133 @@
+# /propose-scenario — Đề xuất một BDD Scenario mới (cho Tester & QC)
+
+Dành cho **tester và QC** phát hiện edge case chưa được BDD hiện tại phủ (vd một gap missing-coverage
+`DOC_GAPS` từ `/qc-analyze`). Draft một Gherkin scenario vào **khu proposal** để
+PO/Dev review và promote.
+
+**KHÔNG sửa file `.feature` canonical.** BDD do PO/Dev sở hữu — lệnh này chỉ ghi
+một proposal. Promote vào BDD thật là hành động của PO/Dev.
+
+Usage: `/propose-scenario {UC-ID} {mô tả edge case}`
+Ví dụ: `/propose-scenario FT-001 login với email có space ở cuối vẫn nên thành công`
+
+## Gate
+{{include:steps/gate.md}}
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID từ `$ARGUMENTS`. Phân giải file `.feature` của nó (để lấy vocabulary + scenario có sẵn) và PRD của nó.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Step 1 — Phân giải UC + Platform
+
+Định vị (qua `spec-manifest.yaml` nếu có, else `paths`):
+- `prd_path` + danh sách acceptance criteria của UC
+- `bdd_path` + `active_platform` (web / app / system) — để khớp vocabulary scenario và tag `@trace`
+- các tiêu đề scenario có sẵn của UC này (để tránh đề xuất trùng)
+
+## Step 2 — Quyết định Coverage (CRITICAL)
+
+Một BDD scenario phải trace tới một PRD acceptance criterion. Xác định case nào áp dụng:
+
+**Case A — behavior NẰM TRONG một AC có sẵn** (AC ngụ ý nó, BDD chỉ thiếu scenario):
+→ Đây là coverage gap. Tiếp tục draft scenario (Step 3), map tới AC đó.
+
+**Case B — behavior KHÔNG nằm trong AC nào** (requirement thực sự mới):
+→ **Đừng** draft BDD proposal (scenario sẽ không có gì để trace). Thay vào đó **ghi một
+file PRD change request** để PO thực sự thấy nó trên `/sync` (đừng chỉ in ra):
+
+Ghi vào `{paths.prd_change_requests_dir}/{UC-ID}-{slug}.md` (phân giải về
+`{spec_source}/feedback/prd-change-requests/` ở umbrella mode; tạo dir nếu cần):
+```
+# PRD Change Request — {UC-ID}: {short title}
+
+> ⚠️ Requirement mới phát hiện trong test — KHÔNG được PRD AC nào phủ (không phải coverage gap).
+| Field | Value |
+|---|---|
+| UC / Ticket | {UC-ID} |
+| PRD | {prd_path} (v{prd_version}) |
+| Source | {BUG-ID nếu có | quan sát của tester/QC} |
+| Requested by | tester/QC |
+| Status | Open |
+
+**Requested behavior:** {description}
+**Suggested AC (draft cho PO):** "{draft AC text}"
+**Route to PO:** thêm/mở rộng một AC trong {prd_path} → `/refine-prd` → chạy lại `/generate-bdd` → dev `/generate-code`.
+```
+Rồi sang Step 5 (handoff áp dụng cho file này luôn). Skip Step 3–4 (không có BDD scenario cho Case B).
+
+Nếu không chắc case nào → hiện danh sách AC và hỏi tester nó map tới AC nào, hoặc confirm nó là mới.
+
+## Step 3 — Draft Scenario (chỉ Case A)
+
+Viết Gherkin nhất quán với convention của `/generate-bdd` cho `active_platform`:
+- Dùng vocabulary platform (web: clicks/sees; app: taps/sees; system: business event)
+- Gồm tag `@trace`: `@trace.uc={UC-ID}`, `@trace.ac={AC-N}`, cùng `@proposed @from-test`
+- Một scenario tập trung; Given/When/Then cụ thể; không chi tiết implementation
+
+## Step 4 — Ghi Proposal
+
+Ghi vào `{paths.bdd_proposals_dir}/{UC-ID}-{slug}.md` (phân giải về `{spec_source}/feedback/bdd-proposals/` ở umbrella mode; tạo dir nếu cần).
+KHÔNG đụng `.feature` canonical. Doc proposal chứa draft + metadata review
+(xem Output), **gồm dòng `Status: proposed`**. Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
+
+> **Vòng đời proposal** (máy đọc được để `/generate-bdd` intake đúng):
+> `proposed` → PO/Dev duyệt đặt `accepted` (hoặc `rejected`) → `/generate-bdd` chèn cái `accepted` vào `.feature` rồi đặt `incorporated` + lưu trữ. **Chỉ `accepted` mới được đưa vào BDD.**
+
+## Step 5 — Handoff (để PO/Dev thực sự thấy)
+
+Một proposal chỉ tới PO/Dev nếu được **commit và push lên spec repo dùng chung**.
+
+```bash
+cd {spec_source}              # umbrella: spec submodule; single-service: bỏ
+git add feedback/bdd-proposals/{UC-ID}-{slug}.md
+git commit -m "qa(proposal): {UC-ID} — {title}"
+git push                      # → PO/Dev thấy nó ở lần /sync tiếp theo
+```
+
+- Không có quyền push spec repo → mở PR / MR thay vì. In fallback này.
+- Với **PRD change request** (Case B), commit file request thay vì:
+  ```bash
+  cd {spec_source}
+  git add feedback/prd-change-requests/{UC-ID}-{slug}.md
+  git commit -m "qa(prd-change): {UC-ID} — {title}"
+  git push
+  ```
+
+> PO/Dev được thông báo qua routine bình thường: `/sync` liệt kê các proposal vừa pull về.
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+📝 Scenario proposal → {paths.bdd_proposals_dir}/{UC-ID}-{slug}.md
+
+UC        : {UC-ID} ({active_platform})
+Maps to AC : {AC-N} — "{AC text}"
+Source     : {BUG-ID nếu có | quan sát tester}
+
+Scenario đề xuất (DRAFT — chờ PO/Dev review):
+  @proposed @from-test @trace.uc={UC-ID} @trace.ac={AC-N}
+  Scenario: {title}
+    Given {…}
+    When  {…}
+    Then  {…}
+
+Để PO/Dev promote:
+  [ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
+  [ ] Đặt `Status: accepted` trong file proposal (để /generate-bdd đưa vào)
+  [ ] Chạy lại /generate-bdd {UC-ID} — nó tự chèn proposal `accepted` vào .feature rồi lưu trữ
+  [ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
+
+Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}
+
+---
+Status : ✅ Complete (read-only trên BDD canonical — chỉ proposal)
+Output Artifacts: created {paths.bdd_proposals_dir}/{UC-ID}-{slug}.md (pushed to shared spec repo)
+Next   : PO/Dev thấy nó ở lần /sync tiếp theo → review & promote
+```