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

package/commands/report-bug.tmpl

@@ -1,109 +1,109 @@
-# /report-bug — File a Spec-Traced Bug (Tester & QC-Facing)
+# /report-bug — File một Bug có trace-spec (cho Tester & QC)
 
-For **testers and QC** — including **product-gaps** surfaced by the `/qc-*` pipeline
-(`/qc-run-test` FAIL classified product-gap, or a `DOC_GAPS` spec-defect blocker from
-`/qc-analyze`). Produces a structured bug report with full spec context, classifies the likely
-layer, and saves it for handoff to the dev team.
+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 on specs and code.** This command never edits PRD, BDD, tech-docs, or source.
-Fixing is the dev's job (`/fix-bug`); writing scenarios is `/propose-scenario`.
+**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 or TICKET} {short description}`
-Example: `/report-bug FT-001 account locks after 6 failed logins, spec says 5`
+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}}
 
-*Note: For this command, the target in Step 1 is a UC-ID / TICKET from `$ARGUMENTS`. Resolve the matching `.feature` file if one exists; if not, continue — a bug can still be filed.*
+*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 — Resolve Spec Context
+## Step 1 — Phân giải Spec Context
 
-Locate the spec chain for the bug's UC/TICKET. Prefer `spec-manifest.yaml` (umbrella/tester setup) if present; else use resolved `paths`.
+Đị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.
 
-Gather and store:
-- `prd_path` + current PRD `Version`
-- `bdd_path` (the `.feature` for this UC) + the specific **failing scenario** title, if one matches
-- `tech_doc_path` (if any)
+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
 
-If no `.feature` scenario matches the reported behavior → set `coverage_gap = true` (the behavior is untested by BDD).
+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 — Gather Bug Details
+## Step 2 — Thu thập chi tiết Bug
 
-If not already in `$ARGUMENTS`, ask the tester (one compact prompt):
+Nếu chưa có trong `$ARGUMENTS`, hỏi tester (một prompt gọn):
 
 ```
-File a bug — answer what you can:
-  1. Where does it occur? (endpoint / screen / flow)
-  2. Steps to reproduce?
-  3. Expected (per spec) vs Actual?
+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 — Identify the AC Violated
+## Step 3 — Xác định AC bị vi phạm
 
-Read the PRD acceptance criteria for this UC. Match the bug to the specific **AC** it violates
-(e.g. `AC3: "5 failed logins → lock 30m"`). Quote it verbatim. If the behavior maps to no AC →
-note "No AC covers this" and treat as a possible PRD gap.
+Đọ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 — Classify Likely Layer (BUG_FLOW)
+## Step 4 — Phân loại Layer khả nghi (BUG_FLOW)
 
-Apply the BUG_FLOW decision table to suggest where the root cause likely is — this routes the bug:
+Áp dụng bảng quyết định BUG_FLOW để gợi ý root cause khả năng ở đâu — cái này route bug:
 
-| If… | Likely layer | Route to |
+| Nếu… | Layer khả nghi | Route tới |
 |------|-------------|----------|
-| Code contradicts a BDD scenario | **Code bug** (Case 1) | Dev → `/fix-bug` |
-| BDD scenario contradicts PRD AC | **BDD bug** (Case 2) | Dev/PO fix BDD |
-| PRD AC is ambiguous / silent | **PRD ambiguity** (Case 3) | PO clarifies PRD |
-| Behavior correct but **no scenario covers it** | **BDD coverage gap** | Tester → `/propose-scenario` |
+| 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 |
-| Env / data only | **Environment** (Case 6) | DevOps |
+| Chỉ Env / data | **Environment** (Case 6) | DevOps |
 
-State the classification as a suggestion (dev confirms during `/fix-bug`).
+Nêu phân loại như một gợi ý (dev confirm trong `/fix-bug`).
 
-## Step 5 — Write the Report
+## Step 5 — Ghi Report
 
-Assign `BUG-{today YYYYMMDD}-{NN}` (NN = next sequence among existing reports).
-Write to `{paths.bug_reports_dir}/{BUG-ID}.md` (resolved to `{spec_source}/feedback/bug-reports/` in umbrella mode; create dir if needed) using the structure in the Output block, and also print it for pasting into Jira/Slack.
+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 the trace (pending-view link)
+## Step 5.5 — Backfill trace (link pending-view)
 
-If Step 1 matched a specific failing scenario `{UC-ID}-SC{N}` **and** a trace row exists in
-`{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`, update **only** that row so the PO/PM "waiting-on" view points
-to this bug — leave every other column (incl. `qc_status`) unchanged:
+Nếu Step 1 khớp một scenario fail cụ thể `{UC-ID}-SC{N}` **và** một trace row tồn tại trong
+`{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.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` if likely layer ∈ {Code, BDD, Design Spec, Env} · `po` if likely layer = PRD ambiguity
+- `qc_owner` = `dev` nếu layer khả nghi ∈ {Code, BDD, Design Spec, Env} · `po` nếu layer khả nghi = PRD ambiguity
 
-Skip silently if no SC matched or no trace file/row exists (a bug can still be filed). This is
-the only write this command makes to operational state — it still **never** edits PRD/BDD/code.
+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 (so PO/Dev actually see it)
+## Step 6 — Handoff (để PO/Dev thực sự thấy)
 
-The report only reaches PO/Dev if it is **committed and pushed to the shared spec repo**. A local file is a dead drop.
+Report chỉ tới PO/Dev nếu được **commit và push lên spec repo dùng chung**. File local là dead drop.
 
-Determine the repo that owns `{paths.bug_reports_dir}`:
-- Umbrella mode → the spec submodule at `{spec_source}`
-- Single-service → the current repo
+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
 
-Then commit + push **that** repo:
+Rồi commit + push **repo đó**:
 
 ```bash
-cd {spec_source}              # umbrella: the spec submodule; single-service: omit
+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 see it on their next /sync
+git push                      # → PO/Dev thấy nó ở lần /sync tiếp theo
 ```
 
-- If the tester lacks push rights to the spec repo → open a PR / MR instead, or hand the file to whoever owns it. Print this fallback.
-- Print the exact commands if you do not run them automatically.
+- 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 are notified through their normal routine: `/sync` lists newly-pulled bug reports.
+> 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ề.
 
 ---
 
@@ -112,34 +112,34 @@ git push                      # → PO/Dev see it on their next /sync
 {{include:steps/report-footer.md}}
 
 ```
-🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (in shared spec repo)
+🐞 {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` by /fix-bug, `Closed` after /qc-run-test re-verify pass)
+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}"   {or: ⚠️ no scenario covers this}
+  BDD      : {bdd_path} → Scenario: "{scenario title}"   {hoặc: ⚠️ no scenario covers this}
   Tech Doc : {tech_doc_path}
 
-AC violated
+AC bị vi phạm
   {AC-N}: "{AC text}"
 
-Expected (per spec) : {expected}
-Actual              : {actual}
-Steps to reproduce  : {1..N}
-Environment         : {env}
+Expected (theo spec) : {expected}
+Actual               : {actual}
+Steps to reproduce   : {1..N}
+Environment          : {env}
 
-Likely layer : {Code | BDD | PRD | Design Spec | Env}  →  {route}
+Layer khả nghi : {Code | BDD | PRD | Design Spec | Env}  →  {route}
 
-Handoff : {✅ committed + pushed to spec repo | ⚠️ run the 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 specs/code — only wrote the feedback file)
+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 will see this on their next /sync
-  - Code bug      → dev runs /fix-bug {BUG-ID}
+  - 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}
 ```