@educa-corp/sdd-framework 0.9.4 → 0.9.5

package/core/commands/qc-analyze.md

@@ -1,17 +1,17 @@
----
-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
-
-*Checkpoint: **chặn thường** — lệnh ghi 2 file artifact. `--yes` bỏ qua được (gate Bước 3a).*
-
+---
+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
+
+*Checkpoint: **chặn thường** — lệnh ghi 2 file artifact. `--yes` bỏ qua được (gate Bước 3a).*
+
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
 Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
@@ -163,355 +163,425 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
 - "N" → dừng, hỏi người dùng muốn thay đổi gì.
 - Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
-
-
-*Lưu ý: Với lệnh này, target ở Bước 1 là một **TICKET-ID** (mã PRD), hoặc một UC-ID / file feature / file PRD — cả ba đều quy về TICKET-ID ở §Phạm vi QC. Trạm này chạy cho **cả PRD × một nền**. Đọc spec chính thức của **mọi UC trong phạm vi** — 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ó ở đó. **Ngoài ra đọc tech-doc gộp** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` làm **nguồn thứ hai** — xem §Đối chiếu tài liệu kỹ thuật.*
-
-## Context
+
+
+*Lưu ý: Với lệnh này, target ở Bước 1 là một **TICKET-ID** (mã PRD), hoặc một UC-ID / file feature / file PRD — cả ba đều quy về TICKET-ID ở §Phạm vi QC. Trạm này chạy cho **cả PRD × một nền**. Đọc spec chính thức của **mọi UC trong phạm vi** — 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ó ở đó. **Ngoài ra đọc tech-doc gộp** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` làm **nguồn thứ hai** — xem §Đối chiếu tài liệu kỹ thuật.*
+
+## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
 rồi mới tiếp tục phần bên dưới.
 
 Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ
 `project-lessons`, và routing service (chế độ umbrella) đều **chưa được phân giải** — mọi
-placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
-
----
-
-## Phạm vi QC — PRD nào, nền nào, những UC nào
-
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
+
+---
+
+## Phạm vi QC — PRD nào, nền nào, những UC nào
+
 **BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,
 rồi mới tiếp tục phần bên dưới.
 
 Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
 `qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).
 Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
-cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
-
-> **QC chạy trên BDD chưa chốt có thể phải làm lại.** `qc-scope` mặc định chỉ lấy UC có
-> `@trace.status: approved`; UC còn nháp vẫn vào bảng *Phạm vi phân tích* của `DOC_GAP.md`
-> với dấu `⏸ Chưa xét` — **không im lặng bỏ khỏi bảng**, vì "chưa xét" khác "đã xét, sạch".
-> Cố ý QC sớm thì thêm `--include-draft`, và artifact phải ghi rõ nó dựa trên BDD nháp.
-
-> **Vì sao trạm này chạy CẢ PRD chứ không từng UC** *(B11)*. Ba lý do, theo thứ tự quan trọng:
->
-> 1. **Mâu thuẫn chéo UC chỉ lộ ra khi đọc cùng lúc.** UC1 nói một kiểu, UC3 nói kiểu khác —
->    chạy tách từng UC thì về **cấu trúc** là không thể thấy, không phải "khó thấy".
-> 2. **Rẻ hơn.** PRD, bản thiết kế, tài liệu kỹ thuật là nguồn **dùng chung**; chạy per-UC là
->    đọc lại chúng mỗi UC một lượt. Phần dùng chung chiếm đa số đầu vào.
-> 3. **Một tài liệu cho một tính năng** là cách PO và QC vốn làm việc — file gốc của đội QC
->    (`DOC_GAP_FEAT-02-3.md`) không có hậu tố UC, và `qa-planner/test-plan.md` vốn viết
->    *"Test Plan cho một feature"*.
-
----
-
-## Đối chiếu tài liệu kỹ thuật *(nguồn thứ hai — bắt lệch nghiệp vụ ↔ kỹ thuật)*
-
-Định vị tech-doc gộp cấp PRD: `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`.
-Nó phủ **nhiều UC** — và trạm này cũng phủ nhiều UC, nên đọc **mọi phần chạm `uc_list`**
-(đối chiếu `@trace.ucs` ở header với `uc_list`). Phần thuộc UC ngoài phạm vi (`⏸ Chưa xét`) thì bỏ qua.
-
-> **Đây là chỗ layout cấp PRD trả lãi rõ nhất.** Tech-doc gộp là **một** tài liệu phủ cả PRD.
-> Chạy per-UC thì nó bị đọc lại N lần, mỗi lần lọc bỏ gần hết — và mâu thuẫn giữa hai UC trong
-> **cùng** tài liệu đó không lần nào lộ ra, vì không lần nào thấy cả hai.
-
-**Không tìm thấy → cảnh báo mềm, KHÔNG chặn** (dự án có thể chưa dựng tech-doc):
-```
-⚠️  Không có tech-doc cho {TICKET-ID} — phân tích chỉ dựa trên PRD + BDD + design-spec.
-   Lệch giữa yêu cầu nghiệp vụ và hợp đồng kỹ thuật (enum, mã lỗi, ràng buộc field) sẽ KHÔNG được phát hiện ở trạm này.
-```
-
-**Có → đối chiếu các mục sau với PRD/BDD, mỗi chỗ vênh là một gap `CONTRADICTORY`:**
-
-| Mục tech-doc | Đối chiếu gì với PRD/BDD |
-|---|---|
-| §3 Mô hình dữ liệu | thực thể/field/quan hệ PRD nhắc tới có khớp không |
-| **§4 Hợp đồng API** | **enum & tập giá trị hợp lệ** · ràng buộc field (độ dài, định dạng, bắt buộc) · **mã lỗi** — PRD nêu bao nhiêu nhánh lỗi, contract định nghĩa bao nhiêu |
-| §4.5 Ánh xạ component UI | màn/component PRD·design-spec mô tả có mặt đủ không |
-| §5 Luồng chính | thứ tự bước, nhánh rẽ có khớp scenario `.feature` không |
-| §6 Điểm tích hợp | side-effect PRD nêu (gửi sự kiện, gọi dịch vụ khác) có được định nghĩa không |
-| §8 Xử lý lỗi & biên | trường hợp biên PRD nêu có đường xử lý không, và ngược lại |
-
-> **Vì sao mục này tồn tại.** Có một lớp gap **chỉ lộ ra khi so hai loại tài liệu với nhau** —
-> đọc riêng bên nào cũng thấy hợp lý. Ca điển hình: PRD viết *"chọn lớp 1–6"*, contract định
-> nghĩa enum `1..9`. Không ai đọc cả hai thì không ai thấy, và nó ra tận lúc chạy thật.
-> **Đây là lý do trạm này đọc tech-doc — không phải để hiểu kỹ thuật, mà để bắt chỗ hai bên nói khác nhau.**
-
-### §12 GAP Register — ĐỌC, KHÔNG GHI
-
-Tech-doc có sổ ẩn số thiết kế riêng (`§12`), với vòng đời và người chịu trách nhiệm riêng, và
-`/generate-code` đã canh nó. **Trạm này chỉ đọc, tuyệt đối không ghi vào.**
-
-Với mỗi mục `open` trong §12 chạm **bất kỳ UC trong `uc_list`**:
-- **KHÔNG mở gap mới** trong `DOC_GAP.md` về cùng chuyện đó.
-- Ghi vào `REQUIREMENT_ANALYSIS.md` mục *"Đang chờ chốt (từ §12 tech-doc)"*: `{id}` · **UC** · điều chưa biết · owner · severity.
-- Test case chạm nó về sau sẽ bị chặn — nhưng bị chặn bởi **một mục đã có người xử lý**, không phải bởi một câu hỏi mới gửi PO.
-
-> **Vì sao không ghi vào.** Một ẩn số đã nằm trong §12 nghĩa là **đã có người đang lo**: có
-> owner, có mức chặn, có cổng chặn sinh code. Mở lại nó thành gap QC là gửi PO một câu hỏi
-> về thứ không phải việc của PO, và tạo hai sổ cùng theo dõi một chuyện — rồi chúng lệch nhau.
-> Đây đúng là **câu hỏi lọc Q1** của `steps/gap-verify.md` (*"chỗ này đã được trả lời ở tài liệu
-> khác chưa?"*), chỉ mở rộng phạm vi "tài liệu khác" thêm một nguồn.
-
-**Ngoại lệ — mục `spec-defect` là việc của PO.** §12 phân ba loại: `nội tại` (backend tự quyết) ·
-`cross-service` (đội khác) · `spec-defect` (PRD/BDD sai hoặc thiếu). Hai loại đầu → ghi "đang chờ".
-Loại thứ ba **đúng là gap tài liệu** → vẫn ghi vào `DOC_GAP.md` (cột `UC` = UC bị chạm), trỏ
-ngược về `{id}` của §12 để không đếm hai lần.
-
----
-
-## 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 — **làm cho từng UC trong `uc_list`**, và `BR`/`AC` phải mang rõ UC của nó
-(một file phân tích giờ phủ nhiều UC, nên `BR-01` không còn tự phân biệt được là của UC nào) — 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.
-
-## Quét gap — hai nguồn, gộp rồi mới thẩm định
-
-Gap đến từ **hai chỗ**, và chúng bổ sung nhau chứ không thay thế:
-
-| Nguồn | Trả lời câu | Gap là |
-|---|---|---|
-| **4 kỹ năng phân tích** ở trên | *"yêu cầu là gì?"* | sản phẩm phụ — đang bóc luật nghiệp vụ thì gặp chỗ mâu thuẫn |
-| **Quét theo lăng kính** *(dưới đây)* | *"còn thiếu gì?"* | mục tiêu chính |
-
-### Quét theo lăng kính
-
-Chạy `steps/review-fanout.md` với:
-
-| Tham số | Giá trị |
-|---|---|
-| `DIMENSIONS` | **4 lăng kính** — `D2 Xử lý lỗi` · `D3 Giao diện` · `D4 Dữ liệu & cấu hình` · `D5 Đối chiếu chéo` **(thu hẹp — xem dưới)** *(định nghĩa ở `{paths.qc_skills_dir}/qa-analyst/exhaustive-gap-scanner.md`)* |
-| `FINDINGS SCHEMA` | như §Output dưới đây |
-| `GRANULARITY` | **`auto`** — chia theo ngưỡng kích thước, KHÔNG ép mịn theo từng UC |
-| `VERIFY` | **`off`** — thẩm định chạy MỘT lần ở bước sau, trên tập đã gộp |
-
-**`D5` chạy ở dạng THU HẸP — chỉ 2 trong 4 cặp tài liệu:**
-
-| Cặp | |
-|---|---|
-| `PRD ↔ design-spec/` | ✅ **SO** — không ai đối chiếu nội dung. `/generate-bdd` chỉ kiểm `Built from PRD` (số phiên bản); cùng phiên bản mà nội dung lệch thì lọt |
-| `bdd/{platform}/ ↔ design-spec/` | ✅ **SO** — không ai |
-| `PRD ↔ bdd/` | ❌ bỏ — `/review-context` **B1** đã làm |
-| `PRD·bdd/ ↔ tech-docs/` | ❌ bỏ — §Đối chiếu tài liệu kỹ thuật **ở trên** đã làm |
-
-> **Cả hai cặp SO đều dính `design-spec/`** — artifact duy nhất trong feature package mà **không
-> tài liệu nào đối chiếu nội dung với nó**. Đừng lẫn với `tech-docs/`: `design-spec/` là *giao diện
-> Designer vẽ*, `tech-docs/` là *hợp đồng hệ thống* — và `tech-docs/` đã được phủ ở §trên.
->
-> Trạm này **đã đọc `design-spec/`** từ trước (nó nằm trong danh sách nguồn ở Gate), nên `D5`
-> không nạp thêm file nào — chỉ bắt nó **so** thay vì chỉ **đọc**. Rẻ hơn một lăng kính thường.
-
-**`D1 Luật nghiệp vụ` là lăng kính duy nhất KHÔNG bật:** `qa-analyst/business-rules.md` đã hỏi
-4/5 câu của nó, và hỏi cụ thể hơn — *"min/max · ký tự cho phép · trim · định dạng"* thay vì
-*"ngưỡng đã chốt chưa"*.
-
-> **Ghi lại vì sao `D5` từng bị tắt:** lý do ban đầu là *"trùng nhiều"* — **đúng một nửa**. Nó phủ
-> **bốn** cặp, chỉ **hai** cặp đã có người làm. Sai vì suy từ ấn tượng thay vì đếm danh sách; bảng
-> kiểm chứng 31 câu hỏi (`docs/plans/qc-implementation-log.md`) là thứ đáng lẽ phải làm **trước**
-> khi quyết. Đừng tắt lại `D5` mà không đọc bảng đó.
-
-> **`GRANULARITY = auto`, không phải `per-uc`.** `/refine-prd` ép mịn theo từng UC vì ở tầng PRD
-> một gap bỏ sót **im lặng đi tiếp** tới tận lúc chạy thật. Ở đây khác: gap bỏ sót còn **bốn lớp
-> chặn phía sau** — trạm 3 bật ngược khi không viết nổi giá trị mong đợi, trạm 4 soát độ phủ,
-> trạm 5 phân loại lỗi thật vs script sai. Ép mịn ở đây tốn gấp ~3 lần cho tính năng nhỏ mà đổi
-> lấy một lưới an toàn đã có sẵn ba lớp khác.
-
-### Gộp trước, thẩm định sau
-
-Gộp gap từ **cả hai nguồn** vào một tập trước khi sang bước thẩm định.
-
-> **Không thẩm định từng nguồn riêng.** Phép kiểm `T6` của `gap-verify` là *"hai gap cùng gốc
-> thì gộp lại"* — nó chỉ chạy được khi **thấy toàn bộ** tập. Thẩm định hai lần trên hai tập rời
-> thì không bắt được trùng lặp chéo nguồn, và PO nhận hai câu hỏi giống nhau.
-
----
-
-## DOC_GAP (bắt buộc)
-
-Luôn tạo **đúng MỘT** file gap cho cả (PRD × nền) theo
-`{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md` — các UC là các hàng bên trong, phân
-biệt bằng cột `UC`:
-- **Bảng 11 cột**, cột 2 là `UC`. ID gap `GAP-UC{N}-{nnn}` (vd `GAP-UC1-001`); gap thuộc cả
-  PRD → `GAP-GEN-{nnn}`. Đánh số **độc lập trong từng UC** — phân tích lại UC1 KHÔNG được làm
-  đổi số gap của UC2, vì test case đã có đang trỏ `🚫 Block: [GAP-UC2-003]`.
-- **Section `Phạm vi phân tích`** — mỗi UC một hàng kèm `@trace.status`, đã phân tích chưa, số
-  gap. UC ngoài phạm vi ghi `⏸ Chưa xét`, **không bỏ khỏi bảng**.
-- Mỗi gap 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 ở cột `UC` của hàng đó** chưa sẵn sàng cho
-  qc-design-test — bàn giao cho qc-plan. *Chặn theo từng UC, KHÔNG chặn cả PRD:* một blocker ở
-  UC3 không có lý do gì dừng việc thiết kế test cho UC1. Ghi rõ UC nào bị chặn ở report.
-- **Đẩ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_GAP.md`: tạo `/report-bug {UC-ID} {desc}`
-  (`{UC-ID}` lấy từ cột `UC` của hàng gap — bug đi theo UC, không theo PRD)
-  (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.
-
-### Thẩm định trước khi bàn giao *(bắt buộc)*
-
-Sinh xong `DOC_GAP.md`, **đọc `.agent/steps/gap-verify.md` và chạy toàn bộ quy trình trong đó**
-với:
-- `FINDINGS` = mọi gap đang `Open` trong `DOC_GAP.md`
-- `EVIDENCE_ROOT` = `{paths.specs_dir}` — spec repo của PO, **không** phải `{paths.qc_dir}`
-- `VERDICT_FIELD` = cột `Trạng thái` + `Câu trả lời` của bảng gap
-- `RERATE` = `on`
-
-Gap rớt thẩm định được **đóng kèm lý do**, KHÔNG xoá — người đọc phải kiểm chứng được vì sao
-nó bị loại. Cập nhật `Tổng số gap` + bảng ưu tiên sau khi áp verdict, và in khối
-`[GAP VERIFY]` + cam kết cuối vào report.
-
-> **Vì sao bắt buộc, không phải tuỳ chọn.** Bước phân tích ở trên chỉ có lực **tìm thêm** —
-> bốn skill lần lượt quét spec và mỗi cái đều được khuyến khích ghi ra chỗ nghi ngờ. Không có
-> bước nào hỏi ngược *"cái vừa ghi có thật không?"*. Hệ quả đo được ở đội QC: phần lớn gap sinh
-> ra là gap ảo — spec đã trả lời ở tài liệu khác, hoặc trích dẫn sai, hoặc là chuyện QC tự quyết
-> được. Mà gap ảo không chỉ tốn thời gian PO: nó **làm PO mất tin vào cả danh sách**, và lúc đó
-> những gap thật cũng chết theo. `gap-verify` là bộ lọc duy nhất đứng giữa hai chuyện đó.
-
-## Output
-
-Ghi **hai file** dưới `{qc_artifact_dir}` (= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/`)
-+ **một** dưới `{paths.refinement_dir}/`.
-
-**Mỗi loại đúng MỘT file cho cả PRD** — đừng tách một-file-mỗi-UC, và cũng đừng tách
-một-file-mỗi-bước (không có file spec-breakdown / business-rules / data-flow / AC riêng):
-
-1. **`{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`** — bản phân tích hợp nhất duy nhất cho cả PRD.
-   Mở đầu bằng **bảng `Phạm vi phân tích`** (cùng nội dung với bảng trong `DOC_GAP.md`), rồi
-   **một mục cho mỗi UC trong phạm vi**, mỗi mục 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` nền này) sở hữu nó.
-   Thêm một mục **"Mâu thuẫn chéo UC"** — chỗ hai UC của cùng PRD nói khác nhau. Rỗng thì ghi
-   "Không có". *Đây là thứ chỉ trạm cấp PRD nhìn thấy được; đừng bỏ mục.*
-   Cuối file thêm mục **"Đang chờ chốt (từ §12 tech-doc)"** — các ẩn số thiết kế `open` chạm
-   các UC trong phạm vi (`{id}` · UC · điều chưa biết · owner · severity). Rỗng thì ghi
-   "Không có"; **đừng bỏ mục**.
-2. **`{qc_artifact_dir}DOC_GAP.md`** — file gap, theo
-   `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md` + luật viết ở
-   `{paths.qc_skills_dir}/qa-analyst/spec-issue-reporter.md`. Bắt buộc:
-   - **Bảng 11 cột** đúng thứ tự, có cột **`UC`** (cột 2) và cột **Giao cho đội** (Dev / PO / BA / Design / Kiến trúc / Dữ liệu).
-   - Section **"Phạm vi phân tích"** ngay sau metadata — mỗi UC một hàng kèm `@trace.status`,
-     đã phân tích chưa, số gap. UC ngoài phạm vi ghi `⏸ Chưa xét`.
-   - Ô câu hỏi đủ **bốn phần** tách bằng `<br/>`: **Bối cảnh → Vấn đề → Tại sao quan trọng → Gợi ý**.
-     *Ba phần đầu cho PO xếp ưu tiên; phần cuối cho PO trả lời nhanh mà không phải nghĩ lại từ đầu.*
-   - Section **"Tài liệu đầu vào đã đọc để phân tích"** đặt ngay sau metadata — liệt kê **đủ** mọi
-     file đã mở. Đây là căn cứ độ phủ: không có nó thì không ai phân biệt được *"đã đọc và không thấy"*
-     với *"chưa đọc"*.
-   - Mức nặng nhất dùng từ **`🔴 Blocker`** (không phải `Critical`) — `/qc-run-test` đọc đúng từ này
-     để đặt *"scenario đang chờ PO"* vào sổ trace.
-3. **`{paths.refinement_dir}/{TICKET-ID}-qa-findings.yaml`** — **cùng dữ liệu gap**, ở định dạng Review Board đọc được. Xem §Bản findings dưới đây.
-
-`{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 đó.
-
-### Bản findings — một nguồn, hai mặt
-
-File `.yaml` và `DOC_GAP.md` là **cùng một tập gap**, không phải hai tập. Sinh `DOC_GAP.md`
-trước (nó là bản người đọc), rồi **render** sang `.yaml` — đừng phân tích lại lần hai.
-
-Dùng **đúng schema của `/refine-prd`** để Review Board đọc được cả hai loại file:
-
-```yaml
-prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
-ticket_id: "{TICKET-ID}"
-platform: "{active_platform}"
-ucs: ["{UC-ID}", "…"]          # các UC TRONG phạm vi (approved) — theo thứ tự
-ucs_skipped: ["{UC-ID}"]       # UC chưa xét, kèm lý do ở DOC_GAP §Phạm vi phân tích
-generated_at: "{ISO datetime}"
-generated_by: "qc-analyze"
-status: "pending_review"
-
-findings:
-  - id: "F001"
-    lens: "QA"                    # LUÔN là QA — file này chỉ có một lăng kính
-    severity: "critical"          # critical | major | minor  ← map từ 🔴/🟠/🟡⚪ của DOC_GAP
-    section: "{section PRD/BDD chứa vấn đề}"
-    uc_id: "{UC-ID}"
-    quote: "{trích nguyên văn ≤120 ký tự từ spec tại đúng chỗ}"
-    finding: "{gap là gì}"
-    suggestion: "{cần PO/BA làm rõ điều gì}"
-    resolution_edge_cases: []     # để [] — phân tích bậc-hai là việc của /refine-prd
-    auto_fixable: false           # LUÔN false — xem cảnh báo dưới
-    status: "pending"
-    applied_via: ""
-    gap_ref: "GAP-UC1-001"        # trỏ ngược về hàng trong DOC_GAP.md (ID mang UC)
-
-summary:
-  total_findings: {N}
-  by_severity: { critical: {N}, major: {N}, minor: {N} }
-  by_lens: { QA: {N} }
-  recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
-```
-
-> **`auto_fixable` LUÔN `false`, và KHÔNG có `--resume` cho file này.**
->
-> Review Board có nút *"chấp nhận rồi tự sửa PRD"*. Với gap của `/refine-prd` thì đúng — nó chạy
-> ở **thời điểm PRD**, sửa PRD lúc đó là sửa đúng chỗ đúng lúc.
->
-> Gap của lệnh này phát hiện **sau khi code đã xong**. Tự sửa PRD ở thời điểm đó là **sửa sau lưng
-> cả dây chuyền**: BDD sinh từ PRD cũ, code sinh từ BDD đó, sổ kết quả kiểm thử neo vào scenario
-> của BDD đó. Đổi PRD mà không đi lại đường ấy thì mọi thứ phía sau nói dối.
->
-> Đường đúng vẫn là kênh đã có: `/report-bug` cho defect spec thật, `/propose-scenario` cho thiếu
-> độ phủ. File `.yaml` này để **PO đọc và quyết trong một chỗ quen**, không phải để máy tự áp.
-
-**File riêng, không ghi chung với `/refine-prd`.** Cả hai giờ đều ở cấp PRD, nên khác biệt nằm
-ở **hậu tố**: `{TICKET-ID}-qa-findings.yaml` (trạm này) vs `{prd-slug}-findings.yaml`
-(`/refine-prd`). Đừng gộp. Ghi chung sẽ phá trường `applied_to_version` mà `/refine-prd` dùng để
-phân biệt *"PRD đổi do chính tôi áp fix"* với *"có người lạ sửa"* — và nó sẽ mãi mãi tưởng có
-người sửa sau lưng, mỗi lần chạy đều quét lại toàn bộ kèm cảnh báo giả.
-
----
-
-## Report
-
+cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
+
+> **QC chạy trên BDD chưa chốt có thể phải làm lại.** `qc-scope` mặc định chỉ lấy UC có
+> `@trace.status: approved`; UC còn nháp vẫn vào bảng *Phạm vi phân tích* của `DOC_GAP.md`
+> với dấu `⏸ Chưa xét` — **không im lặng bỏ khỏi bảng**, vì "chưa xét" khác "đã xét, sạch".
+> Cố ý QC sớm thì thêm `--include-draft`, và artifact phải ghi rõ nó dựa trên BDD nháp.
+
+> **Vì sao trạm này chạy CẢ PRD chứ không từng UC** *(B11)*. Ba lý do, theo thứ tự quan trọng:
+>
+> 1. **Mâu thuẫn chéo UC chỉ lộ ra khi đọc cùng lúc.** UC1 nói một kiểu, UC3 nói kiểu khác —
+>    chạy tách từng UC thì về **cấu trúc** là không thể thấy, không phải "khó thấy".
+> 2. **Rẻ hơn.** PRD, bản thiết kế, tài liệu kỹ thuật là nguồn **dùng chung**; chạy per-UC là
+>    đọc lại chúng mỗi UC một lượt. Phần dùng chung chiếm đa số đầu vào.
+> 3. **Một tài liệu cho một tính năng** là cách PO và QC vốn làm việc — file gốc của đội QC
+>    (`DOC_GAP_FEAT-02-3.md`) không có hậu tố UC, và `qa-planner/test-plan.md` vốn viết
+>    *"Test Plan cho một feature"*.
+
+---
+
+## Đối chiếu tài liệu kỹ thuật *(nguồn thứ hai — bắt lệch nghiệp vụ ↔ kỹ thuật)*
+
+Định vị tech-doc gộp cấp PRD: `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`.
+Nó phủ **nhiều UC** — và trạm này cũng phủ nhiều UC, nên đọc **mọi phần chạm `uc_list`**
+(đối chiếu `@trace.ucs` ở header với `uc_list`). Phần thuộc UC ngoài phạm vi (`⏸ Chưa xét`) thì bỏ qua.
+
+> **Đây là chỗ layout cấp PRD trả lãi rõ nhất.** Tech-doc gộp là **một** tài liệu phủ cả PRD.
+> Chạy per-UC thì nó bị đọc lại N lần, mỗi lần lọc bỏ gần hết — và mâu thuẫn giữa hai UC trong
+> **cùng** tài liệu đó không lần nào lộ ra, vì không lần nào thấy cả hai.
+
+**Không tìm thấy → cảnh báo mềm, KHÔNG chặn** (dự án có thể chưa dựng tech-doc):
+```
+⚠️  Không có tech-doc cho {TICKET-ID} — phân tích chỉ dựa trên PRD + BDD + design-spec.
+   Lệch giữa yêu cầu nghiệp vụ và hợp đồng kỹ thuật (enum, mã lỗi, ràng buộc field) sẽ KHÔNG được phát hiện ở trạm này.
+```
+
+**Có → đối chiếu các mục sau với PRD/BDD, mỗi chỗ vênh là một gap `CONTRADICTORY`:**
+
+| Mục tech-doc | Đối chiếu gì với PRD/BDD |
+|---|---|
+| §3 Mô hình dữ liệu | thực thể/field/quan hệ PRD nhắc tới có khớp không |
+| **§4 Hợp đồng API** | **enum & tập giá trị hợp lệ** · ràng buộc field (độ dài, định dạng, bắt buộc) · **mã lỗi** — PRD nêu bao nhiêu nhánh lỗi, contract định nghĩa bao nhiêu |
+| §4.5 Ánh xạ component UI | màn/component PRD·design-spec mô tả có mặt đủ không |
+| §5 Luồng chính | thứ tự bước, nhánh rẽ có khớp scenario `.feature` không |
+| §6 Điểm tích hợp | side-effect PRD nêu (gửi sự kiện, gọi dịch vụ khác) có được định nghĩa không |
+| §8 Xử lý lỗi & biên | trường hợp biên PRD nêu có đường xử lý không, và ngược lại |
+
+> **Vì sao mục này tồn tại.** Có một lớp gap **chỉ lộ ra khi so hai loại tài liệu với nhau** —
+> đọc riêng bên nào cũng thấy hợp lý. Ca điển hình: PRD viết *"chọn lớp 1–6"*, contract định
+> nghĩa enum `1..9`. Không ai đọc cả hai thì không ai thấy, và nó ra tận lúc chạy thật.
+> **Đây là lý do trạm này đọc tech-doc — không phải để hiểu kỹ thuật, mà để bắt chỗ hai bên nói khác nhau.**
+
+### §12 GAP Register — ĐỌC, KHÔNG GHI
+
+Tech-doc có sổ ẩn số thiết kế riêng (`§12`), với vòng đời và người chịu trách nhiệm riêng, và
+`/generate-code` đã canh nó. **Trạm này chỉ đọc, tuyệt đối không ghi vào.**
+
+Với mỗi mục `open` trong §12 chạm **bất kỳ UC trong `uc_list`**:
+- **KHÔNG mở gap mới** trong `DOC_GAP.md` về cùng chuyện đó.
+- Ghi vào `REQUIREMENT_ANALYSIS.md` mục *"Đang chờ chốt (từ §12 tech-doc)"*: `{id}` · **UC** · điều chưa biết · owner · severity.
+- Test case chạm nó về sau sẽ bị chặn — nhưng bị chặn bởi **một mục đã có người xử lý**, không phải bởi một câu hỏi mới gửi PO.
+
+> **Vì sao không ghi vào.** Một ẩn số đã nằm trong §12 nghĩa là **đã có người đang lo**: có
+> owner, có mức chặn, có cổng chặn sinh code. Mở lại nó thành gap QC là gửi PO một câu hỏi
+> về thứ không phải việc của PO, và tạo hai sổ cùng theo dõi một chuyện — rồi chúng lệch nhau.
+> Đây đúng là **câu hỏi lọc Q1** của `steps/gap-verify.md` (*"chỗ này đã được trả lời ở tài liệu
+> khác chưa?"*), chỉ mở rộng phạm vi "tài liệu khác" thêm một nguồn.
+
+**Ngoại lệ — mục `spec-defect` là việc của PO.** §12 phân ba loại: `nội tại` (backend tự quyết) ·
+`cross-service` (đội khác) · `spec-defect` (PRD/BDD sai hoặc thiếu). Hai loại đầu → ghi "đang chờ".
+Loại thứ ba **đúng là gap tài liệu** → vẫn ghi vào `DOC_GAP.md` (cột `UC` = UC bị chạm), trỏ
+ngược về `{id}` của §12 để không đếm hai lần.
+
+---
+
+## 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 — **làm cho từng UC trong `uc_list`**, và `BR`/`AC` phải mang rõ UC của nó
+(một file phân tích giờ phủ nhiều UC, nên `BR-01` không còn tự phân biệt được là của UC nào) — 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.
+
+## Guard — BR-tag *(phép so khớp cơ học, chạy SAU khi ghi file, TRƯỚC CHECKPOINT)*
+
+§Trace mapping ở trên đi **một chiều**: từ `BR` bạn tạo ra → `SC` sở hữu nó. Chiều đó đúng và
+cần. Nhưng chiều **ngược lại** — từ tag `@trace.business_rules` đã có trong `.feature` → `BR`
+trong bản phân tích — mới là chiều bắt được **cái bỏ sót**, và nó chưa được kiểm ở đâu.
+
+BDD đã tự nói ra một phần đáp án. Mỗi scenario mang tag do `/generate-bdd` ghi khi sinh từ PRD:
+
+```gherkin
+# @trace.scenario: FT-101-UC1-SC3
+# @trace.business_rules: FT-101-UC1-BR02, FT-101-UC1-BR07
+```
+
+Nếu bản phân tích chỉ có `BR01`–`BR05` thì `BR07` là **rule mà BDD biết mà QC bỏ sót** — và đó
+là một **phép so khớp chuỗi**, máy làm được.
+
+### Bốn bước, thuần đếm và so
+
+1. **Thu A** — đọc **mọi** `.feature` của `uc_list` (đúng `active_platform`), gom toàn bộ giá trị
+   trong tag `@trace.business_rules`.
+2. **Thu B** — gom mọi `BR-xx` trong `REQUIREMENT_ANALYSIS.md` **vừa ghi**.
+3. **So** — `A ∖ B` = rule BDD nhắc mà phân tích không có.
+4. **Xử lý:**
+   - `A ∖ B` rỗng → in `Guard BR-tag: khớp {n}/{n}`
+   - `A ∖ B` ≠ rỗng → **quay lại PRD lấy nội dung thật của từng rule đó, BỔ SUNG NGAY vào
+     `REQUIREMENT_ANALYSIS.md`**, rồi in:
+     `⚠️ Guard BR-tag: bổ sung {k} rule BDD đã nhắc mà phân tích bỏ sót: {danh sách}`
+
+**Guard TỰ SỬA, không chỉ tự báo.** In cảnh báo rồi để người đi lấp là thêm một dòng nữa để bỏ
+qua. Bạn phải mở PRD, tìm rule đó, viết nội dung thật vào bản phân tích — **không** thêm một
+dòng trống mang tên `BR-xx` cho đủ số. Cảnh báo là để người **biết đã có chuyện gì xảy ra**,
+không phải để họ đi làm việc đó.
+
+**Chiều `B ∖ A` KHÔNG phải lỗi.** QC sinh `BR09` mà không tag nào nhắc → có thể QC phát hiện một
+rule BDD chưa phủ. Đó là **phát hiện tốt**: ghi thành một gap trong `DOC_GAP.md` (BDD thiếu
+scenario cho rule này), **đừng xoá**.
+
+**In dòng `Guard BR-tag:` kể cả khi sạch.** Guard im lặng khi sạch là guard không ai biết nó tồn
+tại — và không ai phát hiện được khi nó chết.
+
+> **Vì sao cần guard mà không phải self-review.** Self-review là agent **tự đọc lại bài của
+> mình**, nên nó bỏ sót đúng chỗ nó đã bỏ sót lúc viết. Guard đọc **một nguồn khác** (tag trong
+> `.feature`, do một lệnh khác ghi) rồi đối chiếu — không phụ thuộc agent có để ý hay không, và
+> chạy như nhau mỗi lần.
+>
+> **Vì sao bỏ sót ở đây đắt nhất trong cả pipeline.** Không có `BR` → `/qc-plan` không xếp rủi ro
+> cho nó → `/qc-design-test` không viết test case → `/qc-run-test` không có gì chạy → báo cáo
+> cuối nói *"coverage 100%"*. Con số đó tính trên mẫu số *"số scenario đã biết"*, không phải
+> *"số rule cần phủ"* — nên nó sai theo hướng nguy hiểm nhất: trông như đã xong.
+
+## Quét gap — hai nguồn, gộp rồi mới thẩm định
+
+Gap đến từ **hai chỗ**, và chúng bổ sung nhau chứ không thay thế:
+
+| Nguồn | Trả lời câu | Gap là |
+|---|---|---|
+| **4 kỹ năng phân tích** ở trên | *"yêu cầu là gì?"* | sản phẩm phụ — đang bóc luật nghiệp vụ thì gặp chỗ mâu thuẫn |
+| **Quét theo lăng kính** *(dưới đây)* | *"còn thiếu gì?"* | mục tiêu chính |
+
+### Quét theo lăng kính
+
+Chạy `steps/review-fanout.md` với:
+
+| Tham số | Giá trị |
+|---|---|
+| `DIMENSIONS` | **4 lăng kính** — `D2 Xử lý lỗi` · `D3 Giao diện` · `D4 Dữ liệu & cấu hình` · `D5 Đối chiếu chéo` **(thu hẹp — xem dưới)** *(định nghĩa ở `{paths.qc_skills_dir}/qa-analyst/exhaustive-gap-scanner.md`)* |
+| `FINDINGS SCHEMA` | như §Output dưới đây |
+| `GRANULARITY` | **`auto`** — chia theo ngưỡng kích thước, KHÔNG ép mịn theo từng UC |
+| `VERIFY` | **`off`** — thẩm định chạy MỘT lần ở bước sau, trên tập đã gộp |
+
+**`D5` chạy ở dạng THU HẸP — chỉ 2 trong 4 cặp tài liệu:**
+
+| Cặp | |
+|---|---|
+| `PRD ↔ design-spec/` | ✅ **SO** — không ai đối chiếu nội dung. `/generate-bdd` chỉ kiểm `Built from PRD` (số phiên bản); cùng phiên bản mà nội dung lệch thì lọt |
+| `bdd/{platform}/ ↔ design-spec/` | ✅ **SO** — không ai |
+| `PRD ↔ bdd/` | ❌ bỏ — `/review-context` **B1** đã làm |
+| `PRD·bdd/ ↔ tech-docs/` | ❌ bỏ — §Đối chiếu tài liệu kỹ thuật **ở trên** đã làm |
+
+> **Cả hai cặp SO đều dính `design-spec/`** — artifact duy nhất trong feature package mà **không
+> tài liệu nào đối chiếu nội dung với nó**. Đừng lẫn với `tech-docs/`: `design-spec/` là *giao diện
+> Designer vẽ*, `tech-docs/` là *hợp đồng hệ thống* — và `tech-docs/` đã được phủ ở §trên.
+>
+> Trạm này **đã đọc `design-spec/`** từ trước (nó nằm trong danh sách nguồn ở Gate), nên `D5`
+> không nạp thêm file nào — chỉ bắt nó **so** thay vì chỉ **đọc**. Rẻ hơn một lăng kính thường.
+
+**`D1 Luật nghiệp vụ` là lăng kính duy nhất KHÔNG bật:** `qa-analyst/business-rules.md` đã hỏi
+4/5 câu của nó, và hỏi cụ thể hơn — *"min/max · ký tự cho phép · trim · định dạng"* thay vì
+*"ngưỡng đã chốt chưa"*.
+
+> **Ghi lại vì sao `D5` từng bị tắt:** lý do ban đầu là *"trùng nhiều"* — **đúng một nửa**. Nó phủ
+> **bốn** cặp, chỉ **hai** cặp đã có người làm. Sai vì suy từ ấn tượng thay vì đếm danh sách; bảng
+> kiểm chứng 31 câu hỏi (`docs/plans/qc-implementation-log.md`) là thứ đáng lẽ phải làm **trước**
+> khi quyết. Đừng tắt lại `D5` mà không đọc bảng đó.
+
+> **`GRANULARITY = auto`, không phải `per-uc`.** `/refine-prd` ép mịn theo từng UC vì ở tầng PRD
+> một gap bỏ sót **im lặng đi tiếp** tới tận lúc chạy thật. Ở đây khác: gap bỏ sót còn **bốn lớp
+> chặn phía sau** — trạm 3 bật ngược khi không viết nổi giá trị mong đợi, trạm 4 soát độ phủ,
+> trạm 5 phân loại lỗi thật vs script sai. Ép mịn ở đây tốn gấp ~3 lần cho tính năng nhỏ mà đổi
+> lấy một lưới an toàn đã có sẵn ba lớp khác.
+
+### Gộp trước, thẩm định sau
+
+Gộp gap từ **cả hai nguồn** vào một tập trước khi sang bước thẩm định.
+
+> **Không thẩm định từng nguồn riêng.** Phép kiểm `T6` của `gap-verify` là *"hai gap cùng gốc
+> thì gộp lại"* — nó chỉ chạy được khi **thấy toàn bộ** tập. Thẩm định hai lần trên hai tập rời
+> thì không bắt được trùng lặp chéo nguồn, và PO nhận hai câu hỏi giống nhau.
+
+---
+
+## DOC_GAP (bắt buộc)
+
+Luôn tạo **đúng MỘT** file gap cho cả (PRD × nền) theo
+`{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md` — các UC là các hàng bên trong, phân
+biệt bằng cột `UC`:
+- **Bảng 11 cột**, cột 2 là `UC`. ID gap `GAP-UC{N}-{nnn}` (vd `GAP-UC1-001`); gap thuộc cả
+  PRD → `GAP-GEN-{nnn}`. Đánh số **độc lập trong từng UC** — phân tích lại UC1 KHÔNG được làm
+  đổi số gap của UC2, vì test case đã có đang trỏ `🚫 Block: [GAP-UC2-003]`.
+- **Section `Phạm vi phân tích`** — mỗi UC một hàng kèm `@trace.status`, đã phân tích chưa, số
+  gap. UC ngoài phạm vi ghi `⏸ Chưa xét`, **không bỏ khỏi bảng**.
+- Mỗi gap 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 ở cột `UC` của hàng đó** chưa sẵn sàng cho
+  qc-design-test — bàn giao cho qc-plan. *Chặn theo từng UC, KHÔNG chặn cả PRD:* một blocker ở
+  UC3 không có lý do gì dừng việc thiết kế test cho UC1. Ghi rõ UC nào bị chặn ở report.
+- **Đẩ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_GAP.md`: tạo `/report-bug {UC-ID} {desc}`
+  (`{UC-ID}` lấy từ cột `UC` của hàng gap — bug đi theo UC, không theo PRD)
+  (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.
+
+### Thẩm định trước khi bàn giao *(bắt buộc)*
+
+Sinh xong `DOC_GAP.md`, **đọc `.agent/steps/gap-verify.md` và chạy toàn bộ quy trình trong đó**
+với:
+- `FINDINGS` = mọi gap đang `Open` trong `DOC_GAP.md`
+- `EVIDENCE_ROOT` = `{paths.specs_dir}` — spec repo của PO, **không** phải `{paths.qc_dir}`
+- `VERDICT_FIELD` = cột `Trạng thái` + `Câu trả lời` của bảng gap
+- `RERATE` = `on`
+
+Gap rớt thẩm định được **đóng kèm lý do**, KHÔNG xoá — người đọc phải kiểm chứng được vì sao
+nó bị loại. Cập nhật `Tổng số gap` + bảng ưu tiên sau khi áp verdict, và in khối
+`[GAP VERIFY]` + cam kết cuối vào report.
+
+> **Vì sao bắt buộc, không phải tuỳ chọn.** Bước phân tích ở trên chỉ có lực **tìm thêm** —
+> bốn skill lần lượt quét spec và mỗi cái đều được khuyến khích ghi ra chỗ nghi ngờ. Không có
+> bước nào hỏi ngược *"cái vừa ghi có thật không?"*. Hệ quả đo được ở đội QC: phần lớn gap sinh
+> ra là gap ảo — spec đã trả lời ở tài liệu khác, hoặc trích dẫn sai, hoặc là chuyện QC tự quyết
+> được. Mà gap ảo không chỉ tốn thời gian PO: nó **làm PO mất tin vào cả danh sách**, và lúc đó
+> những gap thật cũng chết theo. `gap-verify` là bộ lọc duy nhất đứng giữa hai chuyện đó.
+
+## Output
+
+Ghi **hai file** dưới `{qc_artifact_dir}` (= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/`)
++ **một** dưới `{paths.refinement_dir}/`.
+
+**Mỗi loại đúng MỘT file cho cả PRD** — đừng tách một-file-mỗi-UC, và cũng đừng tách
+một-file-mỗi-bước (không có file spec-breakdown / business-rules / data-flow / AC riêng):
+
+1. **`{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`** — bản phân tích hợp nhất duy nhất cho cả PRD.
+   Mở đầu bằng **bảng `Phạm vi phân tích`** (cùng nội dung với bảng trong `DOC_GAP.md`), rồi
+   **một mục cho mỗi UC trong phạm vi**, mỗi mục 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` nền này) sở hữu nó.
+   Thêm một mục **"Mâu thuẫn chéo UC"** — chỗ hai UC của cùng PRD nói khác nhau. Rỗng thì ghi
+   "Không có". *Đây là thứ chỉ trạm cấp PRD nhìn thấy được; đừng bỏ mục.*
+   Cuối file thêm mục **"Đang chờ chốt (từ §12 tech-doc)"** — các ẩn số thiết kế `open` chạm
+   các UC trong phạm vi (`{id}` · UC · điều chưa biết · owner · severity). Rỗng thì ghi
+   "Không có"; **đừng bỏ mục**.
+2. **`{qc_artifact_dir}DOC_GAP.md`** — file gap, theo
+   `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md` + luật viết ở
+   `{paths.qc_skills_dir}/qa-analyst/spec-issue-reporter.md`. Bắt buộc:
+   - **Bảng 11 cột** đúng thứ tự, có cột **`UC`** (cột 2) và cột **Giao cho đội** (Dev / PO / BA / Design / Kiến trúc / Dữ liệu).
+   - Section **"Phạm vi phân tích"** ngay sau metadata — mỗi UC một hàng kèm `@trace.status`,
+     đã phân tích chưa, số gap. UC ngoài phạm vi ghi `⏸ Chưa xét`.
+   - Ô câu hỏi đủ **bốn phần** tách bằng `<br/>`: **Bối cảnh → Vấn đề → Tại sao quan trọng → Gợi ý**.
+     *Ba phần đầu cho PO xếp ưu tiên; phần cuối cho PO trả lời nhanh mà không phải nghĩ lại từ đầu.*
+   - Section **"Tài liệu đầu vào đã đọc để phân tích"** đặt ngay sau metadata — liệt kê **đủ** mọi
+     file đã mở. Đây là căn cứ độ phủ: không có nó thì không ai phân biệt được *"đã đọc và không thấy"*
+     với *"chưa đọc"*.
+   - Mức nặng nhất dùng từ **`🔴 Blocker`** (không phải `Critical`) — `/qc-run-test` đọc đúng từ này
+     để đặt *"scenario đang chờ PO"* vào sổ trace.
+3. **`{paths.refinement_dir}/{TICKET-ID}-qa-findings.yaml`** — **cùng dữ liệu gap**, ở định dạng Review Board đọc được. Xem §Bản findings dưới đây.
+
+`{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 đó.
+
+### Bản findings — một nguồn, hai mặt
+
+File `.yaml` và `DOC_GAP.md` là **cùng một tập gap**, không phải hai tập. Sinh `DOC_GAP.md`
+trước (nó là bản người đọc), rồi **render** sang `.yaml` — đừng phân tích lại lần hai.
+
+Dùng **đúng schema của `/refine-prd`** để Review Board đọc được cả hai loại file:
+
+```yaml
+prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
+ticket_id: "{TICKET-ID}"
+platform: "{active_platform}"
+ucs: ["{UC-ID}", "…"]          # các UC TRONG phạm vi (approved) — theo thứ tự
+ucs_skipped: ["{UC-ID}"]       # UC chưa xét, kèm lý do ở DOC_GAP §Phạm vi phân tích
+generated_at: "{ISO datetime}"
+generated_by: "qc-analyze"
+status: "pending_review"
+
+findings:
+  - id: "F001"
+    lens: "QA"                    # LUÔN là QA — file này chỉ có một lăng kính
+    severity: "critical"          # critical | major | minor  ← map từ 🔴/🟠/🟡⚪ của DOC_GAP
+    section: "{section PRD/BDD chứa vấn đề}"
+    uc_id: "{UC-ID}"
+    quote: "{trích nguyên văn ≤120 ký tự từ spec tại đúng chỗ}"
+    finding: "{gap là gì}"
+    suggestion: "{cần PO/BA làm rõ điều gì}"
+    resolution_edge_cases: []     # để [] — phân tích bậc-hai là việc của /refine-prd
+    auto_fixable: false           # LUÔN false — xem cảnh báo dưới
+    status: "pending"
+    applied_via: ""
+    gap_ref: "GAP-UC1-001"        # trỏ ngược về hàng trong DOC_GAP.md (ID mang UC)
+
+summary:
+  total_findings: {N}
+  by_severity: { critical: {N}, major: {N}, minor: {N} }
+  by_lens: { QA: {N} }
+  recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
+```
+
+> **`auto_fixable` LUÔN `false`, và KHÔNG có `--resume` cho file này.**
+>
+> Review Board có nút *"chấp nhận rồi tự sửa PRD"*. Với gap của `/refine-prd` thì đúng — nó chạy
+> ở **thời điểm PRD**, sửa PRD lúc đó là sửa đúng chỗ đúng lúc.
+>
+> Gap của lệnh này phát hiện **sau khi code đã xong**. Tự sửa PRD ở thời điểm đó là **sửa sau lưng
+> cả dây chuyền**: BDD sinh từ PRD cũ, code sinh từ BDD đó, sổ kết quả kiểm thử neo vào scenario
+> của BDD đó. Đổi PRD mà không đi lại đường ấy thì mọi thứ phía sau nói dối.
+>
+> Đường đúng vẫn là kênh đã có: `/report-bug` cho defect spec thật, `/propose-scenario` cho thiếu
+> độ phủ. File `.yaml` này để **PO đọc và quyết trong một chỗ quen**, không phải để máy tự áp.
+
+**File riêng, không ghi chung với `/refine-prd`.** Cả hai giờ đều ở cấp PRD, nên khác biệt nằm
+ở **hậu tố**: `{TICKET-ID}-qa-findings.yaml` (trạm này) vs `{prd-slug}-findings.yaml`
+(`/refine-prd`). Đừng gộp. Ghi chung sẽ phá trường `applied_to_version` mà `/refine-prd` dùng để
+phân biệt *"PRD đổi do chính tôi áp fix"* với *"có người lạ sửa"* — và nó sẽ mãi mãi tưởng có
+người sửa sau lưng, mỗi lần chạy đều quét lại toàn bộ kèm cảnh báo giả.
+
+---
+
+## Self-Review *(trước khi in Report)*
+
+Theo 3 nhóm ở `{paths.qc_skills_dir}/_shared/self-review-principles.md` — **không chép lại ở đây**.
+
+- **Bịa:** mỗi `BR-xx`/`AC-xx` trích được về đúng dòng nào của PRD/BDD — không phải rule tôi tự
+  thêm? Mỗi gap `CONTRADICTORY` nêu được **cả hai** chỗ nói khác nhau, không phải một bên?
+- **Nhảy bước:** đã chạy đủ 4 kỹ năng phân tích + 4 lăng kính + §Đối chiếu tài liệu kỹ thuật —
+  không bỏ lăng kính nào vì "UC này đơn giản"?
+- **Số liệu:** `{N}` gap · `{blockers}` blocker · `{M}` BR/AC in ở report là **đếm thật trên
+  bảng vừa ghi** (`grep -cE "^\| GAP-"`), không phải áng chừng?
+
+> **`gap-verify` và self-review bổ sung nhau, KHÔNG thay nhau.** `gap-verify` kiểm **từng
+> finding** có sống sót qua T1–T6 (sâu, per-finding). Self-review kiểm **cả lượt chạy** có bịa /
+> nhảy bước / đếm sai (rộng, per-run). Chạy một cái rồi bỏ cái kia là bỏ một nửa lưới.
+>
+> Và cả hai **không thay** Guard BR-tag ở trên — guard đó là phép so khớp cơ học, xem §Ranh giới
+> trong file skill.
+
+## Report
+
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
-Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
-
-```
-/qc-analyze Hoàn tất — {TICKET-ID} ({active_platform})
-Phạm vi: {n}/{N} UC phân tích{nếu có UC chưa xét: " · ⏸ {m} chưa xét: {danh sách UC-ID} (BDD chưa approved)"}
-Files : {paths.qc_dir}/{TICKET-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md + DOC_GAP.md (11 cột)
-        {paths.refinement_dir}/{TICKET-ID}-qa-findings.yaml    ← mở bằng Review Board (chuột phải)
-Nguồn : PRD · BDD({active_platform}, {n} UC) · design-spec · tech-doc{nếu thiếu tech-doc: " (THIẾU — không đối chiếu được nghiệp vụ ↔ kỹ thuật)"}
-Quét  : 4 kỹ năng phân tích + 4 lăng kính (xử lý lỗi · giao diện · dữ liệu & cấu hình
-        · đối chiếu chéo: PRD↔design-spec, bdd↔design-spec)
-Verify: {raw} gap thô → {N} còn Open  (❌ {invalid} bịa/đã-trả-lời · ⚠️ {reclass} không phải gap nghiệp vụ · 🔁 {merge} trùng)
-Gaps  : {N} ({blockers} blocker) — theo UC: {UC1: n · UC2: n · …}{nếu có: " · toàn PRD: {n}"}
-        ← blocker là spec-defect? → /report-bug {UC-ID của hàng đó}  | coverage gap → /propose-scenario {UC-ID}
-Chéo UC: {X} mâu thuẫn giữa các UC của cùng PRD (đã ghi vào REQUIREMENT_ANALYSIS §Mâu thuẫn chéo UC)
-Chặn  : {danh sách UC có 🔴 Blocker còn Open} — các UC còn lại vẫn thiết kế test được bình thường
-Chờ chốt: {G} ẩn số §12 tech-doc đang open chạm các UC này (đã ghi vào REQUIREMENT_ANALYSIS, KHÔNG hỏi lại PO)
-SC map: {M} BR/AC map tới {K} scenario
-Next  : /qc-plan {TICKET-ID} {active_platform}   ← rủi ro / what-if / câu hỏi cho dev
-        (giải quyết các gap 🔴 Blocker với PO/Dev trước)
-```
-
-> **Dòng `Next` là bắt buộc in, không phải trang trí.** Dây gốc của đội QC ra **cả** file gap
-> **và** kế hoạch test trong một lần chạy (13/14 lần đo được ở repo của họ). Ở framework đó là
-> **hai lệnh**. Người quen dây cũ sẽ dừng lại ở đây và tưởng đã xong — dòng này là chỗ duy nhất
-> nói cho họ biết còn một bước nữa.
-
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
+
+```
+/qc-analyze Hoàn tất — {TICKET-ID} ({active_platform})
+Phạm vi: {n}/{N} UC phân tích{nếu có UC chưa xét: " · ⏸ {m} chưa xét: {danh sách UC-ID} (BDD chưa approved)"}
+Files : {paths.qc_dir}/{TICKET-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md + DOC_GAP.md (11 cột)
+        {paths.refinement_dir}/{TICKET-ID}-qa-findings.yaml    ← mở bằng Review Board (chuột phải)
+Nguồn : PRD · BDD({active_platform}, {n} UC) · design-spec · tech-doc{nếu thiếu tech-doc: " (THIẾU — không đối chiếu được nghiệp vụ ↔ kỹ thuật)"}
+Quét  : 4 kỹ năng phân tích + 4 lăng kính (xử lý lỗi · giao diện · dữ liệu & cấu hình
+        · đối chiếu chéo: PRD↔design-spec, bdd↔design-spec)
+Verify: {raw} gap thô → {N} còn Open  (❌ {invalid} bịa/đã-trả-lời · ⚠️ {reclass} không phải gap nghiệp vụ · 🔁 {merge} trùng)
+Gaps  : {N} ({blockers} blocker) — theo UC: {UC1: n · UC2: n · …}{nếu có: " · toàn PRD: {n}"}
+        ← blocker là spec-defect? → /report-bug {UC-ID của hàng đó}  | coverage gap → /propose-scenario {UC-ID}
+Chéo UC: {X} mâu thuẫn giữa các UC của cùng PRD (đã ghi vào REQUIREMENT_ANALYSIS §Mâu thuẫn chéo UC)
+Chặn  : {danh sách UC có 🔴 Blocker còn Open} — các UC còn lại vẫn thiết kế test được bình thường
+Chờ chốt: {G} ẩn số §12 tech-doc đang open chạm các UC này (đã ghi vào REQUIREMENT_ANALYSIS, KHÔNG hỏi lại PO)
+SC map: {M} BR/AC map tới {K} scenario
+Guard BR-tag: {khớp {n}/{n} | ⚠️ bổ sung {k} rule BDD đã nhắc mà phân tích bỏ sót: {danh sách}}
+Self-review: {✅ sạch | ⚠️ {n} điểm cần chú ý — liệt kê}
+Next  : /qc-plan {TICKET-ID} {active_platform}   ← rủi ro / what-if / câu hỏi cho dev
+        (giải quyết các gap 🔴 Blocker với PO/Dev trước)
+```
+
+> **Dòng `Next` là bắt buộc in, không phải trang trí.** Dây gốc của đội QC ra **cả** file gap
+> **và** kế hoạch test trong một lần chạy (13/14 lần đo được ở repo của họ). Ở framework đó là
+> **hai lệnh**. Người quen dây cũ sẽ dừng lại ở đây và tưởng đã xong — dòng này là chỗ duy nhất
+> nói cho họ biết còn một bước nữa.
+