@anhth2/spec-driven-dev-plugin 0.10.0 → 0.11.0

package/docs/02-guides/product-owner/prd-writing-rules.md

@@ -0,0 +1,45 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Product Owner](README.md) › Quy tắc viết PRD
+
+# Quy Tắc Viết PRD Hiệu Quả
+
+## PRD là platform-agnostic
+
+| ✅ Viết trong PRD | ❌ Không viết trong PRD |
+|---|---|
+| "Đăng nhập thành công → truy cập tính năng" | "Click button Login → hiển thị spinner" |
+| "Sai password 5 lần → khoá 30 phút" | "API POST /auth/login trả về JWT" |
+| "Session hết hạn → yêu cầu xác thực lại" | "Toast message màu đỏ ở góc phải" |
+| "User có thể reset password qua email" | "Gọi sendgrid API để gửi email" |
+
+UI details và API specs thuộc về:
+- **Design Spec** → UI/UX cho FE/App
+- **Tech Docs** → API contract, technical design (dev team tự generate). BE tech-design (API contract) nằm trong shared spec module khi `spec_source` được set.
+
+## UC và AC phải testable
+
+Mỗi AC phải trả lời được câu hỏi: **"Làm sao biết tính năng này hoạt động đúng?"**
+
+❌ Không testable: `AC: "Hệ thống xử lý nhanh"` · `AC: "UI thân thiện với người dùng"`
+
+✅ Testable: `AC: "Trang login load trong vòng 3 giây"` · `AC: "Error message hiển thị trong vòng 1 giây sau khi submit"`
+
+## BR phải có ID liên tục
+
+```
+UC1 → BR1, BR2, BR3
+UC2 → BR4, BR5          ← tiếp tục từ BR3, không reset về BR1
+UC3 → BR6
+```
+
+## Luôn có negative path
+
+Với mỗi AC happy path, cần có ít nhất 1 AC cho error case:
+```
+AC1 (happy): Đăng nhập thành công với email + password hợp lệ
+AC2 (error): Đăng nhập thất bại khi password sai → hiển thị lỗi
+AC3 (error): Tài khoản bị khoá → hiển thị thông báo + thời gian còn lại
+```
+
+---
+
+← [Tình huống thực tế](scenarios.md) · Tiếp theo: [Checklist handoff](handoff-checklist.md)

package/docs/02-guides/product-owner/scenarios.md

@@ -0,0 +1,357 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Product Owner](README.md) › Tình huống thực tế
+
+# Tình Huống Thực Tế
+
+## Tình huống 1 — Bắt đầu tính năng mới từ đầu
+
+**Bối cảnh:** PO nhận yêu cầu tính năng mới, cần viết tài liệu để dev team implement.
+
+**Bước 1 — Capture ý tưởng:**
+```
+/define-product
+```
+Agent sẽ hỏi: Tên tính năng, domain · Mô tả ngắn · Vấn đề cần giải quyết · Actors liên quan · Kết quả mong muốn.
+
+Output: `specs/product-definition/FEAT-01-login.md`
+
+**Bước 2 — Generate PRD:**
+```
+/generate-prd specs/product-definition/FEAT-01-login.md
+```
+Agent tự động: đọc product definition · expand thành PRD đầy đủ với UC, AC, BR · nhắc nếu bạn viết UI details · kiểm tra terminology với business-dictionary.
+
+Output: `specs/prd/auth/FEAT-01-login-prd.md`
+
+**Bước 3 — Review nội dung:**
+```
+/refine-prd specs/prd/auth/FEAT-01-login-prd.md
+```
+Agent fan-out 4 lens (QA/DEV/SA/PO) chạy song song, rồi chạy completeness-critic loop cho đến khi một vòng không tìm ra finding mới, cuối cùng dedup + resolve conflict. Findings đầy đủ trong 1 lần chạy.
+
+Mở findings file, xem xét từng finding: `accepted` → apply · `modified` → viết note · `rejected` → bỏ qua.
+```
+/review-context --resume specs/prd/auth/FEAT-01-login-prd.md
+```
+
+**Bước 4 — Final check:**
+```
+/review-context specs/prd/auth/FEAT-01-login-prd.md
+```
+Kiểm tra: `@trace.status`, `@trace.domain`, completeness.
+
+**Bước 5 — Approve PRD:**
+```yaml
+# Trong file PRD, cập nhật:
+@trace.status: approved
+@trace.version: 1.0
+```
+
+**Bước 6 — Tạo Design Spec (FE/App):**
+```
+/generate-design-spec specs/prd/auth/FEAT-01-login-prd.md
+```
+Agent hỏi platform (web / app). PO phải cung cấp **Figma link node-level** (URL chứa `?node-id=`, lấy bằng right-click vào frame → "Copy link to selection") cho **mỗi screen**. Screen nào thiếu link → bị flag ❌ Missing, Status giữ `draft`, `/generate-bdd` bị BLOCKED cho đến khi đủ link.
+
+Sau khi Designer review + confirm đủ Figma node-id links → `@trace.status: approved`.
+
+**Bước 7 — Generate BDD:**
+```
+/generate-bdd specs/prd/auth/FEAT-01-login-prd.md
+```
+Agent hỏi: **"Platform? (1) web  (2) app  (3) system"**
+- Chọn `web` → `specs/bdd/auth/web/FEAT-01-UC1-login-web.feature`
+- Chạy lại, chọn `app` → `specs/bdd/auth/app/FEAT-01-UC1-login-app.feature`
+- Chạy lại, chọn `system` → Agent tổng hợp từ web+app BDDs → `specs/bdd/auth/system/FEAT-01-UC1-login-system.feature`
+
+> Nếu project chỉ có web → chỉ cần gen `web` rồi `system`.
+
+**Bước 8 — Push và thông báo:**
+```bash
+git add specs/prd/ specs/design-spec/ specs/bdd/
+git commit -m "feat(auth): add FEAT-01 PRD, design spec, and BDD"
+git push
+```
+**Thông báo dev team:** "FEAT-01 PRD + BDD đã sẵn sàng, domain: `auth`. BDD tại `specs/bdd/auth/`"
+
+---
+
+## Tình huống 2 — Viết PRD khi dev team chưa setup
+
+**Bối cảnh:** PO bắt đầu viết tài liệu, dev team chưa có umbrella repo. **Không cần đợi dev team.**
+
+```
+/define-product         → product definition
+/generate-prd           → PRD với @trace.domain: auth
+/review-context --fix   → auto-fix
+/generate-design-spec   → design spec cho FE (nếu có designer)
+/generate-bdd → web     → specs/bdd/auth/web/
+/generate-bdd → system  → specs/bdd/auth/system/ (tổng hợp từ web)
+```
+
+**Điều duy nhất cần làm:** thống nhất domain names với dev team trước.
+```bash
+# Khi /setup-ai-first hỏi "List your business domains":
+# → nhập: auth, payment, loyalty
+
+# Communicate với dev team:
+# "Domain names của project: auth, payment, loyalty
+#  Khi setup umbrella, dùng đúng tên này làm services keys"
+```
+
+---
+
+## Tình huống 3 — Tạo Design Spec và BDD sau khi PRD approved
+
+**Bối cảnh:** PRD đã được approve. Cần tạo Design Spec + BDD trước khi handoff.
+
+**Điều kiện:** Có Figma link **node-level** (URL chứa `?node-id=`, right-click frame → "Copy link to selection") cho từng screen.
+
+**Bước 1 — Design Spec:**
+```
+/generate-design-spec specs/prd/auth/FEAT-01-login-prd.md
+```
+Output: `specs/design-spec/auth/FEAT-01-design-spec-web.md`
+
+Mỗi screen cần Figma link node-id. Screen thiếu → flag ❌ Missing, BLOCKED. Sau khi Designer review → `@trace.status: approved`.
+
+**Bước 2 — Generate BDD:**
+```
+/generate-bdd specs/prd/auth/FEAT-01-login-prd.md
+```
+
+| Lần | Platform | Output |
+|---|---|---|
+| 1 | `web` | `specs/bdd/auth/web/FEAT-01-UC1-login-web.feature` |
+| 2 | `app` | `specs/bdd/auth/app/FEAT-01-UC1-login-app.feature` |
+| 3 | `system` | `specs/bdd/auth/system/FEAT-01-UC1-login-system.feature` |
+
+```bash
+git add specs/design-spec/ specs/bdd/
+git commit -m "feat(auth): add FEAT-01 design spec and BDD (web+app+system)"
+git push
+```
+
+---
+
+## Tình huống 4 — PRD bị review trả lại (NEEDS_REVISION)
+
+**Bước 1 — Đọc findings:**
+```bash
+cat .agent/review/FEAT-01-login-prd-review-context-findings.yaml
+```
+
+**Bước 2 — Xử lý từng finding:** set status `accepted` · `modified: "note của bạn"` · `rejected`.
+
+**Bước 3 — Apply:**
+```
+/review-context --resume specs/prd/auth/FEAT-01-login-prd.md
+```
+
+**Bước 4 — Re-review:**
+```
+/review-context specs/prd/auth/FEAT-01-login-prd.md
+```
+Lặp lại cho đến khi `recommendation: APPROVED`.
+
+---
+
+## Tình huống 5 — Requirements thay đổi sau khi PRD đã approved
+
+**Bước 1 — Đổi status về draft:**
+```yaml
+@trace.status: draft
+```
+
+**Bước 2 — Sửa nội dung:**
+```
+/refine-prd specs/prd/auth/FEAT-01-login-prd.md "Thêm yêu cầu: hỗ trợ đăng nhập bằng OTP"
+```
+
+**Bước 3 — Review lại:**
+```
+/review-context specs/prd/auth/FEAT-01-login-prd.md
+/review-context --resume    (nếu cần fix)
+```
+
+**Bước 4 — Approve và thông báo:**
+```yaml
+@trace.status: approved
+@trace.version: 1.1     # minor bump vì chỉ thêm AC
+                         # major bump (2.0) nếu thay đổi cơ bản
+```
+```bash
+git add specs/prd/auth/FEAT-01-login-prd.md
+git commit -m "feat(auth): update FEAT-01 PRD v1.1 — add OTP login AC"
+git push
+```
+
+**Bước 5 — Re-generate BDD cho các platform bị ảnh hưởng:**
+```
+/generate-bdd → web     (nếu thay đổi ảnh hưởng FE behavior)
+/generate-bdd → app     (nếu project có app)
+/generate-bdd → system
+→ BDD mới phản ánh AC đã thay đổi
+```
+```bash
+git add specs/bdd/
+git commit -m "feat(auth): update BDD for FEAT-01 v1.1 — OTP login scenarios"
+git push
+```
+> **Lưu ý:** Dev **KHÔNG tự generate BDD** — đây là trách nhiệm của PO. Nếu bỏ qua bước này, dev sẽ code theo BDD cũ và traces sẽ broken.
+
+**Thông báo dev team:** "FEAT-01 PRD + BDD updated v1.0 → v1.1, domain: `auth`. Pull spec submodule và bắt đầu với BDD mới."
+
+---
+
+## Tình huống 6 — Thêm domain mới vào project
+
+**Bước 1 — Cập nhật project-context.yaml:**
+```yaml
+domains:
+  - auth
+  - payment
+  - loyalty    # ← thêm vào đây
+```
+
+**Bước 2 — Thông báo dev team cập nhật umbrella config:**
+```yaml
+services:
+  loyalty:
+    path: "loyalty-service"
+    module: "java-spring"
+    specs_dir: "loyalty-service/specs/bdd"
+```
+
+**Bước 3 — Viết PRD bình thường với `@trace.domain: loyalty`.**
+
+> **Lưu ý:** Nếu dev team chưa cập nhật services config → `/review-context` P0 check sẽ cảnh báo domain không match.
+
+---
+
+## Tình huống 7 — Conflict giữa 2 PRDs (P3 check)
+
+**Bối cảnh:** FEAT-01 quy định "session hết hạn sau 30 phút", FEAT-05 quy định "session hết hạn sau 2 giờ".
+
+1. Đọc findings file — P3 liệt kê cả 2 PRD và điểm mâu thuẫn.
+2. Quyết định PRD nào đúng.
+3. Sửa file:
+   ```
+   /review-context --resume specs/prd/auth/FEAT-01-login-prd.md
+   # với finding P3: modified: "session timeout cập nhật thành 2 giờ theo FEAT-05"
+   ```
+4. Cả 2 PRD phải nhất quán trước khi dev team generate BDD.
+
+---
+
+## Tình huống 8 — Cập nhật Business Dictionary
+
+**Cách 1 — Thủ công:** Mở `specs/domain-knowledge/business-dictionary.md` → thêm vào Canonical Terms hoặc Banned Terms.
+
+**Cách 2 — Để agent phát hiện:** Khi chạy `/generate-prd` hoặc `/review-context`, agent sẽ hỏi nếu phát hiện term mới chưa có trong dictionary.
+
+**Sau khi cập nhật:**
+```bash
+git add specs/domain-knowledge/business-dictionary.md
+git commit -m "docs: add/update business dictionary — {term}"
+git push
+```
+
+> ⚠️ Sau khi ban một term mới, chạy `/review-context --fix` trên các PRDs hiện tại để replace banned terms tự động.
+
+---
+
+## Tình huống 9 — Quản lý nhiều PRD song song
+
+```
+specs/prd/
+├── auth/
+│   ├── FEAT-01-login-prd.md          (approved)
+│   └── FEAT-08-sso-prd.md            (draft)
+├── payment/
+│   ├── FEAT-03-checkout-prd.md       (approved)
+│   └── FEAT-11-refund-prd.md         (draft)
+└── loyalty/
+    └── FEAT-06-points-prd.md         (in-review)
+```
+
+**Gợi ý:** Hoàn thiện 1 PRD đến `approved` trước khi bắt đầu PRD tiếp theo. Chỉ PRD `approved` mới được dev team sử dụng.
+
+```bash
+# Xem nhanh tất cả PRDs và status:
+grep -r "@trace.status" specs/prd/ --include="*.md"
+```
+
+---
+
+## Tình huống 10 — Handoff PRD cho dev team
+
+**Checklist trước khi thông báo:**
+```yaml
+@trace.id: FEAT-01          ✅ có
+@trace.domain: auth         ✅ khớp với services keys của dev team
+@trace.status: approved     ✅ đã approved
+@trace.version: 1.0         ✅ có version number
+```
+
+```
+/review-context specs/prd/auth/FEAT-01-login-prd.md
+→ Phải thấy recommendation: APPROVED và 0 critical findings
+```
+
+**Template thông báo cho dev team:**
+```
+[FEAT-01] PRD Login đã approved — sẵn sàng implement
+
+Domain: auth
+File: my-project-specs/specs/prd/auth/FEAT-01-login-prd.md
+Version: 1.0
+Design Spec (Web): my-project-specs/specs/design-spec/auth/FEAT-01-design-spec-web.md
+
+Lệnh để bắt đầu:
+  git submodule update --remote my-project-specs
+  /review-context my-project-specs/specs/prd/auth/FEAT-01-login-prd.md
+```
+
+---
+
+## Tình huống 11 — Brownfield: API đã tồn tại trên hệ thống cũ
+
+**Bước 1 — Thêm `API Source: existing` vào PRD Metadata:**
+```markdown
+| **API Source** | existing |
+```
+
+**Bước 2 — Điền section "Existing API Contract" trong Appendix:**
+```markdown
+## Existing API Contract
+
+| Method | Path | Auth | Request | Response |
+|--------|------|------|---------|----------|
+| POST | /api/v1/orders | Bearer | `{ product_id, quantity }` | `{ id, status, total }` |
+| GET  | /api/v1/orders/:id | Bearer | — | `{ id, items[], status, created_at }` |
+
+**Error responses:**
+
+| HTTP Status | Error Code | Khi nào xảy ra |
+|-------------|------------|----------------|
+| 404 | ORDER_NOT_FOUND | Order ID không tồn tại |
+| 422 | INSUFFICIENT_STOCK | Số lượng vượt tồn kho |
+```
+
+**Bước 3 — Generate BDD như bình thường:**
+```
+/generate-bdd → system
+```
+Framework tự nhận ra `API Source: existing`, dùng contract trong PRD trực tiếp.
+
+**Bước 4 — Generate Tech Docs:**
+```
+/generate-tech-docs
+```
+Chạy ở mode **Reverse-document**: mô tả lại API đã tồn tại, ghi chú gaps.
+
+**Không cần:** Sign-off gate T7 (tự động skip) · `--phase=ui` (API đã live).
+
+---
+
+← [Commands](commands.md) · Tiếp theo: [Quy tắc viết PRD](prd-writing-rules.md)

package/docs/02-guides/qc-automation.md

@@ -0,0 +1,92 @@
+[📚 Docs](../README.md) › [Guides](README.md) › QC Automation
+
+# Hướng Dẫn QC Automation — Spec-Driven Dev
+
+Pipeline QC automation **chính thức** của framework — được port từ agent của team QC (reference repo `ai-automation-qc-base`) vào ngay trong framework. Nó sinh và chạy automation **Playwright/pytest** từ BDD `.feature` chính thức, rồi ghi tín hiệu **`qc_status`** (authoritative) vào trace TSV → Living Docs.
+
+## Mục Lục
+
+- [Hai luồng test: dev self-check vs QC chính thức](#hai-luồng-test-dev-self-check-vs-qc-chính-thức)
+- [Pipeline 6 bước](#pipeline-6-bước)
+- [Stack — module qc-playwright](#stack--module-qc-playwright)
+- [Trace join: qc_status đến Living Docs như thế nào](#trace-join-qc_status-đến-living-docs-như-thế-nào)
+- [Entry point](#entry-point)
+- [Skills theo layer](#skills-theo-layer)
+
+## Hai Luồng Test: Dev Self-Check vs QC Chính Thức
+
+Pipeline QC này **khác** với developer **self-check** (`/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test`):
+
+| Signal | Owner | Command | Ý nghĩa |
+|--------|-------|---------|---------|
+| `dev_selftest` | Dev | `/dev-run-test` | smoke check của riêng dev (KHÔNG authoritative) |
+| `qc_status` | QC | `/qc-run-test` | kết quả QC automation **chính thức** |
+
+Cả hai hiển thị **cạnh nhau** trong Living Docs; không cái nào ghi đè cái nào. `dev_selftest: pass` chỉ nghĩa "dev đã tự smoke qua"; coverage chính thức nằm ở `qc_status`.
+
+## Pipeline 6 Bước
+
+```
+/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
+ (requirement   (risk/plan   (test-case      (review     (gen+run     (report +
+  breakdown)     + Q-for-dev)  .Test.md)       gate)       Python →     evidence)
+                                                            qc_status)
+```
+
+| Command | Vai trò | Output |
+|---------|---------|--------|
+| `/qc-analyze` | bóc tách spec chính thức thành requirement + BR/AC + data-flow + `DOC_GAPS` | `{refinement_dir}/qc/{UC-ID}/` |
+| `/qc-plan` | risk / what-if / questions-for-dev + test plan | `TEST_PLAN.md` |
+| `/qc-design-test` | thiết kế test case (Markdown `.Test.md`), tag `@trace.verifies={UC-ID}-SC{N}` | `test-cases/` |
+| `/qc-review` | cổng review hai chiều: review test case (sau design) và script (sau run) | findings |
+| `/qc-run-test` | sinh + chạy Python pytest-playwright; **ghi `qc_status`** per scenario | `{trace_dir}/{UC-ID}.tsv` |
+| `/qc-report` | report pytest-html + Playwright trace + evidence | `reports/<feature>/report.html` |
+
+## Stack — Module qc-playwright
+
+`/qc-run-test` và `/qc-report` dùng stack module `qc-playwright`
+(`.agent/modules/qc-playwright/stack-profile.yaml`): **Python + pytest-playwright + Page
+Object** (slim `BasePage`, 3-layer), **Playwright Trace + pytest-html** (KHÔNG Allure). Stack
+này độc lập với module implementation của dev (java-spring, react, flutter, …).
+
+Per-layer guides chi tiết nằm trong `skills/qc/<stage>/` (port từ skills của agent QC):
+functional / integration / e2e / non-functional / exploratory.
+
+## Trace Join: qc_status Đến Living Docs Như Thế Nào
+
+1. `.feature` chính thức định nghĩa scenario là `@trace.scenario={UC-ID}-SC{N}`.
+2. `/qc-design-test` ghi SC mà test case thuộc về; `/qc-run-test` tag mỗi pytest test
+   `# @trace.verifies={UC-ID}-SC{N}`.
+3. `/qc-run-test` ghi `qc_status` (`pass|fail|skip|not_run`) + `qc_run_at` vào trace TSV của
+   service (authoritative), rồi refresh panel mirror local.
+4. `/validate-traces` (hoặc `/sync`) tổng hợp các TSV thành report Living Docs tại
+   `{spec_source}/.living-docs/` — dashboard hiển thị `qc_status` cạnh `dev_selftest`.
+
+## Entry Point
+
+Pipeline QC bắt đầu ngay khi BDD của một UC được approved (`/review-context (BDD)` APPROVED):
+
+```
+/qc-analyze {UC-ID}   →  … → /qc-report {UC-ID}  →  /validate-traces {UC-ID}
+```
+
+## Skills Theo Layer
+
+Các skill chi tiết theo từng giai đoạn QC nằm trong `skills/qc/`:
+
+| Stage skill | Vai trò |
+|---|---|
+| `qa-analyst` | phân tích requirement, sinh `DOC_GAPS` |
+| `qa-planner` | test plan, risk, questions-for-dev |
+| `qa-designer` | thiết kế test case `.Test.md` theo layer (functional / integration / e2e / non-functional / exploratory) |
+| `qa-reviewer` | cổng review test case và script |
+| `qa-runner` | sinh + chạy Python pytest-playwright, sinh report (Playwright Trace + pytest-html) |
+
+Mỗi skill **tự chứa** (self-contained) và có version frontmatter để theo dõi khi nâng cấp.
+
+## Xem Thêm
+
+- [Guide › Tester](tester/README.md) — vai trò tester, spec-manifest, `/report-bug`, `/propose-scenario`
+- [Concepts › Traceability](../03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
+- [Reference › Modules](../05-reference/modules.md) — chi tiết module `qc-playwright`
+- [Reference › Commands](../05-reference/commands.md) — danh mục đầy đủ mọi command

package/docs/02-guides/tester/README.md

@@ -0,0 +1,72 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › Tester / QA
+
+# Hướng Dẫn Tester — Spec-Driven Dev
+
+Tài liệu dành cho **QA / Tester** — cách kết nối với spec framework, workflow kiểm thử, và các tình huống thực tế.
+
+## Mục Lục
+
+| Trang | Nội dung |
+|---|---|
+| [Spec Manifest & Setup](spec-manifest.md) | Spec manifest là gì · setup tester agent · Living Docs panel |
+| [Workflow](workflow.md) | Luồng làm việc cơ bản từ nhận task đến pass/fail |
+| [Đọc Spec Chain](reading-specs.md) | Thứ tự đọc PRD → BDD → Tech Docs · ví dụ thực tế |
+| [Tình huống thực tế](scenarios.md) | 6 scenario: feature mới, PRD thay đổi, multi-service, regression, ... |
+| [Báo cáo bug](bug-reporting.md) | `/report-bug` · `/propose-scenario` · template báo cáo |
+| [Checklist test pass](test-checklist.md) | Checklist trước khi báo "test pass" |
+
+## Vai Trò Tester Trong Framework
+
+```
+PO/BA          Dev                    Tester
+──────────     ──────────────────     ──────────────────────────
+PRD            BDD (từ PRD)           /sync + /generate-spec-manifest
+               Tech Docs              Đọc PRD + BDD + Tech Docs
+               Code                   Viết test cases · Chạy test
+   ▲              ▲                    /report-bug      (bug → spec-traced)
+   │              │                    /propose-scenario (edge case → BDD draft)
+   └──────────────┴───── feedback/ trong spec repo ◄────┘
+        PO/Dev thấy qua /sync (📥) → fix / promote / update PRD
+```
+
+**Tester chịu trách nhiệm:**
+- Đọc PRD để hiểu business requirement trước khi test
+- Đọc BDD để biết chính xác scenarios cần cover
+- Đọc Tech Docs để hiểu API contracts và data flow
+- Viết test cases dựa trên BDD scenarios
+- Khi bug xảy ra: `/report-bug` → tạo bug report có spec-context đầy đủ, phân loại layer
+- Khi phát hiện edge case chưa có trong BDD: `/propose-scenario` → đề xuất cho PO/Dev duyệt
+
+**Tester KHÔNG làm:**
+- Sửa PRD / BDD / Tech Docs trực tiếp — đó là việc của PO và Dev
+- Approve PRD — chỉ PO
+- Generate code — chỉ Dev
+
+> **Lưu ý về `/propose-scenario`:** lệnh này **không** sửa BDD. Nó chỉ ghi một bản *đề xuất* (draft Gherkin) vào vùng `feedback/bdd-proposals/` của spec repo dùng chung. PO/Dev review và đưa vào `.feature` chính thức.
+
+## Commands Dành Cho Tester
+
+| Command | Mục đích | Khi nào dùng |
+|---|---|---|
+| `/generate-spec-manifest` | Tạo index TICKET-ID → PRD/BDD/tech-doc | Trước mỗi sprint, sau khi pull specs mới |
+| `/report-bug {UC-ID} {mô tả}` | Tạo bug report có spec-context + phân loại layer (read-only) | Khi test fail / phát hiện bug |
+| `/propose-scenario {UC-ID} {mô tả}` | Đề xuất scenario BDD mới cho edge case chưa cover | Khi tìm thấy case ngoài BDD hiện có |
+
+**QC Automation Pipeline (chính thức) — 6 lệnh `/qc-*`:**
+
+| Command | Mục đích | Khi nào dùng |
+|---|---|---|
+| `/qc-analyze` | Phân tích spec chain (PRD + BDD + Tech Docs), xác định scope test | Bước 1, sau khi BDD đã approved |
+| `/qc-plan` | Lập test plan: liệt kê scenarios, layer, ưu tiên | Bước 2 |
+| `/qc-design-test` | Thiết kế test case chi tiết (Page Object, data, assertions) | Bước 3 |
+| `/qc-review` | Review test design trước khi code automation | Bước 4 |
+| `/qc-run-test` | Chạy automation test → ghi `qc_status` per scenario vào trace TSV | Bước 5 |
+| `/qc-report` | Tổng hợp kết quả thành QC report | Bước 6 |
+
+Đây là **bộ test chính thức (authoritative) của QC**, chạy ngay trong framework. Pipeline dùng stack module `qc-playwright` (Python + pytest-playwright + Page Object). Xem chi tiết flow tại **[QC Automation guide](../qc-automation.md)**.
+
+> **Phân biệt với test commands của Dev:** `/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test` là **dev tự kiểm tra code của mình** — phát tín hiệu `dev_selftest`, KHÔNG phải bộ test chính thức. Bộ test authoritative của QC là pipeline `/qc-*` (sinh ra `qc_status`). Hai luồng tách biệt.
+
+---
+
+*Xem thêm:* [Developer Guide](../developer/README.md) · [QC Automation Guide](../qc-automation.md) · [Operations › Bug Flow](../../04-operations/bug-flow.md) · [Reference › Commands](../../05-reference/commands.md)

package/docs/02-guides/tester/bug-reporting.md

@@ -0,0 +1,117 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Báo cáo bug
+
+# Khi Tìm Thấy Bug — Quy Trình Trace
+
+Khi test fail, báo cáo phải có đủ **spec context** để Dev fix đúng chỗ.
+
+## Cách nhanh nhất: `/report-bug`
+
+```bash
+/report-bug FT-001 tài khoản khoá sau 6 lần sai, spec ghi 5
+```
+
+Lệnh tự động:
+- Resolve spec-context từ `spec-manifest.yaml`: PRD path + version, BDD scenario fail, tech-doc
+- Tìm **AC bị vi phạm** trong PRD
+- **Phân loại layer** theo BUG_FLOW (Code / BDD / PRD / Design Spec / Env) → route đúng người
+- Phát hiện **coverage gap** → gợi ý `/propose-scenario`
+- Ghi report vào **spec repo** (`{spec_source}/feedback/bug-reports/{BUG-ID}.md`) → **commit + push**
+
+Hoàn toàn **read-only** trên spec/code chính thức — chỉ ghi vào vùng `feedback/`.
+
+> **Làm sao PO/Dev biết?** Report được commit+push vào **spec repo dùng chung**. PO/Dev chạy `/sync` hàng ngày sẽ thấy dòng `📥 New tester feedback`. File nằm local một mình thì không ai biết — chính bước push + `/sync` mới khép vòng. (Không có quyền push → tạo PR/MR.)
+
+## Khi bug là "thiếu scenario" — `/propose-scenario`
+
+Nếu `/report-bug` báo *coverage gap* (behavior đúng nhưng chưa có scenario nào kiểm):
+
+```bash
+/propose-scenario FT-001 login với email có khoảng trắng ở cuối vẫn phải thành công
+```
+
+- Nếu behavior **đã nằm trong một AC của PRD** → lệnh draft Gherkin (tag `@proposed @from-test`), ghi vào `{spec_source}/feedback/bdd-proposals/` → commit + push. PO/Dev review rồi đưa vào `.feature`.
+- Nếu behavior **chưa có trong PRD** → lệnh dừng và xuất *PRD change request* cho PO.
+
+> Tester không tự ghi vào BDD — chỉ đề xuất. Giữ đúng ownership.
+
+## Template báo cáo bug
+
+*(Tham khảo — `/report-bug` tự sinh theo format này. Dùng khi báo cáo thủ công.)*
+
+```
+Bug ID   : BUG-{date}-{seq}
+Feature  : FT-{xxx} — {feature name}
+Service  : BE / Web / App
+Severity : Critical / Major / Minor
+
+Spec context:
+  PRD      : specs/prd/{domain}/{TICKET-ID}.md (v{x.x})
+  BDD      : {bdd path} → Scenario: "{scenario title}"
+  Tech Doc : {tech_docs path}
+
+AC bị vi phạm:
+  AC{N}: "{AC text từ PRD}"
+
+BDD Scenario bị fail:
+  "{Scenario title}"
+  Given: {given state}
+  When : {action}
+  Then : {expected theo spec}
+
+Actual behavior:
+  {what actually happened}
+
+Steps to reproduce:
+  1. {step}
+  2. {step}
+
+Environment: staging / production
+```
+
+## Ví dụ báo cáo thực tế
+
+```
+Bug ID   : BUG-20260605-003
+Feature  : FT-001 — User Login
+Service  : BE
+Severity : Major
+
+Spec context:
+  PRD      : specs/prd/auth/FT-001-login.md (v1.0)
+  BDD      : free-trial-be/specs/bdd/auth/FT-001-login.feature
+             → Scenario: "Lock account after 5 failed attempts"
+  Tech Doc : free-trial-specs/specs/tech-docs/auth/FT-001-auth-api.md
+
+AC bị vi phạm:
+  AC3: "Sai password 5 lần liên tiếp → khoá tài khoản 30 phút"
+
+BDD Scenario bị fail:
+  "Lock account after 5 failed attempts"
+  Given : user "alice@example.com" has 0 failed attempts
+  When  : login with wrong password 5 times
+  Then  : 5th attempt returns 423 Locked
+          AND retry_after = 1800
+
+Actual behavior:
+  5th attempt returns 401 Unauthorized (không phải 423)
+  Không có retry_after header
+  → Tài khoản không bị khoá, vẫn cho thử tiếp
+
+Steps to reproduce:
+  POST /api/v1/auth/login × 5 với password sai
+  → lần thứ 5 vẫn nhận 401
+
+Environment: staging (deploy 2026-06-05 09:00)
+```
+
+## Sau khi gửi bug report
+
+Dev sẽ xác định bug thuộc layer nào (code / BDD / PRD / env) và phản hồi với root cause + scenario cần re-test.
+
+> Xem flow phối hợp đầy đủ giữa Tester ↔ Dev ↔ PO trong **[Operations › Bug Flow](../../04-operations/bug-flow.md)**.
+
+> **Nếu AI lặp lại cùng kiểu lỗi qua nhiều feature:** ghi chú trong bug report. Dev chạy `/learn` để biến nó thành guardrail — AI sẽ không sinh lại lỗi đó ở các UC sau.
+
+---
+
+← [Tình huống thực tế](scenarios.md) · Tiếp theo: [Checklist test pass](test-checklist.md)