@educa-corp/sdd-framework 0.1.0

package/commands/report-bug.tmpl

@@ -0,0 +1,148 @@
+# /report-bug — File một Bug có trace-spec (cho Tester & QC)
+
+Dành cho **tester và QC** — gồm cả **product-gap** lòi ra từ pipeline `/qc-*`
+(`/qc-run-test` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAPS` từ
+`/qc-analyze`). Sinh một bug report có cấu trúc với đầy đủ spec context, phân loại layer
+khả nghi, và lưu lại để handoff cho team dev.
+
+**READ-ONLY trên spec và code.** Lệnh này không bao giờ sửa PRD, BDD, tech-docs, hay source.
+Fix là việc của dev (`/fix-bug`); viết scenario là `/propose-scenario`.
+
+Usage: `/report-bug {UC-ID hoặc TICKET} {mô tả ngắn}`
+Ví dụ: `/report-bug FT-001 tài khoản khoá sau 6 lần login fail, spec nói 5`
+
+## Gate
+{{include:steps/gate.md}}
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID / TICKET từ `$ARGUMENTS`. Phân giải file `.feature` khớp nếu có; nếu không, tiếp tục — bug vẫn file được.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Step 1 — Phân giải Spec Context
+
+Định vị chuỗi spec cho UC/TICKET của bug. Ưu tiên `spec-manifest.yaml` (setup umbrella/tester) nếu có; else dùng `paths` đã phân giải.
+
+Thu thập và lưu:
+- `prd_path` + `Version` hiện tại của PRD
+- `bdd_path` (file `.feature` của UC này) + tiêu đề **scenario fail** cụ thể, nếu có cái khớp
+- `tech_doc_path` (nếu có)
+- `service` / domain
+
+Nếu không có scenario `.feature` nào khớp behavior báo cáo → set `coverage_gap = true` (behavior chưa được BDD test).
+
+## Step 2 — Thu thập chi tiết Bug
+
+Nếu chưa có trong `$ARGUMENTS`, hỏi tester (một prompt gọn):
+
+```
+File một bug — trả lời những gì bạn biết:
+  1. Xảy ra ở đâu? (endpoint / screen / flow)
+  2. Các bước tái hiện?
+  3. Expected (theo spec) vs Actual?
+  4. Error / log / status code?
+  5. Environment? (staging / prod / local)
+```
+
+## Step 3 — Xác định AC bị vi phạm
+
+Đọc PRD acceptance criteria cho UC này. Khớp bug với **AC** cụ thể nó vi phạm
+(vd `AC3: "5 lần login fail → khoá 30m"`). Trích nguyên văn. Nếu behavior không map AC nào →
+ghi "No AC covers this" và coi như một PRD gap khả dĩ.
+
+## Step 4 — Phân loại Layer khả nghi (BUG_FLOW)
+
+Áp dụng bảng quyết định BUG_FLOW để gợi ý root cause khả năng ở đâu — cái này route bug:
+
+| Nếu… | Layer khả nghi | Route tới |
+|------|-------------|----------|
+| Code mâu thuẫn một BDD scenario | **Code bug** (Case 1) | Dev → `/fix-bug` |
+| BDD scenario mâu thuẫn PRD AC | **BDD bug** (Case 2) | Dev/PO fix BDD |
+| PRD AC mơ hồ / im lặng | **PRD ambiguity** (Case 3) | PO làm rõ PRD |
+| Behavior đúng nhưng **không scenario nào phủ** | **BDD coverage gap** | Tester → `/propose-scenario` |
+| UI ≠ Design Spec | **Design Spec bug** (Case 5) | Dev/Designer |
+| Chỉ Env / data | **Environment** (Case 6) | DevOps |
+
+Nêu phân loại như một gợi ý (dev confirm trong `/fix-bug`).
+
+## Step 5 — Ghi Report
+
+Gán `BUG-{today YYYYMMDD}-{NN}` (NN = sequence kế tiếp trong các report có sẵn).
+Ghi vào `{paths.bug_reports_dir}/{BUG-ID}.md` (phân giải về `{spec_source}/feedback/bug-reports/` ở umbrella mode; tạo dir nếu cần) theo cấu trúc trong Output block, và cũng in nó ra để dán vào Jira/Slack.
+
+## Step 5.5 — Backfill trace (link pending-view)
+
+Nếu Step 1 khớp một scenario fail cụ thể `{UC-ID}-SC{N}`, xác định **sổ platform** cần cập nhật (trace tách theo platform: `{UC-ID}-{platform}.tsv`):
+- `{platform}` = platform mà bug xảy ra (từ ngữ cảnh test/feature fail — `web`/`app`/`system`). Nếu biết → dùng thẳng.
+- Nếu **không rõ platform**: glob `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-*.tsv` tìm sổ nào có `sc_id` = `{UC-ID}-SC{N}`. Khớp đúng **một** sổ → dùng nó. Khớp **nhiều** sổ (cùng số SC ở nhiều platform, là 2 scenario khác nhau) → **hỏi tester bug thuộc platform nào** rồi mới ghi.
+
+Nếu tìm được đúng row trong sổ `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv`, cập nhật **chỉ** row đó để view "waiting-on" của PO/PM trỏ
+tới bug này — giữ nguyên mọi cột khác (gồm `qc_status`):
+- `qc_blocked_by` = `{BUG-ID}`
+- `qc_owner` = `dev` nếu layer khả nghi ∈ {Code, BDD, Design Spec, Env} · `po` nếu layer khả nghi = PRD ambiguity
+
+Skip âm thầm nếu không SC nào khớp hoặc không có file/row trace (bug vẫn file được). Đây là
+lần ghi duy nhất lệnh này làm tới operational state — nó vẫn **không bao giờ** sửa PRD/BDD/code.
+
+## Step 6 — Handoff (để PO/Dev thực sự thấy)
+
+Report chỉ tới PO/Dev nếu được **commit và push lên spec repo dùng chung**. File local là dead drop.
+
+Xác định repo sở hữu `{paths.bug_reports_dir}`:
+- Umbrella mode → spec submodule tại `{spec_source}`
+- Single-service → repo hiện tại
+
+Rồi commit + push **repo đó**:
+
+```bash
+cd {spec_source}              # umbrella: spec submodule; single-service: bỏ
+git add feedback/bug-reports/{BUG-ID}.md
+git commit -m "qa(bug): {BUG-ID} — {short description}"
+git push                      # → PO/Dev thấy nó ở lần /sync tiếp theo
+```
+
+- Nếu tester không có quyền push spec repo → mở PR / MR thay vì, hoặc đưa file cho người sở hữu. In fallback này.
+- In chính xác các lệnh nếu bạn không tự chạy chúng.
+
+> PO/Dev được thông báo qua routine bình thường: `/sync` liệt kê các bug report vừa pull về.
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (trong spec repo dùng chung)
+
+Feature  : {UC-ID} — {feature name}   |  Service: {service}   |  Severity: {Critical|Major|Minor}
+State    : 🟢 Open   (lifecycle: Open → Fixed → Closed — set `Fixed` bởi /fix-bug, `Closed` sau khi /qc-run-test re-verify pass)
+
+Spec context
+  PRD      : {prd_path} (v{prd_version})
+  BDD      : {bdd_path} → Scenario: "{scenario title}"   {hoặc: ⚠️ no scenario covers this}
+  Tech Doc : {tech_doc_path}
+
+AC bị vi phạm
+  {AC-N}: "{AC text}"
+
+Expected (theo spec) : {expected}
+Actual               : {actual}
+Steps to reproduce   : {1..N}
+Environment          : {env}
+
+Layer khả nghi : {Code | BDD | PRD | Design Spec | Env}  →  {route}
+
+Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}
+
+---
+Status : ✅ Complete (read-only trên specs/code — chỉ ghi file feedback)
+Output Artifacts: created {paths.bug_reports_dir}/{BUG-ID}.md (pushed to shared spec repo)
+Next   :
+  - PO/Dev sẽ thấy nó ở lần /sync tiếp theo
+  - Code bug      → dev chạy /fix-bug {BUG-ID}
+  - PRD ambiguity → PO (BUG_FLOW Case 3)
+  - Coverage gap  → /propose-scenario {UC-ID}
+```