@educa-corp/sdd-framework 0.9.0 → 0.9.2

package/core/commands/refine-prd.md

@@ -1,4 +1,4 @@
-# /refine-prd — Phân tích PRD qua 3 lăng kính review
+# /refine-prd — Phân tích PRD qua 4 lăng kính review
 
 > **Ranh giới — lệnh này chỉ áp được fix cho vấn đề mà CHÍNH NÓ tìm ra.** Resume Mode Phase 2 tự
 > cấm đụng bất kỳ section nào không được một finding chấp nhận trỏ tới, và findings sinh từ việc soi
@@ -259,10 +259,11 @@ vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
 Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
 - **DIMENSIONS** — danh sách các chiều review để fan out
-  (`/refine-prd` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
+  (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check; `/qc-analyze` → 3 lăng kính quét gap).
 - **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
 - **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
 - **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
+- **VERIFY** *(tuỳ chọn, mặc định `off`)* — `on` chèn **Phase 2.5** (`steps/gap-verify.md`) giữa critic và dedup: mỗi finding phải mở lại tài liệu nguồn tự chứng minh trước khi được giữ. Không truyền → hành vi không đổi.
 
 > **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
 > quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
@@ -381,6 +382,31 @@ Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
 
 ---
 
+## Phase 2.5 — Thẩm định *(chỉ chạy khi `VERIFY = on`)*
+
+**Vì sao có bước này.** Phase 1 và Phase 2 chỉ có **một chiều lực**: fan-out mở rộng bề
+ngang, critic lặp cho tới khi không còn gì mới — cả hai đều hỏi *"còn thiếu gì nữa?"*.
+Không có gì hỏi ngược lại *"cái vừa tìm ra có thật không?"*. Nên quy trình này đẩy **recall**
+lên mà **không có gì kéo precision lại**, và càng lặp critic thì tỉ lệ finding bịa càng cao —
+đúng thứ nó tự sinh ra: khẳng định hành vi tài liệu không nêu, trích evidence sai, hoặc gắn
+nhãn vấn đề cho thứ thực ra là chuyện làm-kỹ-hơn.
+
+Chạy `steps/gap-verify.md` trên `ALL_FINDINGS` với:
+- `FINDINGS` = `ALL_FINDINGS` (sau Phase 2)
+- `EVIDENCE_ROOT` = `{paths.specs_dir}` — hoặc giá trị lệnh gọi chỉ định
+- `VERDICT_FIELD` = trường trạng thái của FINDINGS SCHEMA mà lệnh định nghĩa
+- `RERATE` = `on`
+
+Finding bị `❌ INVALID` / `⚠️ RECLASSIFY` / `🔁 MERGE` **không đi tiếp sang Phase 3** — nhưng
+**KHÔNG bị xoá**: chúng vào file findings với trạng thái đóng + lý do, để người đọc kiểm chứng
+được vì sao chúng bị loại. Ghi lại số liệu verdict cho report.
+
+> **Chạy TRƯỚC Phase 3, không phải sau.** Dedup và giải quyết xung đột là việc tốn suy luận;
+> làm nó trên một tập còn lẫn finding bịa là vừa phí, vừa nguy hiểm — một finding ảo có thể
+> "thắng" một finding thật ở bước giữ-cái-severity-cao-hơn.
+
+---
+
 ## Phase 3 — Dedup, giải quyết xung đột, merge
 
 Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ
@@ -412,7 +438,7 @@ Convergence: {convergence_rounds} vòng critic — file findings đã đầy đ
 
 ---
 
-## Phân tích — 3 lăng kính (fan out cả ba, rồi hội tụ)
+## Phân tích — 4 lăng kính (fan out cả bốn, rồi hội tụ)
 
 Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
 
@@ -431,22 +457,23 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
        - **`applied_to_version` có mặt VÀ `==` version PRD hiện tại** → PRD đổi đúng bằng phần lệnh này tự áp, không actor khác động vào → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
        - **`applied_to_version` vắng mặt HOẶC `≠` version hiện tại** → PRD đã bị sửa bởi **actor khác** (lệnh `/review-context`, sửa tay…) sau lần resume này → KHÔNG tin được phạm vi hẹp → **FULL** (KHÔNG truyền `CHANGED_SCOPE`), kèm cảnh báo: `"PRD đổi ngoài tầm theo dõi của findings (applied_to_version={A} ≠ hiện tại={C}); quét lại toàn bộ để khỏi sót UC do người/lệnh khác sửa."`
 
-**DIMENSIONS** = 3 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
+**DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
 toàn bộ PRD qua đúng lăng kính của nó:
 
-<!-- ─────────────────────────────────────────────────────────────────────────────
-  LĂNG KÍNH BỊ TẮT (DISABLED — KHÔNG dùng, KHÔNG fan-out agent cho lăng kính này):
-
-  - **Lăng kính QA (tầng nghiệm thu)**: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
+- **Lăng kính QA (tầng nghiệm thu)** *(bật lại 2026-08-25 — xem `docs/plans/qc-implementation-log.md` B8)*: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
 
-  CÁCH THÊM LẠI QA (khi cần bật lại giai đoạn sau):
-    1. Chuyển bullet QA ở trên ra khỏi block comment này, đặt lên đầu danh sách DIMENSIONS.
-    2. Đổi "3 lăng kính"/"cả ba" → "4 lăng kính"/"cả bốn" ở: dòng tiêu đề (# /refine-prd),
-       heading "## Phân tích", câu "DIMENSIONS = N lăng kính", và steps/review-fanout.md.
-    3. Thêm "QA" lại vào enum của `lens:` trong FINDINGS SCHEMA + vào `by_lens`.
-    4. Thêm "QA" lại vào ghi chú "phán đoán DEV/SA/PO" ở LƯU Ý của schema.
-    5. Rebuild: node bin/build.js
-───────────────────────────────────────────────────────────────────────────── -->
+> **Phạm vi lăng kính QA — hẹp có chủ ý, đừng nới.** Nó hỏi về **HÌNH THỨC** của AC (*"phát biểu này kiểm chứng được không?"* · *"có lặp tầng không?"*), **KHÔNG** về **NỘI DUNG** (*"còn thiếu gì?"*).
+>
+> Lý do là thời điểm: ở đây **chỉ có PRD** — design-spec, BDD, tech-doc đều chưa tồn tại. Nên không thể phân biệt *"PRD thiếu X"* với *"PRD cố ý để X cho design-spec"*, và phép kiểm *"đã trả lời ở tài liệu khác chưa?"* **không có tài liệu khác để tra**.
+>
+> Số liệu thật (14 lần chạy ở repo QC): review chỉ-đọc-PRD ra **14 gap** trung bình, review đủ 4 nguồn ra **9,4** — khoảng 5 gap chênh lệch là câu hỏi mà tài liệu sau **trả lời hộ**. Nới lăng kính này sang câu hỏi nội dung là cố tình sinh ra 5 gap đó rồi gửi PO.
+>
+> Câu hỏi nội dung thuộc `/qc-analyze` (3 lăng kính: xử lý lỗi · giao diện · dữ liệu & cấu hình), nơi đã có đủ 4 nguồn để tra.
+>
+> **CÁCH TẮT LẠI QA** *(nếu cần)*: gỡ bullet QA ở trên · đổi `4 lăng kính`/`cả bốn` → `3`/`cả ba` ở
+> dòng tiêu đề, heading `## Phân tích`, câu `DIMENSIONS = N lăng kính`, và `steps/review-fanout.md` ·
+> gỡ `QA` khỏi enum `lens:` + `by_lens` + ghi chú `phán đoán QA/DEV/SA/PO` · sửa
+> `docs/explain/03-refine-prd.md` cho khớp · rebuild `node bin/build.js`.
 
 > **Nguyên tắc chung cho DEV & SA — đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ.**
 > Hai lăng kính này dùng con mắt kỹ thuật để **phát hiện chỗ nghiệp vụ mô tả thiếu/mơ hồ/mâu thuẫn đến mức sẽ chặn triển khai** — mục tiêu là **làm rõ vấn đề nghiệp vụ để sau này xử lý được về mặt kỹ thuật**. **KHÔNG** đưa góc nhìn kỹ thuật vào PRD, **KHÔNG** đề xuất giải pháp/cơ chế kỹ thuật. Mọi `finding` và `suggestion` phải **thuần nghiệp vụ** (tuân Business Language Guard): mô tả *cái nghiệp vụ còn thiếu/chưa rõ* và *hỏi cần làm rõ gì*, chứ không nói *làm thế nào về kỹ thuật*.
@@ -483,7 +510,7 @@ status: "pending_review"
 
 findings:
   - id: "F001"
-    lens: "DEV"          # DEV | SA | PO
+    lens: "DEV"          # QA | DEV | SA | PO
     severity: "major"    # critical | major | minor
     section: "§2. Acceptance Criteria"   # nhãn heading/section dạng người đọc
     uc_id: "{TICKET-ID}-UC{N}"           # UC mà finding thuộc về; "" nếu PRD-global (scope, metrics, problem statement)
@@ -499,8 +526,8 @@ findings:
     # true  = AI tự tin cao vào suggestion này; Review Board có thể hiển thị nút "quick accept"
     # false = cần human đọc kỹ và ghi quyết định trước khi accept
     # Resume Mode luôn áp dụng theo status (accepted|modified), bất kể auto_fixable.
-    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 3 lăng kính
-    #   là phán đoán DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
+    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 4 lăng kính
+    #   là phán đoán QA/DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
     #   quick-accept cho Board, KHÔNG để máy tự áp.
     status: "pending"
     applied_via: ""
@@ -516,7 +543,7 @@ findings:
 summary:
   total_findings: {N}
   by_severity: { critical: {N}, major: {N}, minor: {N} }
-  by_lens: { DEV: {N}, SA: {N}, PO: {N} }
+  by_lens: { QA: {N}, DEV: {N}, SA: {N}, PO: {N} }
   recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
   # Rule: critical ≥ 1                       → BLOCKED
   #       critical = 0, major ≥ 1            → NEEDS_REVISION

package/core/commands/report-bug.md

@@ -1,7 +1,7 @@
 # /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-run-test` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAP` 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.
 

package/core/commands/review-context.md

@@ -267,10 +267,11 @@ vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
 Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
 - **DIMENSIONS** — danh sách các chiều review để fan out
-  (`/refine-prd` → 3 lăng kính; `/review-context` → các P-check hoặc B-check).
+  (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check; `/qc-analyze` → 3 lăng kính quét gap).
 - **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
 - **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
 - **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
+- **VERIFY** *(tuỳ chọn, mặc định `off`)* — `on` chèn **Phase 2.5** (`steps/gap-verify.md`) giữa critic và dedup: mỗi finding phải mở lại tài liệu nguồn tự chứng minh trước khi được giữ. Không truyền → hành vi không đổi.
 
 > **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
 > quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
@@ -389,6 +390,31 @@ Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
 
 ---
 
+## Phase 2.5 — Thẩm định *(chỉ chạy khi `VERIFY = on`)*
+
+**Vì sao có bước này.** Phase 1 và Phase 2 chỉ có **một chiều lực**: fan-out mở rộng bề
+ngang, critic lặp cho tới khi không còn gì mới — cả hai đều hỏi *"còn thiếu gì nữa?"*.
+Không có gì hỏi ngược lại *"cái vừa tìm ra có thật không?"*. Nên quy trình này đẩy **recall**
+lên mà **không có gì kéo precision lại**, và càng lặp critic thì tỉ lệ finding bịa càng cao —
+đúng thứ nó tự sinh ra: khẳng định hành vi tài liệu không nêu, trích evidence sai, hoặc gắn
+nhãn vấn đề cho thứ thực ra là chuyện làm-kỹ-hơn.
+
+Chạy `steps/gap-verify.md` trên `ALL_FINDINGS` với:
+- `FINDINGS` = `ALL_FINDINGS` (sau Phase 2)
+- `EVIDENCE_ROOT` = `{paths.specs_dir}` — hoặc giá trị lệnh gọi chỉ định
+- `VERDICT_FIELD` = trường trạng thái của FINDINGS SCHEMA mà lệnh định nghĩa
+- `RERATE` = `on`
+
+Finding bị `❌ INVALID` / `⚠️ RECLASSIFY` / `🔁 MERGE` **không đi tiếp sang Phase 3** — nhưng
+**KHÔNG bị xoá**: chúng vào file findings với trạng thái đóng + lý do, để người đọc kiểm chứng
+được vì sao chúng bị loại. Ghi lại số liệu verdict cho report.
+
+> **Chạy TRƯỚC Phase 3, không phải sau.** Dedup và giải quyết xung đột là việc tốn suy luận;
+> làm nó trên một tập còn lẫn finding bịa là vừa phí, vừa nguy hiểm — một finding ảo có thể
+> "thắng" một finding thật ở bước giữ-cái-severity-cao-hơn.
+
+---
+
 ## Phase 3 — Dedup, giải quyết xung đột, merge
 
 Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ

package/core/commands/validate-traces.md

@@ -190,6 +190,30 @@ Nhiều cờ scope cùng lúc → **DỪNG**, báo lỗi: chúng loại trừ nh
 
 `--prd`/`--uc` không phân giải được về một package/UC có thật → **DỪNG** và liệt kê ứng viên. **KHÔNG** âm thầm rơi về `all` (chạy toàn bộ khi người ta xin một phần là đốt 30 phút không ai muốn) và **KHÔNG** âm thầm audit rỗng (báo cáo "sạch" trên 0 row).
 
+**Token TRẦN (không mở đầu bằng `--`)** — vd `/validate-traces --reconcile-code LESS-06`:
+
+| Token trần trông như | Xử |
+|---|---|
+| **UC-ID** (`{TICKET}-UC{n}`) | coi là `--uc {token}` |
+| **TICKET-ID** phân giải được về đúng **một** feature-package | coi là `--prd {token}` |
+| không phân giải được, hoặc khớp **nhiều** package | **DỪNG**, liệt kê ứng viên |
+| có **cả** token trần **và** một cờ scope | **DỪNG** — hai nguồn phạm vi, không tự chọn hộ |
+
+Hai hàng đầu **phải in một dòng** nói rõ đã tự suy, để người dùng thấy mình vừa được hiểu thế nào:
+```
+ⓘ Hiểu `{token}` là `--prd {token}` ({domain}/{prd-slug}). Gõ cờ tường minh nếu ý khác.
+```
+
+> **Vì sao không để token trần rơi về `all` (phát hiện 2026-08-27, lượt dùng `--reconcile-code` đầu tiên).**
+> Gate Bước 1 loại mọi token `--` khỏi phần resolve target, và lệnh này **không có target file** — nên
+> token trần trước đây **bị bỏ hoàn toàn** ⇒ `scope` = `all`. Người dùng gõ `--reconcile-code LESS-06`
+> tin rằng đang chạy hẹp một PRD, trong khi lệnh sẽ **GHI vào sổ của cả 20+ PRD**, gồm cả phần của PO
+> khác. Đây đúng điều chính step này cấm hai dòng ở trên — *"KHÔNG âm thầm rơi về `all`"* — chỉ khác là
+> lỗ vào bằng cửa *"không có cờ nào"* thay vì cửa *"cờ không phân giải được"*.
+>
+> Với một lệnh **chỉ đọc** thì đó là đốt thời gian. Với `--reconcile-code` (có GHI) thì đó là ghi ra
+> ngoài phạm vi mà người dùng nghĩ mình đã yêu cầu — hạng nặng hơn hẳn.
+
 Lưu `scope` — mọi step sau dùng nó:
 
 | Step | Hẹp thế nào |
@@ -621,7 +645,7 @@ Không đụng `dev_selftest`/`qc_status` (luật G28 không áp: **không có l
 |---|---|
 | `implemented_by` | tên class/hàm mang `@trace.implements` cho SC đó (nhiều file → nối bằng `,`, đúng khuôn `/generate-code` đang ghi) |
 | `gen_ver` | copy `spec_ver` của **chính row đó** *(không phải version hiện tại của `.feature` — code sinh ra từ bản nào thì `spec_ver` lúc này là bản đó; Step 2 vừa đồng bộ nó)* |
-| `fe_phase` | `integration` nếu file code có wire adapter thật theo §4.5.4 · `ui` nếu chỉ có mock · `—` cho `system`. **Không suy được** → để `—`, đừng đoán |
+| `fe_phase` | **`integrated`** nếu file code có wire adapter thật theo §4.5.4 · `ui` nếu còn `@trace.mock_for`/mock adapter · `—` cho `system`. **Không suy được** → để `—`, đừng đoán. *(Vocabulary chỉ có `ui` \| `integrated` — nhớ hậu tố **-ed**. Dạng không -ed thuộc về cờ `--phase=integration`, không phải cột này.)* |
 | `test_count` · `test_classes` | **CHỈ khi `has_verifies` = true** (Step 2b đã thu). Số test + tên class lấy từ file mang `@trace.verifies`. `has_verifies` = false → **để trống**, tuyệt đối không điền 0-giả hay tên class phỏng đoán |
 
 > ### ⚠️ Luật cứng: KHÔNG set `status`
@@ -654,7 +678,7 @@ Không đụng `dev_selftest`/`qc_status` (luật G28 không áp: **không có l
       {UC-ID}-{platform}.tsv:{dòng}  {sc_id}
         implemented_by ← {ClassName.method}      (từ {file}:{dòng})
         gen_ver        ← {spec_ver}
-        fe_phase       ← {ui | integration | —}
+        fe_phase       ← {ui | integrated | —}
         test_count     ← {n} · test_classes ← {…}   (từ @trace.verifies ở {file})   [hoặc: bỏ trống — không có @trace.verifies]
    ```
    Ghi bù im lặng là ghi bù không kiểm chứng được.

package/core/skills/qc/qa-analyst/DOC_GAP.template.md

@@ -0,0 +1,117 @@
+---
+version: 1.0
+updated: 2026-08-25
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/spec-issue-reporter/DOC_GAPS.template.md
+upstream_sha: c7ca6cfb798c609f18ffe20a38f64f95c76e1919
+---
+
+> **Template DUY NHẤT cho file gap của `/qc-analyze`** *(B9 — hợp nhất 2026-08-25)*.
+> Bản 9 cột cũ đã bỏ: nó thiếu đúng hai thứ PO cần — cột *Giao cho đội* và ô câu hỏi 4 phần.
+> Giữ một bản kém hơn làm mặc định là để người không biết có cờ nhận bản kém.
+>
+> **Một chỗ CỐ Ý khác upstream:** mức nặng nhất dùng từ **`Blocker`**, không phải `Critical`.
+> Lý do: `/qc-run-test` đọc `🔴 Blocker` để đặt *"scenario đang chờ PO"* vào sổ kết quả trace.
+> Đổi từ là đứt liên kết đó. Ba mức còn lại giữ nguyên upstream.
+
+# DOC GAP -- <UC>: <Tên UC>
+
+| Trường | Giá trị |
+|---|---|
+| Feature | `<FEATURE>` |
+| UC | `<UC> — <Tên UC>` |
+| Tài liệu nguồn | `<đường dẫn PRD>` · `<đường dẫn BDD nếu có>` · `<các file inputs/ liên quan>` |
+| Ngày phân tích | `<YYYY-MM-DD>` |
+| Tổng số gap | `<N>` (Blocker: x · High: y · Medium: z · Low: w) |
+| Trạng thái chung | 🔴 Blocked / 🟠 Cần làm rõ / 🟢 Đủ rõ để thiết kế TC |
+
+---
+
+## Tài liệu đầu vào đã đọc để phân tích
+
+> Liệt kê **đầy đủ** mọi file đã đọc để dựng phân tích gap (spec chính + mọi ref-link + transitive 1-hop). Đây là căn cứ độ phủ — mọi file đã mở đều phải có mặt, KHÔNG bỏ sót. Đường dẫn tính từ `{paths.specs_dir}`.
+
+| # | Đường dẫn (từ `{paths.specs_dir}`) | Vai trò | Phiên bản |
+|---|---|---|---|
+| 1 | `<đường dẫn spec chính>` | **Spec chính** | `<vX.Y>` |
+| 2 | `<đường dẫn ref>` | Ref bắt buộc — `<lý do>` | `—` |
+| ... | ... | Transitive 1-hop — `<feature liền kề / dịch vụ tiêu thụ>` | `—` |
+
+**Tổng: `<N>` tài liệu.** Lane API: `<có → liệt kê openapi.yaml/*.dbml/tdd | không có → SKIP, không đọc, không bịa endpoint>` *(chỉ áp khi framework đã nhận trục lane — xem B5)*. Không dùng làm evidence: Change log · Appendix · mục Giả định AI.
+
+---
+
+| ID | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời |
+|---|---|---|---|---|---|---|---|---|---|
+| GAP-<UC>-001 | MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION | Tiêu đề ngắn mô tả vấn đề | **Bối cảnh:** Ngữ cảnh dẫn đến gap này.<br/>**Vấn đề:** Điều gì chưa được spec hoặc mâu thuẫn.<br/>**Tại sao quan trọng:** Hậu quả nếu không làm rõ.<br/>**Gợi ý:** Ai cần làm gì để giải quyết. | `<đường dẫn file spec>` `<TÊN-BR hoặc AC gốc trong PRD, ví dụ FEAT-01-2-UC4-BR11>`: trích nguyên văn | Dev / PO / BA / Design | 🔴 Blocker | | Open | |
+
+---
+
+## Ưu tiên xử lý
+
+| Mức độ | Gap ID |
+|---|---|
+| 🔴 Blocker | GAP-<UC>-00x · ... |
+| 🟠 High | GAP-<UC>-00x · ... |
+| 🟡 Medium | GAP-<UC>-00x · ... |
+| ⚪ Low | GAP-<UC>-00x · ... |
+
+**Cần chốt trước khi viết test case:**
+- GAP-<UC>-00x: <lý do block>
+
+---
+
+## Chú thích (Legend)
+
+### Loại Gap
+
+| Loại | Mô tả |
+|---|---|
+| MISSING | Thông tin, chức năng, quy tắc, hoặc kịch bản chưa được mô tả trong bất kỳ tài liệu nào trong `{paths.specs_dir}`. |
+| AMBIGUOUS | Mô tả mơ hồ, có thể hiểu theo nhiều cách, hoặc thiếu chi tiết để viết kịch bản kiểm thử. |
+| CONTRADICTORY | Hai hoặc nhiều tài liệu trong `{paths.specs_dir}` mô tả cùng một hành vi nhưng mâu thuẫn nhau. |
+| ASSUMPTION | Giả định do nhóm QA tự suy luận từ tài liệu trong `{paths.specs_dir}`, chưa được PO/Dev xác nhận tường minh. |
+
+### Mức độ
+
+| Mức | Ý nghĩa |
+|---|---|
+| 🔴 Blocker | Chặn viết kịch bản kiểm thử hoặc lập trình — không thể tiến hành nếu chưa có câu trả lời. |
+| 🟠 High | Ảnh hưởng đến nhiều kịch bản kiểm thử hoặc logic nghiệp vụ chính — cần giải quyết trước khi viết test case. |
+| 🟡 Medium | Ảnh hưởng đến một số kịch bản cụ thể — cần giải quyết trước sprint kiểm thử. |
+| ⚪ Low | Ít ảnh hưởng — có thể ghi giả định tạm thời và xử lý trong sprint review. |
+
+### Giao cho đội
+
+| Ký hiệu | Đội |
+|---|---|
+| Dev | Đội phát triển (Frontend + Backend) |
+| Architect | Kiến trúc sư hệ thống |
+| PO | Product Owner |
+| BA | Business Analyst |
+| Design | Đội thiết kế UX/UI |
+| Analytics | Nhóm dữ liệu / phân tích |
+
+---
+
+## ⚠️ Checklist bắt buộc trước khi lưu file
+
+Trước khi lưu file gap, kiểm tra **từng hàng** trong bảng gap:
+
+- [ ] **Có section `Tài liệu đầu vào đã đọc để phân tích`** – bảng liệt kê **đầy đủ** mọi file đã đọc (spec chính + ref-link + transitive 1-hop), có đường dẫn `{paths.specs_dir}`, vai trò, phiên bản; ghi tổng số + trạng thái lane API. KHÔNG bỏ sót file nào đã mở.
+- [ ] **10 cột đủ** – đúng thứ tự: `ID | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
+- [ ] **Cột 3 = `Vấn đề cần confirm`** – KHÔNG viết tắt thành `Vấn đề`
+- [ ] **Cột 4 = `Câu hỏi / Lý do cần confirm & Gợi ý`** – bắt buộc có đủ 4 phần, tách bằng `<br/>`:
+  ```
+  **Bối cảnh:** ...<br/>**Vấn đề:** ...<br/>**Tại sao quan trọng:** ...<br/>**Gợi ý:** ...
+  ```
+  Không viết 4 mục liên tiếp trên cùng một dòng.
+- [ ] **Cột 5 = `Trích đoạn tài liệu (Evidence)`** – KHÔNG viết tắt thành `Evidence`; dẫn nguyên văn + đường dẫn file `{paths.specs_dir}`; **dùng PRD source ID** (ví dụ `FEAT-01-2-UC4-BR11`), KHÔNG dùng internal analysis ID (ví dụ `BR-UC4-12`)
+- [ ] **Cột Mức độ** (cột 7) – bắt buộc dùng emoji: `🔴 Blocker` / `🟠 High` / `🟡 Medium` / `⚪ Low`. Không được ghi text thuần.
+- [ ] **Cột Giao cho đội** (cột 6) – dùng: `Dev` / `PO` / `BA` / `Design` / `Architect` / `Analytics` hoặc kết hợp. Nếu thấy "Open" ở đây → đang bị lệch cột.
+- [ ] **Cột Người trả lời = vai trò** (PO / BA / Dev / Design / ...). Nếu thấy "Open" ở đây → đang bị lệch cột.
+- [ ] **Cột Trạng thái** = `Open` / `Resolved` / `Out of Scope` / `Re-scoped → Covered`
+- [ ] **Trạng thái chung** trong metadata có emoji: `🔴 Blocked` / `🟠 Cần làm rõ` / `🟢 Đủ rõ để thiết kế TC`
+- [ ] **Có đủ 3 section cuối**: Ưu tiên xử lý · Chú thích (Legend) với bảng đầy đủ
+- [ ] **KHÔNG có section "Change log"** và **KHÔNG có section "AI Assumptions"**
+- [ ] **Evidence chỉ từ `{paths.specs_dir}`** – không dùng file trong `{paths.qc_dir}` nội bộ (TC_*.md, REQUIREMENT_ANALYSIS*.md, DOC_GAP*.md khác)

package/core/skills/qc/qa-analyst/acceptance-criteria.md

@@ -1,7 +1,9 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/acceptance-criteria.md
+upstream_sha: 516f35cf78102d27aa5639bfb2818274399800c0
 ---
 
 # Acceptance Criteria — Sinh tiêu chí chấp nhận
@@ -52,7 +54,7 @@ Mỗi AC gắn mã trace: chức năng + BR-xx để TC sau này map 1-1.
 ## Output
 
 Ghi vào **mục Acceptance Criteria** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
-(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`):
+(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`):
 
 - Danh sách AC dạng Given/When/Then, có mã trace về chức năng, business rule (BR-xx)
   và scenario chính thức `{UC-ID}-SC{N}` của `.feature`.

package/core/skills/qc/qa-analyst/business-rules.md

@@ -1,7 +1,9 @@
 ---
 version: 1.0
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
+updated: 2026-08-25
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/business-rules.md
+upstream_sha: 0d5f01257c30182d1c98835303640775d360a3da
 ---
 
 # Business Rules — Trích xuất luật nghiệp vụ
@@ -25,6 +27,38 @@ Trích xuất và liệt kê toàn bộ business rule, điều kiện và ràng
 1. Đọc spec đã bóc tách (output của spec-breakdown) hoặc tài liệu gốc.
 2. Quét tìm: điều kiện ("nếu… thì…"), ràng buộc field, giới hạn (min/max, rate limit),
    quy tắc phân quyền, công thức tính, quy tắc trạng thái, default value.
+3. **Checklist ràng buộc field — kiểm tra TẤT CẢ field (kể cả tuỳ chọn / optional):**
+   - [ ] `minlength` / `maxlength` — PRD có nêu không? Nếu không → GAP (MISSING)
+   - [ ] Ký tự được phép — chữ, số, tiếng Việt có dấu, ký tự đặc biệt, khoảng trắng?
+   - [ ] Trim khoảng trắng đầu/cuối — có hay không?
+   - [ ] Format đặc biệt — email, SĐT, ngày tháng, v.v.
+   > ⚠️ **Field tuỳ chọn (optional) vẫn phải kiểm tra đủ 4 mục trên.** "Không bắt buộc nhập" KHÔNG đồng nghĩa với "không có ràng buộc". Đây là nguồn gốc hay bị bỏ sót khi phân tích.
+
+4. **Checklist đặc biệt — hay bị bỏ sót khi đọc BDD/PRD:**
+
+   **a. Routing table — đọc cả 2 chiều:**
+   - [ ] Với MỖI rule "nếu đủ điều kiện → bỏ qua / nếu thiếu → vào": đánh dấu cả 2 nhánh cần test
+   - [ ] Routing table N loại tài khoản × M màn → duyệt từng ô, không bỏ dòng nào
+
+   **b. Liệt kê hết variant:**
+   - [ ] Spec đề cập nhiều provider/platform/giá trị liệt kê (Google/Facebook, Lớp 1-6...)? → ghi từng variant ra
+   - [ ] Với mỗi variant: behavior hoặc content có khác nhau không? Nếu có → đánh dấu cần TC riêng
+
+   **c. Telemetry/event analytics:**
+   - [ ] Liệt kê TẤT CẢ event name được nhắc trong BDD/PRD cho UC này
+   - [ ] Với mỗi event: trigger khác nhau? → cần TC riêng
+   - [ ] Có field nhạy cảm (SĐT, PII) KHÔNG ĐƯỢC vào event? → cần TC verify âm riêng
+
+   **d. Privacy/security assertions âm:**
+   - [ ] Spec có nói "KHÔNG ghi", "KHÔNG hiển thị", "chỉ đọc", "KHÔNG vào event"? → ghi ra, cần TC riêng
+   - [ ] "Read-only + che X/hiện Y" → 2 TC riêng: (1) hiển thị đúng che/hiện, (2) không chỉnh sửa được
+
+   **e. Validation kế thừa từ UC/AC khác:**
+   - [ ] Spec có reference "chuẩn hoá theo ACx", "logic tương tự UCy", "validation như màn Z"? → đọc UC/AC đó
+   - [ ] Liệt kê TẤT CẢ scenario normalization của UC nguồn chưa có trong UC hiện tại
+
+   **f. AC có sub-cases:**
+   - [ ] Mỗi AC dạng "(1)...→...; (2)...→...; (3)...→..." → đếm số sub-cases, mỗi sub-case 1 TC
 
 ---
 
@@ -50,10 +84,10 @@ Với rule có nhiều điều kiện kết hợp → gợi ý dựng **Decision
 ## Output
 
 Ghi vào **mục Business Rules** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
-(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`):
+(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`):
 
 - Bảng business rule có ID (BR-xx) để TC trace ngược về.
 - Gợi ý các rule cần Decision Table / BVA khi sang qa-designer.
 
-Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`
+Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md`
 (loại CONTRADICTORY / AMBIGUOUS, cột "Ảnh hưởng" trỏ BR-xx).

package/core/skills/qc/qa-analyst/data-flow.md

@@ -1,7 +1,9 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/data-flow.md
+upstream_sha: fc0fc3d0f8010e3fb266c16b132eff1b23641a8f
 ---
 
 # Data Flow — Phân tích luồng dữ liệu
@@ -53,7 +55,7 @@ Thể hiện luồng dạng bước tuần tự hoặc sơ đồ text:
 ## Output
 
 Ghi vào **mục Data Flow** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
-(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`):
+(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`):
 
 - Sơ đồ/list luồng dữ liệu cho mỗi kịch bản chính.
 - Danh sách integration point + state change + failure point.
@@ -61,4 +63,4 @@ Ghi vào **mục Data Flow** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.
 - Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho qa-runner.
 
 Chặng nào luồng/hành vi chưa rõ (vd lỗi xử lý ra sao, retry, partial commit) →
-ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md` (loại MISSING / OPEN QUESTION).
+ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md` (loại MISSING / OPEN QUESTION).