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