@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/commands/report-bug.tmpl

@@ -1,148 +0,0 @@
-# /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}
-```