@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/docs/explain/17-qc-design-test.md

@@ -0,0 +1,61 @@
+[← /qc-plan](16-qc-plan.md) · [Explain Home](README.md) · [Next: /qc-review →](18-qc-review.md)
+
+# 17 · `/qc-design-test` — Trạm 3: Thiết kế test case (Markdown)
+
+> **Một câu.** Thiết kế **test case dạng Markdown** (`.Test.md`) từ plan — chưa sinh Python; script đến sau ở `/qc-run-test`.
+
+---
+
+## Vấn đề giải quyết
+
+Tách "thiết kế test case" (con người đọc/review được) khỏi "code test" (máy chạy). `.Test.md` là bản thiết kế mà `/qc-review` duyệt và `/qc-run-test` biến thành script.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 3), sau `/qc-plan`.
+
+---
+
+## Input / Output
+
+**Input:** TEST_PLAN.md + skill `qa-designer` (chọn layer, nạp MỘT file).
+
+**Output:** `{qc_dir}/{UC-ID}/{platform}/test-cases/*.Test.md` (trace mapping bắt buộc).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Role qa-designer** — chọn layer, nạp một file skill (không nạp cả bộ → tiết kiệm context).
+2. **Conventions** — theo quy ước test-case của QC team.
+3. **Trace mapping (bắt buộc)** — mỗi test case ↔ SC.
+4. **Output** `.Test.md`.
+
+---
+
+## Checkpoint & Gate
+
+- Không gate ở đây; gate là `/qc-review` kế tiếp.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Markdown-first** — test case là tài liệu review được trước khi thành code.
+- **Nạp MỘT file skill theo layer** — tối ưu context (chỉ layer cần).
+- **Trace mapping** — giữ test case gắn SC để về sau ghi `qc_status` đúng.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Tách design ↔ script** thêm một trạm nhưng cho phép review sớm — đánh đổi giữa số bước và chất lượng gate.
+- **Phụ thuộc convention QC team** — cần đồng bộ khi convention đổi.
+
+---
+
+## Kết nối
+
+**Trước:** [`/qc-plan`](16-qc-plan.md) · **Sau:** [`/qc-review`](18-qc-review.md) (review test case).

package/docs/explain/18-qc-review.md

@@ -0,0 +1,59 @@
+[← /qc-design-test](17-qc-design-test.md) · [Explain Home](README.md) · [Next: /qc-run-test →](19-qc-run-test.md)
+
+# 18 · `/qc-review` — Trạm 4: Cổng review hai chiều (test case & script)
+
+> **Một câu.** Gate chất lượng của QC: review **test case** (sau design-test) VÀ **script** (sau run-test) — chạy ở hai thời điểm trong dây chuyền.
+
+---
+
+## Vấn đề giải quyết
+
+Không chạy test kém. Trạm này chặn: (1) test case chưa đủ tốt trước khi biến thành script; (2) script chưa đúng trước khi coi kết quả là chính thức.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 4) — **hai lần**: sau `/qc-design-test` (review case) và sau `/qc-run-test` (review script).
+
+---
+
+## Input / Output
+
+**Input:** `.Test.md` (case) hoặc script Python (script) + skill `qa-reviewer`.
+
+**Output:** verdict APPROVED / NEEDS_FIX + findings review.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Role qa-reviewer** — nạp `{qc_skills_dir}/qa-reviewer/`.
+2. **Review focus** — kiểm test case (đủ phủ, đúng SC) hoặc script (đúng logic, selector, không fake-pass).
+3. Verdict: APPROVED → đi tiếp; NEEDS_FIX → sửa rồi review lại.
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 **Cổng hai chiều** — chặn `/qc-run-test` (nếu case chưa duyệt) và chặn tạo PR (nếu script chưa duyệt).
+
+---
+
+## Cơ chế đặc biệt
+
+- **Một lệnh, hai vai** — review case và review script dùng chung skill, khác focus.
+- **Gate thật của QC** — điểm HITL chính trong dây chuyền tự động.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chạy 2 lần cùng một lệnh** — người dùng phải nhớ gọi đúng thời điểm. Footer "Next" hướng dẫn, nhưng dễ nhầm. Cân nhắc tách rõ hoặc auto-detect giai đoạn.
+- **Verdict thủ công** — phụ thuộc reviewer; không có findings-file có mã như review-context. Đáng xem có nên chuẩn hoá.
+
+---
+
+## Kết nối
+
+**Trước:** [`/qc-design-test`](17-qc-design-test.md) (case) / [`/qc-run-test`](19-qc-run-test.md) (script) · **Sau:** case APPROVED → [`/qc-run-test`](19-qc-run-test.md); script APPROVED → [`/qc-report`](20-qc-report.md) / PR.

package/docs/explain/19-qc-run-test.md

@@ -0,0 +1,67 @@
+[← /qc-review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
+
+# 19 · `/qc-run-test` — Trạm 5: Sinh & chạy Playwright, ghi `qc_status`
+
+> **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
+
+---
+
+## Vấn đề giải quyết
+
+Đây là nơi QC trở thành **chính thức**: chạy test thật trên Playwright, phân loại FAIL (script-bug vs product-gap, **không fake-pass**), và đóng dấu `qc_status` — trạng thái QC authoritative.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 5), sau `/qc-review` (case APPROVED).
+- **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
+
+---
+
+## Input / Output
+
+**Input:** `.Test.md` đã review + skill `qa-runner` + selector (từ `/map-testids`).
+
+**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + Panel Mirror.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Role & stack** — qc-playwright (`stack-profile.yaml`): Python, pytest-playwright fixture, Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
+2. **Skills** — nạp một file skill `qa-runner` theo layer.
+3. **Sinh script** từ `.Test.md`; tag `@trace.verifies={UC-ID}-SC{N}`.
+4. **Chạy** — phân loại mỗi FAIL: **script-bug** (fix selector/logic) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
+5. **Write Trace State — `qc_status`** (kết quả QC chính thức).
+6. **Refresh Panel Mirror** — Living Docs local.
+
+---
+
+## Checkpoint & Gate
+
+- Tiền đề: case đã APPROVED ở `/qc-review`. Script sinh ra → review lại ở `/qc-review` (script) trước PR.
+
+---
+
+## Cơ chế đặc biệt
+
+- **`qc_status` là trục authoritative** — khác `dev_selftest`; có evidence.
+- **Không fake-pass** — product-gap giữ nguyên FAIL, đẩy về PO/Dev.
+- **Stack QC tách hẳn dev** — `@trace.verifies` nối script ↔ SC.
+- **`active_platform` khoá sổ trace** — `qc_status` ghi đúng `{UC-ID}-{platform}.tsv`.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Trạm nặng nhất của QC** — sinh + chạy + phân loại + ghi trace. Chạy thật phụ thuộc môi trường (browser, data, service lên).
+- **Phân loại script-bug vs product-gap phụ thuộc AI/reviewer** — sai loại → hoặc giấu lỗi sản phẩm hoặc báo nhầm. Đáng có tiêu chí rõ.
+- **Selector phụ thuộc `/map-testids`** — nếu chưa map, script giòn.
+- **Chạy lại tốn tài nguyên** — cân nhắc scoped run như dev-run-test.
+
+---
+
+## Kết nối
+
+**Trước:** [`/qc-review`](18-qc-review.md) (case) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review`](18-qc-review.md) (script).

package/docs/explain/20-qc-report.md

@@ -0,0 +1,61 @@
+[← /qc-run-test](19-qc-run-test.md) · [Explain Home](README.md) · [Next: /validate-traces →](21-validate-traces.md)
+
+# 20 · `/qc-report` — Trạm 6: Report + evidence + product-gap
+
+> **Một câu.** Trạm cuối QC: tổng hợp **report + evidence**, và đẩy **product-gap** (lỗi sản phẩm, không phải script) ngược về PO/Dev.
+
+---
+
+## Vấn đề giải quyết
+
+Kết quả chạy cần được trình bày có bằng chứng và **định tuyến đúng**: script-bug thì QC tự sửa, còn **product-gap** phải về tay PO/Dev. Trạm này đóng gói kết quả QC pass thành báo cáo.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 6, cuối), sau `/qc-run-test`.
+
+---
+
+## Input / Output
+
+**Input:** kết quả run + evidence + skill `qa-runner/report`.
+
+**Output:** QC report + evidence; product-gap đẩy về PO/Dev.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Role qa-runner/report** — nạp skill report.
+2. **Procedure** — tổng hợp kết quả run (pass/fail per SC), đính evidence.
+3. Tách **product-gap** → định tuyến về PO/Dev (có thể thành `/report-bug`).
+4. **Output** report.
+
+---
+
+## Checkpoint & Gate
+
+- Không gate chặn — báo cáo + định tuyến.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Product-gap routing** — khép vòng feedback: lỗi sản phẩm từ QC về đúng người quyết.
+- **Evidence-first** — báo cáo kèm bằng chứng (khác dev smoke).
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Product-gap → PO/Dev** nhưng cơ chế nối với `/report-bug` không tự động — dễ đứt. Đáng tích hợp để gap thành bug spec-anchored có hồ sơ.
+- **Report tách khỏi run** (trạm riêng) — linh hoạt nhưng thêm một lệnh phải nhớ gọi.
+- **Sau report → `/validate-traces`** để làm mới Living Docs (`qc_status`) — chuỗi này phụ thuộc người chạy đủ.
+
+---
+
+## Kết nối
+
+**Trước:** [`/qc-run-test`](19-qc-run-test.md) · **Sau:** [`/validate-traces`](21-validate-traces.md) (làm mới Living Docs); product-gap → [`/report-bug`](25-report-bug.md).

package/docs/explain/21-validate-traces.md

@@ -0,0 +1,68 @@
+[← /qc-report](20-qc-report.md) · [Explain Home](README.md) · [Next: /generate-spec-manifest →](22-generate-spec-manifest.md)
+
+# 21 · `/validate-traces` — Ma trận độ phủ spec ↔ code ↔ test
+
+> **Một câu.** Check **read-only** độ phủ giữa spec, code, test (gồm PRD version drift); phân loại mỗi SC và làm mới Living Docs. Không sửa gì.
+
+---
+
+## Vấn đề giải quyết
+
+Traceability chỉ có giá trị khi kiểm được. Command cho bức tranh toàn cục: SC nào có code, có test, hay còn hở — để không "tưởng xong mà chưa xong".
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Trace Audit (xuyên suốt).
+- **Đặc biệt:** read-only — an toàn chạy bất kỳ lúc nào.
+
+---
+
+## Input / Output
+
+**Input:** `.trace/…/{UC-ID}-{platform}.tsv` + spec + code + test.
+
+**Output:** ma trận coverage + `code_coverage`; làm mới Living Docs dashboard.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. Quét trace `.tsv` + đối chiếu spec/code/test.
+2. Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
+   | # | Trạng thái | Điều kiện |
+   |---|-----------|-----------|
+   | 1 | UNTRACKED | `gen_ver == —` |
+   | 2 | DRIFT | có code + `spec_ver != gen_ver` |
+   | 3 | GAP | có code + `test_count == —/0` |
+   | 4 | OK | version khớp + có code + có test |
+3. Dựng dashboard: `dev_selftest` (DEV smoke) **và** `qc_status` (QC chính thức) hiển thị cạnh nhau — **không merge**; cột `qc_owner` + `qc_blocked_by` ("Waiting on").
+
+---
+
+## Checkpoint & Gate
+
+- ⚪ Read-only, không gate.
+
+---
+
+## Cơ chế đặc biệt
+
+- **DRIFT xét trước GAP** — code lỗi thời chưa test phải hiện DRIFT (regen) không phải GAP.
+- **`dev_selftest` ≠ `qc_status`** — hai cột riêng, không trộn.
+- **"Waiting on" column** — `qc_owner`/`qc_blocked_by` trả lời "case nào chờ ai".
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chỉ báo cáo, không hành động** — hành động ở `/generate-code` (regen DRIFT) & QC (bù GAP). Chuỗi phụ thuộc người chạy tiếp.
+- **Nguồn sự thật của Living Docs** — chất lượng dashboard phụ thuộc `.tsv` được các lệnh code/test ghi đúng.
+- **Là "single pane" để PM/PO nhìn trạng thái** — ứng viên tốt cho UI viewer (blueprint có gợi ý).
+
+---
+
+## Kết nối
+
+**Trước:** bất kỳ (đặc biệt sau [`/qc-report`](20-qc-report.md)) · **Sau:** DRIFT/UNTRACKED → [`/generate-code`](09-generate-code.md); GAP → [`/dev-gen-test`](12-dev-gen-test.md); OK → PR.

package/docs/explain/22-generate-spec-manifest.md

@@ -0,0 +1,60 @@
+[← /validate-traces](21-validate-traces.md) · [Explain Home](README.md) · [Next: /fix-bug →](23-fix-bug.md)
+
+# 22 · `/generate-spec-manifest` — Mục lục spec cho agent ngoài
+
+> **Một câu.** Sinh một **manifest** (mục lục máy-đọc) của mọi spec trong dự án, để agent/công cụ bên ngoài định vị PRD/BDD/tech-docs mà không phải quét cả repo.
+
+---
+
+## Vấn đề giải quyết
+
+Agent ngoài (hoặc lệnh khác) cần biết "có những spec nào, ở đâu, trạng thái gì" mà không đọc toàn bộ. Manifest là index tự sinh, luôn cập nhật khi chạy lại.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** xuyên suốt (thường sau `/sync`).
+- **Đặc biệt:** file manifest **gitignored** (auto-generated, không commit).
+
+---
+
+## Input / Output
+
+**Input:** cây spec (`specs/{domain}/{prd-slug}/…`).
+
+**Output:** `spec-manifest.yaml` (auto-generated, DO NOT edit; regenerate bằng chính lệnh này).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. Quét `specs/` theo bố cục feature-package.
+2. Với mỗi feature: ghi domain, prd-slug, TICKET-ID, các artifact (PRD/BDD/tech-docs/design-spec), trạng thái.
+3. Ghi `spec-manifest.yaml` với header "Auto-generated — do not commit".
+
+---
+
+## Checkpoint & Gate
+
+- Không gate.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Máy-đọc, gitignored** — index tái sinh, không phải nguồn chân lý (spec mới là nguồn).
+- **Cho agent ngoài** — điểm tích hợp với công cụ/agent khác.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Phải chạy lại để cập nhật** — dễ stale nếu quên. `/sync` Step 6 làm mới cho umbrella; single-service phải nhớ chạy tay.
+- **Trùng vai với `/validate-traces`?** — validate-traces là trạng thái coverage; manifest là index vị trí. Khác mục đích nhưng cùng "bản đồ spec".
+
+---
+
+## Kết nối
+
+**Trước:** [`/sync`](28-sync.md) hoặc bất kỳ · **Sau:** agent ngoài dùng manifest để định vị spec.

package/docs/explain/23-fix-bug.md

@@ -0,0 +1,69 @@
+[← /generate-spec-manifest](22-generate-spec-manifest.md) · [Explain Home](README.md) · [Next: /debug →](24-debug.md)
+
+# 23 · `/fix-bug` — Workflow sửa bug đầy đủ
+
+> **Một câu.** Sửa bug **có kỷ luật**: truy root cause → fix (tag `@trace.fixes/root_cause/regression`) → regression test → build → commit (2 tầng ở umbrella) → đóng bug report → đề xuất lesson.
+
+---
+
+## Vấn đề giải quyết
+
+Sửa bug ad-hoc dễ tái phát và mất truy vết. Command áp một quy trình: hiểu gốc rễ, sửa có tag, thêm regression test để không lặp, và ghi lesson nếu là lỗi tái diễn.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** xuyên suốt (ngoài pipeline tuyến tính).
+- **Đặc biệt:** một trong số ít lệnh được sinh code **không cần `.feature` backing** (bug fix).
+
+---
+
+## Input / Output
+
+**Input:** bug report spec-anchored (`{BUG-ID}`) hoặc mô tả lỗi + code liên quan.
+
+**Output:** code fix (tag trace) + regression test + commit + bug report đóng.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Gate** — xác định service & code liên quan; tạo branch `fix/{TICKET}-{slug}`.
+2. **Phase 2 · Root Cause Analysis** — truy nguyên nhân gốc (không vá triệu chứng).
+3. **Phase 3 · Fix** — sửa; tag `@trace.fixes` / `@trace.root_cause` / `@trace.regression`.
+4. **Phase 4 · Regression Test** — thêm test tái hiện bug để chống tái phát.
+5. **Phase 5 · Build & Commit** — build verify; umbrella **push 2 tầng** (Tầng 1: fix branch trong service submodule nơi code sống; Tầng 2: umbrella pointer).
+6. **Phase 5.5 · Đóng bug report** — nếu fix một `{BUG-ID}` đã file → cập nhật trạng thái.
+7. **Phase 6 · Đề xuất Lesson** — nếu lỗi tái diễn → `capture-lesson` (L1–L5).
+
+---
+
+## Checkpoint & Gate
+
+- Commit **sau khi user duyệt**.
+- Build phải pass.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Root cause bắt buộc** trước fix — chống vá triệu chứng.
+- **Regression test bắt buộc** — mỗi bug fix để lại "bằng chứng chống tái phát".
+- **Push 2 tầng umbrella** — code ở submodule, pointer ở umbrella.
+- **Đóng bug report + đề xuất lesson** — khép vòng feedback.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Sinh code không cần `.feature`** — ngoại lệ có chủ đích cho bug, nhưng nghĩa là fix có thể lệch spec. Đáng cân nhắc có nên yêu cầu cập nhật BDD nếu fix đổi hành vi.
+- **Root cause phụ thuộc AI phân tích** — với bug phức tạp có thể cần `/debug` trước.
+- **Push 2 tầng** dễ sai thứ tự (submodule trước, pointer sau) — điểm nhạy cảm.
+- **Regression test có gắn `@trace.verifies` không?** — đáng đảm bảo để validate-traces thấy.
+
+---
+
+## Kết nối
+
+**Trước:** [`/report-bug`](25-report-bug.md) / [`/debug`](24-debug.md) / [`/dev-run-test`](13-dev-run-test.md) (fail) · **Sau:** tạo PR + link ticket; lỗi lặp → [`/learn`](27-learn.md).

package/docs/explain/24-debug.md

@@ -0,0 +1,61 @@
+[← /fix-bug](23-fix-bug.md) · [Explain Home](README.md) · [Next: /report-bug →](25-report-bug.md)
+
+# 24 · `/debug` — Phân tích debug nhanh (read-only)
+
+> **Một câu.** Phân tích lỗi (stack trace, error pattern, test failure) và đề xuất hướng sửa — **không sửa code**, chỉ chẩn đoán.
+
+---
+
+## Vấn đề giải quyết
+
+Trước khi sửa, cần hiểu lỗi. `/debug` phân tích nhanh nguyên nhân + vị trí + hướng fix, tách "hiểu lỗi" khỏi "sửa lỗi" (`/fix-bug`).
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** xuyên suốt.
+- **Đặc biệt:** **read-only** — không sửa, không commit.
+
+---
+
+## Input / Output
+
+**Input:** mô tả lỗi / stack trace / test failure + `platform_type` + project lessons.
+
+**Output:** báo cáo — Error · Root Cause · Location · Suggested Fix · Related Rule (`Output Artifacts: none (read-only)`).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Stack Trace Analysis** — đọc stack trace, định vị.
+2. **Common Error Patterns** — đối chiếu pattern lỗi quen thuộc theo platform.
+3. **Test Failure Analysis** — nếu là test fail, phân tích nguyên nhân.
+4. **Output** cấu trúc: Error / Root Cause / Location / Suggested Fix / Related Rule (trỏ rule/lesson liên quan).
+
+---
+
+## Checkpoint & Gate
+
+- Read-only, không gate.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Chẩn đoán theo platform** (`platform_type`) + đối chiếu **project lessons**.
+- **Related Rule** — nối lỗi với rule/lesson đã có → học từ lịch sử.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Read-only tách khỏi fix** — sạch về vai, nhưng người dùng phải chuyển sang `/fix-bug` thủ công. Có thể chuyển giao mượt hơn (truyền root cause sang fix-bug).
+- **Common Error Patterns** — độ hữu ích phụ thuộc pattern có bám stack thực tế của dự án không.
+
+---
+
+## Kết nối
+
+**Trước:** lỗi bất kỳ / [`/dev-run-test`](13-dev-run-test.md) (fail) · **Sau:** cần sửa → [`/fix-bug`](23-fix-bug.md).

package/docs/explain/25-report-bug.md

@@ -0,0 +1,65 @@
+[← /debug](24-debug.md) · [Explain Home](README.md) · [Next: /propose-scenario →](26-propose-scenario.md)
+
+# 25 · `/report-bug` — File bug có trace-spec (cho Tester & QC)
+
+> **Một câu.** Ghi một bug **gắn spec** (AC bị vi phạm, layer khả nghi), backfill trace, và handoff để PO/Dev thực sự thấy.
+
+---
+
+## Vấn đề giải quyết
+
+Bug không gắn spec khó truy vết & regression. Command ép bug được neo vào UC/SC/AC cụ thể, phân loại layer khả nghi, và nổi lên đúng người — làm input chất lượng cho `/fix-bug`.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** xuyên suốt (kênh feedback tester/QC), gồm cả product-gap từ `/qc-*`.
+
+---
+
+## Input / Output
+
+**Input:** mô tả bug + UC/platform + spec context.
+
+**Output:** `{bug_reports_dir}/{BUG-ID}.md` (spec-anchored) + backfill trace + handoff.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Step 1 · Phân giải Spec Context** — định vị UC/SC/PRD liên quan.
+2. **Step 2 · Thu thập chi tiết Bug** — hiện tượng, bước tái hiện, môi trường.
+3. **Step 3 · Xác định AC bị vi phạm** — bug này vi phạm AC nào (neo nghiệp vụ).
+4. **Step 4 · Phân loại Layer khả nghi (BUG_FLOW)** — đoán layer gây lỗi (FE/BE/data…).
+5. **Step 5 · Ghi Report** — file `{BUG-ID}.md`.
+6. **Step 5.5 · Backfill trace** — link pending-view (nối bug vào trace).
+7. **Step 6 · Handoff** — nổi lên để PO/Dev thấy (qua `/sync`).
+
+---
+
+## Checkpoint & Gate
+
+- Không gate — kênh có hồ sơ.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Spec-anchored** — bug neo AC/SC → `/fix-bug` có ngữ cảnh, regression đúng chỗ.
+- **BUG_FLOW layer classification** — hướng dev tới layer khả nghi.
+- **Backfill trace pending-view** — bug hiện trong dashboard trace.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Product-gap từ `/qc-report` → `/report-bug`** không tự động — nối tay. Đáng tích hợp để gap thành bug spec-anchored liền mạch.
+- **Handoff qua `/sync`** — nếu không chạy sync, feedback nằm im. Phụ thuộc nhịp vận hành.
+- **Phân loại layer là phỏng đoán** — có thể sai; `/debug`/`/fix-bug` xác nhận lại.
+
+---
+
+## Kết nối
+
+**Trước:** QC/test phát hiện lỗi · **Sau:** [`/fix-bug {BUG-ID}`](23-fix-bug.md); thiếu coverage → [`/propose-scenario`](26-propose-scenario.md); nổi lên qua [`/sync`](28-sync.md).

package/docs/explain/26-propose-scenario.md

@@ -0,0 +1,63 @@
+[← /report-bug](25-report-bug.md) · [Explain Home](README.md) · [Next: /learn →](27-learn.md)
+
+# 26 · `/propose-scenario` — Đề xuất BDD scenario mới (cho Tester & QC)
+
+> **Một câu.** Tester đề xuất một scenario còn thiếu; command quyết đây là **scenario mới** (draft) hay **thay đổi PRD** (change request), rồi ghi proposal để PO/Dev duyệt.
+
+---
+
+## Vấn đề giải quyết
+
+Tester thấy coverage thủng nhưng không được sửa spec trực tiếp. Command cho họ kênh **đề xuất có hồ sơ**: nếu là scenario mới trong scope → draft; nếu chạm yêu cầu nghiệp vụ → PRD change request.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** xuyên suốt (kênh feedback tester/QC).
+
+---
+
+## Input / Output
+
+**Input:** UC + platform + mô tả scenario thiếu.
+
+**Output:** `{bdd_proposals_dir}/…` (Case A: scenario draft) hoặc PRD change request (Case B).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Step 1 · Phân giải UC + Platform.**
+2. **Step 2 · Quyết định Coverage (CRITICAL)** — phân loại:
+   - **Case A** — scenario mới **trong scope** UC hiện tại → draft scenario.
+   - **Case B** — đòi hỏi **thay đổi yêu cầu nghiệp vụ** → **PRD Change Request** (không tự draft, đẩy về PO).
+3. **Step 3 · Draft Scenario** (chỉ Case A) — viết Gherkin đề xuất.
+4. **Step 4 · Ghi Proposal.**
+5. **Step 5 · Handoff** — để PO/Dev thấy; `/generate-bdd` có thể incorporate proposal `accepted`.
+
+---
+
+## Checkpoint & Gate
+
+- Không gate — đề xuất, PO/Dev quyết.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Phân biệt scenario-gap vs PRD-change** — giữ ranh giới ai được đổi gì (tester không tự đổi yêu cầu nghiệp vụ).
+- **Proposal `accepted` chảy ngược vào `/generate-bdd`** — khép vòng.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Quyết định Case A/B là điểm phán đoán** — sai hướng thì hoặc phình scope BDD hoặc bỏ sót đổi PRD. Tiêu chí rõ quan trọng.
+- **Nối với `/generate-bdd` incorporate** phụ thuộc trạng thái `accepted` được cập nhật — quy trình duyệt cần rõ.
+
+---
+
+## Kết nối
+
+**Trước:** tester thấy coverage thiếu · **Sau:** PO/Dev review proposal; Case A accepted → [`/generate-bdd`](06-generate-bdd.md); Case B → [`/refine-prd`](03-refine-prd.md)/PRD.