@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.1

package/commands/propose-scenario.tmpl

@@ -1,91 +1,91 @@
-# /propose-scenario — Propose a New BDD Scenario (Tester & QC-Facing)
+# /propose-scenario — Đề xuất một BDD Scenario mới (cho Tester & QC)
 
-For **testers and QC** who discover an edge case not covered by existing BDD (e.g. a `DOC_GAPS`
-missing-coverage gap from `/qc-analyze`). Drafts a Gherkin scenario into a **proposals area** for
-PO/Dev to review and promote.
+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.
 
-**Does NOT edit the canonical `.feature` file.** BDD is owned by PO/Dev — this command only writes
-a proposal. Promotion into the real BDD is a PO/Dev action.
+**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} {edge case description}`
-Example: `/propose-scenario FT-001 login with email that has trailing spaces should still succeed`
+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}}
 
-*Note: For this command, the target in Step 1 is a UC-ID from `$ARGUMENTS`. Resolve its `.feature` file (for vocabulary + existing scenarios) and its PRD.*
+*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 — Resolve UC + Platform
+## Step 1 — Phân giải UC + Platform
 
-Locate (via `spec-manifest.yaml` if present, else `paths`):
-- `prd_path` + the UC's acceptance criteria list
-- `bdd_path` + `active_platform` (web / app / system) — to match scenario vocabulary and `@trace` tags
-- existing scenario titles for this UC (to avoid proposing a duplicate)
+Đị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 — Coverage Decision (CRITICAL)
+## Step 2 — Quyết định Coverage (CRITICAL)
 
-A BDD scenario must trace to a PRD acceptance criterion. Determine which case applies:
+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 IS within an existing AC** (the AC implies it, BDD just lacks a scenario):
-→ This is a coverage gap. Proceed to draft the scenario (Step 3), mapped to that AC.
+**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 is NOT in any AC** (genuinely new requirement):
-→ Do **not** draft a BDD proposal (a scenario would have nothing to trace to). Instead **write a
-PRD change request file** so the PO actually sees it on `/sync` (do not just print it):
+**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):
 
-Write to `{paths.prd_change_requests_dir}/{UC-ID}-{slug}.md` (resolved to
-`{spec_source}/feedback/prd-change-requests/` in umbrella mode; create dir if needed):
+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}
 
-> ⚠️ New requirement found in test — NOT covered by any PRD AC (not a coverage gap).
+> ⚠️ 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 if any | tester/QC observation} |
+| 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 for PO):** "{draft AC text}"
-**Route to PO:** add/extend an AC in {prd_path} → `/refine-prd` → re-run `/generate-bdd` → dev `/generate-code`.
+**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`.
 ```
-Then go to Step 5 (handoff applies to this file too). Skip Step 3–4 (no BDD scenario for Case B).
+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).
 
-If unsure which case → show the AC list and ask the tester which AC this maps to, or confirm it's new.
+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 the Scenario (Case A only)
+## Step 3 — Draft Scenario (chỉ Case A)
 
-Write Gherkin consistent with `/generate-bdd` conventions for `active_platform`:
-- Use the platform vocabulary (web: clicks/sees; app: taps/sees; system: business events)
-- Include `@trace` tags: `@trace.uc={UC-ID}`, `@trace.ac={AC-N}`, plus `@proposed @from-test`
-- One focused scenario; concrete Given/When/Then; no implementation detail
+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 — Write the Proposal
+## Step 4 — Ghi Proposal
 
-Write to `{paths.bdd_proposals_dir}/{UC-ID}-{slug}.md` (resolved to `{spec_source}/feedback/bdd-proposals/` in umbrella mode; create dir if needed).
-Do NOT touch the canonical `.feature`. The proposal doc contains the draft + review metadata
-(see Output). If the source was a bug, reference its `BUG-ID`.
+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). Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
 
-## Step 5 — Handoff (so PO/Dev actually see it)
+## Step 5 — Handoff (để PO/Dev thực sự thấy)
 
-A proposal only reaches PO/Dev if it is **committed and pushed to the shared spec repo**.
+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: the spec submodule; single-service: omit
+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 see it on their next /sync
+git push                      # → PO/Dev thấy nó ở lần /sync tiếp theo
 ```
 
-- No push rights to the spec repo → open a PR / MR instead. Print this fallback.
-- For a **PRD change request** (Case B), commit the request file instead:
+- 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
@@ -93,7 +93,7 @@ git push                      # → PO/Dev see it on their next /sync
   git push
   ```
 
-> PO/Dev are notified through their normal routine: `/sync` lists newly-pulled proposals.
+> PO/Dev được thông báo qua routine bình thường: `/sync` liệt kê các proposal vừa pull về.
 
 ---
 
@@ -106,24 +106,24 @@ git push                      # → PO/Dev see it on their next /sync
 
 UC        : {UC-ID} ({active_platform})
 Maps to AC : {AC-N} — "{AC text}"
-Source     : {BUG-ID if any | tester observation}
+Source     : {BUG-ID nếu có | quan sát tester}
 
-Proposed scenario (DRAFT — pending PO/Dev review):
+Scenario đề xuất (DRAFT — chờ PO/Dev review):
   @proposed @from-test @trace.uc={UC-ID} @trace.ac={AC-N}
   Scenario: {title}
     Given {…}
     When  {…}
     Then  {…}
 
-For PO/Dev to promote:
-  [ ] AC mapping correct? (or update PRD if requirement is actually new)
-  [ ] Add scenario to {bdd_path} (edit, or re-run /generate-bdd if PRD changed)
-  [ ] Then: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
+Để PO/Dev promote:
+  [ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
+  [ ] Thêm scenario vào {bdd_path} (sửa, hoặc chạy lại /generate-bdd nếu PRD đổi)
+  [ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
 
-Handoff : {✅ committed + pushed to spec repo | ⚠️ run git commands above / open a PR}
+Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}
 
 ---
-Status : ✅ Complete (read-only on canonical BDD — proposal only)
+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 see it on their next /sync → review & promote
+Next   : PO/Dev thấy nó ở lần /sync tiếp theo → review & promote
 ```