# /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
```