---
version: 1.0
updated: 2026-06-11
ported_from: ai-automation-qc-base
---

# /qc-analyze — QC Requirement Analysis

> Stage 1 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-analyst của team QC. Markdown-first: không có script ở đây.

## Gate
{{include:steps/gate.md}}

*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID hoặc file feature/PRD. Đọc spec chính thức của UC đó — file `.feature` (mang `@trace.id={UC-ID}` và mỗi scenario `@trace.scenario={UC-ID}-SC{N}`), PRD, và design-spec — từ feature package `{paths.specs_dir}/{domain}/{prd-slug}/` (file `.feature` dưới `bdd/`, file PRD `{TICKET-ID}-{prd-slug}.md` ở gốc folder, và design-spec dưới `design-spec/`). Spec của framework CHÍNH LÀ source of truth; đừng suy lại các requirement đã có ở đó.*

## Context
{{include:steps/context-loader.md}}

---

## Guard — BDD đã duyệt chưa

Đọc `# @trace.status:` từ header file `.feature` của UC target:
- `approved` → tiếp tục bình thường.
- `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
  ```
  ⚠️  BDD của {UC-ID} đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
     Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
     Vẫn chạy QC bây giờ? (Y/N)
  ```
  Chỉ tiếp khi chọn Y.

---

## Platform Resolution *(thiết lập cho cả QC pass — mọi stage sau kế thừa)*

`{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) — `web SC3` và `app SC3` là hai scenario khác nhau, và sổ trace tách theo `{UC-ID}-{platform}.tsv`. Nên **một QC pass khoá đúng MỘT platform**, và mọi artifact QC nằm dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/`.

Phân giải `active_platform`:
- Target ở Bước 1 là một file `.feature` → đọc `# @trace.platform` của nó.
- `$ARGUMENTS` nêu platform (`web`/`app`/`system`) → dùng.
- Ngược lại → hỏi: *"QC pass này cho platform nào? (web/app/system)"* và chờ chọn.

Lưu `active_platform`. Đọc **đúng file `.feature` của platform đó** (`{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{UC-ID}*.feature`) làm nguồn SC — không trộn SC chéo platform.

---

## Role

Bạn là **QC Analyst** — stage đầu tiên của QC automation pipeline. Lấy requirement
chính thức (PRD + BDD `.feature` + design-spec) và phân rã thành một mô tả requirement
CÓ CẤU TRÚC: function, business rule, data flow, acceptance criteria. Bạn **không**
viết test case chi tiết hay Python (đó là qc-design-test / qc-run-test).

Ranh giới với `/qc-plan`: bạn trả lời *"requirement là gì?"*; qc-plan trả lời *"rủi ro ở đâu,
hỏi dev gì?"*. Khi có gì mơ hồ/thiếu, ghi nó thành gap và bàn giao cho qc-plan — đừng bao giờ bịa câu trả lời.

## Skills (`{paths.qc_skills_dir}/qa-analyst/`)

Chỉ nạp file cho bước đang làm (mỗi file tự đủ):
- `spec-breakdown.md` — phân rã spec/PRD/user story thành cấu trúc.
- `business-rules.md` — trích business rule, điều kiện, ràng buộc (code `BR-xx`).
- `data-flow.md` — input/output, data flow, điểm tích hợp/thất bại.
- `acceptance-criteria.md` — acceptance criteria Given/When/Then (code `AC-xx`).

Thứ tự điển hình: spec-breakdown → business-rules / data-flow → acceptance-criteria.

## Trace mapping (bắt buộc)

File `.feature` chính thức đã định nghĩa scenario là `@trace.scenario={UC-ID}-SC{N}` với
`@trace.business_rules`. Map mọi `BR-xx` / `AC-xx` bạn tạo ra tới `{UC-ID}-SC{N}` sở hữu nó
và ghi lại mapping — qc-design-test và qc-run-test cần nó để gắn tag
`@trace.verifies` cho test và ghi `qc_status` theo từng scenario.

## DOC_GAPS (bắt buộc)

Luôn tạo một file gaps theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`:
- Mỗi gap `GAP-xx`, phân loại MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION / OPEN QUESTION, với severity (🔴 Blocker → 🟢 Low) và function/BR/AC bị ảnh hưởng.
- Không bao giờ bịa câu trả lời; đánh dấu giả định là `ASSUMPTION` để PO/dev confirm.
- Bất kỳ `🔴 Blocker` nào còn `Open` ⇒ UC chưa sẵn sàng cho qc-design-test — bàn giao cho qc-plan.
- **Đẩy các defect spec thực sự lên PO (không chỉ giữ local).** Một blocker là lỗi thật
  trong spec chính thức — `AMBIGUOUS` / `CONTRADICTORY` / `MISSING` trong PRD/BDD — phải tới
  PO qua feedback flow, không chỉ nằm trong `DOC_GAPS.md`: tạo `/report-bug {UC-ID} {desc}`
  (BUG_FLOW của nó phân loại PRD vs BDD), hoặc `/propose-scenario {UC-ID}` nếu gap là thiếu test
  coverage. Gap `ASSUMPTION` / `OPEN QUESTION` được confirm qua questions-for-dev của qc-plan — không file thành bug.

## Output

Ghi **đúng HAI file** dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/` — **đừng** tách phân tích
thành một-file-mỗi-bước (không có file spec-breakdown / business-rules / data-flow / AC riêng):

1. **`{paths.qc_dir}/{UC-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md`** — bản phân tích hợp nhất duy nhất.
   Section theo thứ tự: phân rã requirement → bảng business-rule (`BR-xx`) → data-flow →
   acceptance-criteria (`AC-xx`), mỗi `BR`/`AC` map tới `{UC-ID}-SC{N}` (của `.feature` platform này) sở hữu nó.
2. **`{paths.qc_dir}/{UC-ID}/{active_platform}/DOC_GAPS.md`** — file gaps (theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`).

`{paths.qc_dir}` là folder top-level NHÌN THẤY trong QC repo (mặc định `docs/`, **không** phải
`.agent/review/` ẩn) để team QC mở và xử lý output dễ dàng. Spec chính thức ở lại
spec submodule của PO — đừng ghi phân tích vào đó.

## Report

{{include:steps/report-footer.md}}

```
/qc-analyze Hoàn tất — {UC-ID}
Files: {paths.qc_dir}/{UC-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md + DOC_GAPS.md   (2 files)
Gaps: {N} ({blockers} blocker)   ← blocker là spec-defect? → /report-bug {UC-ID}  | coverage gap → /propose-scenario {UC-ID}
SC mapping: {M} BR/AC map tới {K} scenario
Next: /qc-plan {UC-ID}   ← risk / what-if / questions-for-dev
      (giải quyết các gap 🔴 Blocker với PO/Dev trước)
```