@educa-corp/sdd-framework 0.9.0 → 0.9.2

package/core/skills/qc/qa-analyst/exhaustive-gap-scanner.md

@@ -0,0 +1,174 @@
+---
+version: 1.0
+updated: 2026-08-25
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/exhaustive-gap-scanner.md
+upstream_sha: b3f5aa112ec2fb93100d8945a3fa3d5fe904eb26
+port_completeness: partial
+---
+
+# Exhaustive Gap Scanner — 5 chiều quét gap
+
+Năm **lăng kính** để quét gap tài liệu. Mỗi lăng kính chỉ lo phần mình và **mù với các
+lăng kính khác** — đó là điều làm độ phủ cao hơn một lượt đọc tuần tự, nơi phần cuối tài liệu
+luôn bị lướt.
+
+> **Bốn trong năm chiều đang BẬT** ở `/qc-analyze`: `D2` · `D3` · `D4` · `D5`*(thu hẹp)*.
+> Chỉ `D1` tắt. File này khai *nội dung* các chiều; việc *chạy* chúng thuộc
+> `steps/review-fanout.md`.
+
+## Chiều nào đang bật
+
+| Chiều | Trạng thái | Bằng chứng *(kiểm từng câu hỏi — xem `docs/plans/qc-implementation-log.md` §Kiểm chứng 31 câu hỏi)* |
+|---|---|---|
+| `D1` Luật nghiệp vụ | ⏸️ **tắt** | **4/5 câu đã có chỗ hỏi, và hỏi cụ thể hơn** — `business-rules.md` hỏi *"min/max · ký tự cho phép · trim · định dạng"* thay vì *"ngưỡng đã chốt chưa"* |
+| `D2` Xử lý lỗi | ✅ **bật** | **4/6 câu KHÔNG AI HỎI** — không kỹ năng nào chuyên về *"hết số lần thử lại thì đi đâu"* |
+| `D3` Giao diện | ✅ **bật** | **1/8 phủ tốt, 3 hở hẳn** — không ai đối chiếu chữ trên nút giữa các tài liệu |
+| `D4` Dữ liệu & cấu hình | ✅ **bật** | **6/6 câu KHÔNG AI HỎI** — chiều đáng giá nhất |
+| `D5` Đối chiếu chéo | ✅ **bật, THU HẸP** | **2/4 cặp đang hở** — cả hai dính `design-spec/`. Hai cặp còn lại đã có người làm → bỏ. Xem §Phạm vi ở D5 |
+
+> **`D5` từng bị tắt, và đó là quyết định SAI.** Lý do tắt ban đầu — *"trùng nhiều"* — đúng một
+> nửa: nó phủ **bốn** cặp tài liệu, và chỉ **hai** cặp đã có người làm. Hai cặp còn lại
+> (`PRD ↔ design-spec/` và `bdd/ ↔ design-spec/`) **không ai đối chiếu nội dung**.
+>
+> Sai vì suy từ ấn tượng thay vì đếm danh sách. Bảng kiểm chứng 31 câu hỏi trong nhật ký là thứ
+> đáng lẽ phải làm **trước** khi quyết.
+
+> **Chi phí:** bật cả 5 (không thu hẹp) tốn ~5–6 lần token so với không bật. Cấu hình hiện tại —
+> 3 chiều đầy đủ + `D5` thu hẹp — vào khoảng **~3,5 lần**. `D5` rẻ hơn một chiều thường vì nó chỉ
+> so 2 cặp, và `design-spec/` thì trạm QC **đã đọc từ trước**.
+
+## Cố ý KHÔNG port nửa còn lại
+
+Bản upstream tự cài lại toàn bộ cơ chế fan-out bằng tay: một Coordinator kiểm kê tài liệu,
+dựng SPAWN PLAN, gọi song song 5 agent, rồi consolidate + dedup + đánh ID.
+
+Framework **đã có đúng cơ chế đó** ở `steps/review-fanout.md` — và bản của framework còn có
+thêm hai thứ upstream không có: vòng **completeness-critic** lặp tới khi hai vòng liền không
+sinh gì mới, và **agent cap** gom batch khi fan-out quá rộng.
+
+Port cả phần điều phối = nuôi hai bản cài đặt của cùng một thứ, rồi chúng trôi khỏi nhau.
+Nên file này **chỉ giữ phần nội dung** (5 mandate), phần điều phối để `review-fanout` lo.
+
+*Ghi vào `port_completeness: partial` ở frontmatter — khi đồng bộ ngược sau này, đừng hiểu
+phần thiếu là "ta cố ý xoá nội dung".*
+
+---
+
+## Ràng buộc nguồn *(áp cho cả 5 chiều)*
+
+- Chỉ dùng **spec repo** (`{paths.specs_dir}`) làm evidence. KHÔNG dùng artifact nội bộ do
+  chính pipeline sinh ra (`{paths.qc_dir}/**` — test-case, test-plan, file gap khác).
+- **Bỏ qua** section **Change Log** · **Appendix** · **Giả định AI / AI Assumptions** trong mọi
+  tài liệu. Evidence CHỈ lấy từ thân bài: AC · BR · UC · Wireframe · Screen Spec · Scenario.
+- **KHÔNG bịa** endpoint, bảng, field, hay tài liệu không tồn tại.
+
+---
+
+## Năm chiều
+
+Truyền vào `steps/review-fanout.md` làm `DIMENSIONS`. Chiều nào không có tài liệu đầu vào
+tương ứng thì **bỏ hẳn** — không tạo gap rỗng, không nhắc tới nó trong output.
+
+### D1 · Luật nghiệp vụ  *(⏸️ TẮT ở `/qc-analyze` — xem bảng trên)*
+- Logic rẽ nhánh: điều kiện đã đủ chưa? Thiếu nhánh nào?
+- Ngưỡng / ràng buộc: đã chốt số cụ thể hay còn để ngỏ?
+- Ngoại lệ: trường hợp biên nào chưa được xử lý trong spec?
+- Rule mâu thuẫn giữa các tài liệu?
+- Chỗ nào người viết test **buộc phải giả định** vì spec không rõ?
+
+### D2 · Xử lý lỗi  *(✅ bật)*
+- Quá hạn (timeout) → hành vi là gì?
+- Số lần thử lại đã spec chưa? Khoảng cách giữa các lần?
+- Thử lại hết số lần → hệ thống làm gì?
+- Hàng đợi lỗi: ai xử lý? Có cảnh báo cho người vận hành không?
+- Với **từng loại lỗi**: màn nào hiện, người dùng làm được gì tiếp?
+- Khôi phục: người dùng thử lại được không? Luồng đi tiếp hay bị chặn?
+
+### D3 · Giao diện  *(✅ bật — bỏ hẳn nếu không có BDD / design-spec / wireframe)*
+- **Trạng thái màn**: thiếu state nào? (đang tải · rỗng · lỗi · thành công · một phần · vô hiệu)
+- **Chữ & nhãn**: text nút/tiêu đề/thông báo/gợi ý có nhất quán trong cùng tài liệu và **giữa**
+  các tài liệu không?
+- **Điều hướng**: từ mỗi màn, đi tiếp được đâu và quay lại được đâu? Đã spec đủ mọi đường chưa?
+- **Kiểm tra & phản hồi**: rule validate đã spec? Thông báo lỗi/thành công đã có **nội dung
+  cụ thể** chưa?
+- **Trạng thái biên**: màn trống, danh sách rỗng, quá hạn, kết quả 0 — trải nghiệm thế nào?
+- **UI đã bị gỡ**: component/popup/màn còn trong design-spec nhưng PRD/BDD đã bỏ?
+- **Đa nền** *(nếu có)*: hành vi trên các nền/breakpoint có nhất quán không?
+- **Tài nguyên hiển thị**: loại asset (animation/ảnh/video) và tiêu chí hiển thị đã xác định chưa?
+
+### D4 · Dữ liệu & cấu hình  *(✅ bật — bỏ hẳn nếu không có bảng tính điểm / dữ liệu mẫu / cờ tính năng / spec môi trường)*
+- Bảng điểm / rule tính toán / bảng ánh xạ: có **đủ dữ liệu để tự kiểm chứng kết quả tính** không?
+- Dữ liệu mẫu: có ví dụ đủ để dựng môi trường test không?
+- Cấu hình đổi **giữa lúc đang chạy** thì hành vi là gì? Chốt giá trị tại thời điểm nào?
+- Phụ thuộc môi trường: service, hàng đợi, DB cần thiết đã được spec cho môi trường test chưa?
+- Việc dựng dữ liệu có phụ thuộc thứ còn để ngỏ hoặc chưa làm không?
+- Cờ tính năng: cờ nào ảnh hưởng hành vi cần test? Giá trị mặc định ở môi trường test là gì?
+
+### D5 · Đối chiếu chéo tài liệu  *(✅ bật — THU HẸP còn 2 cặp, xem dưới)*
+
+> **Nhiệm vụ của chiều này là PHÁT HIỆN cặp lệch + gắn HƯỚNG thô. KHÔNG tự chốt loại cuối** —
+> việc phân loại và lọc báo-oan do `steps/gap-verify.md` làm (T5 xác định hướng, T3b xác định
+> mâu thuẫn thật). Chiều này chỉ đưa bằng chứng *"X nói khác/thiếu/thừa so với Y"*.
+
+#### PHẠM VI — chỉ hai cặp, không phải bốn
+
+Bản upstream so **mọi cặp** tài liệu trong feature package. Ở framework, hai cặp đã có chỗ khác
+làm — so lại là nhân đôi công việc và PO nhận hai câu hỏi cho một vấn đề.
+
+| Cặp | Ở framework | |
+|---|---|---|
+| **PRD ↔ `design-spec/`** | **không ai so 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 | ✅ **SO** |
+| **`bdd/{platform}/` ↔ `design-spec/`** | không ai | ✅ **SO** |
+| PRD ↔ `bdd/` | `/review-context` **B1** đã làm (AC/BR nào chưa có scenario) | ❌ bỏ |
+| PRD · `bdd/` ↔ `tech-docs/` | `/qc-analyze` §Đối chiếu tài liệu kỹ thuật đã làm (6 mục) | ❌ bỏ |
+
+> **Cả hai cặp SO đều dính `design-spec/`** — tức phần **Designer vẽ**. Đây là 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ó**.
+>
+> `design-spec/` ≠ `tech-docs/`: cái đầu là *giao diện người dùng thấy*, cái sau là *hợp đồng hệ
+> thống*. `tech-docs/` đã được phủ ở §Đối chiếu tài liệu kỹ thuật của `/qc-analyze`.
+
+Trạm QC **đã đọc `design-spec/`** từ trước (nó nằm trong danh sách nguồn). Nên chiều này không
+nạp thêm file nào — chỉ bắt nó **so** thay vì chỉ **đọc**.
+
+#### Bốn hướng lệch
+
+Lấy **PRD làm gốc**, đối chiếu **thân bài** (KHÔNG đọc Change Log):
+
+| Hướng | Nghĩa | Ai xử lý |
+|---|---|---|
+| **THIẾU** *(design-spec < PRD)* | PRD có màn / trạng thái / hành vi mà `design-spec/` **không** mô tả | Designer bổ sung |
+| **THỪA** *(design-spec > PRD)* | `design-spec/` **tự thêm** màn/nút/hành vi mà PRD không định nghĩa | **PO chốt**: giữ (rồi định nghĩa hệ quả vào PRD) hay gỡ |
+| **MÂU THUẪN** | cùng một hành vi/giá trị/chữ nhưng hai tài liệu nói khác nhau | PO + Designer |
+| **LỆCH-REF** | `design-spec/` trích số/tên BR·AC đã đổi nghĩa — mở đúng BR/AC đó trong PRD **hiện tại**: ref không còn, hoặc mang nghĩa khác | PO |
+
+> **THIẾU vs THỪA phải phân biệt đúng** — đây là lỗi framing hay gặp nhất, và hai hướng xử lý
+> **ngược nhau**. Gọi *"thiết kế thiếu"* trong khi thiết kế **thừa** là đặt sai đề bài cho cả PO
+> lẫn Designer: một bên tưởng phải vẽ thêm, một bên đáng lẽ phải quyết giữ hay gỡ.
+
+#### Với cặp `bdd/` ↔ `design-spec/` — soi gì
+
+- Kịch bản test đi qua một **trạng thái màn** mà `design-spec/` không có (`loading`/`error`/`empty`)?
+- Kịch bản test tác động lên một **thành phần giao diện** không có trong Component Inventory?
+- `design-spec/` mô tả một **đường điều hướng** mà không kịch bản nào đi qua?
+
+*(Chiều này chỉ chạy khi feature có `design-spec/`. Feature `system` không có → bỏ hẳn cặp này.)*
+
+---
+
+## Sau khi quét — BẮT BUỘC thẩm định
+
+Fan-out càng rộng thì gap bịa càng nhiều: đây là cơ chế **đẩy recall**, tự nó không có gì
+kéo precision. Chạy `steps/gap-verify.md` trên tập gap trước khi bàn giao — đó là nửa còn lại.
+
+**Hai cách gọi, tuỳ lệnh:**
+
+| Lệnh gọi có | Thẩm định chạy ở đâu |
+|---|---|
+| `VERIFY = on` | tự động ở `review-fanout` Phase 2.5 — dùng khi fan-out là **nguồn gap duy nhất** |
+| `VERIFY = off` | lệnh gọi tự chạy `gap-verify` **sau khi gộp** — dùng khi còn nguồn gap khác |
+
+`/qc-analyze` dùng cách thứ hai: gap đến từ **cả** 4 kỹ năng phân tích **và** fan-out, nên phải
+gộp trước rồi mới thẩm định một lần. Thẩm định hai tập rời thì phép kiểm `T6` (*"hai gap cùng gốc
+thì gộp lại"*) không bắt được trùng lặp chéo nguồn.

package/core/skills/qc/qa-analyst/spec-breakdown.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/spec-breakdown.md
+upstream_sha: 4a5fb9334fef1fdc3ac5e899e0463c643af80dad
 ---
 
 # Spec Breakdown — Bóc tách yêu cầu
@@ -27,7 +29,7 @@ Bóc tách spec/PRD/user story thô thành mô tả yêu cầu có cấu trúc c
    vào phân tích/BR/AC. Với file Confluence/HTML/MHTML: phát hiện qua thẻ `<s>`,
    `<strike>`, `<del>` hoặc style `text-decoration: line-through`.
 3. Xác định: feature name, actor/role, mục tiêu nghiệp vụ, phạm vi (in/out scope).
-4. Đánh dấu phần MƠ HỒ / THIẾU → ghi vào `DOC_GAPS.md` (gap GAP-xx).
+4. Đánh dấu phần MƠ HỒ / THIẾU → ghi vào `DOC_GAP.md` (gap GAP-xx).
 
 ---
 
@@ -37,7 +39,7 @@ Tách yêu cầu thành các khối:
 
 A. TỔNG QUAN: mục tiêu, actor, giá trị nghiệp vụ.
 B. CHỨC NĂNG: list từng chức năng (visible + ẩn + integration point).
-C. INPUT/OUTPUT: mỗi chức năng có input gì, output gì, ràng buộc field.
+C. INPUT/OUTPUT: mỗi chức năng có input gì, output gì, ràng buộc field. Với **mỗi field input** (kể cả tuỳ chọn): kiểm tra đủ `minlength`/`maxlength`, ký tự cho phép, trim, format. Field thiếu bất kỳ mục nào → ghi gap MISSING vào `DOC_GAP.md`.
 D. TRẠNG THÁI & LUỒNG: các state, điều kiện chuyển, happy path + alternate flow.
 E. PHỤ THUỘC: hệ thống/API/module liên quan.
 F. GIẢ ĐỊNH & CÂU HỎI MỞ: điều suy ra được vs điều cần dev/BA xác nhận.
@@ -48,14 +50,14 @@ F. GIẢ ĐỊNH & CÂU HỎI MỞ: điều suy ra được vs điều cần dev
 
 ⚠️ `/qc-analyze` chỉ ghi **ĐÚNG 2 FILE** cho mỗi UC, đặt trong thư mục QC **lộ ra ngoài**
 `{paths.qc_dir}/{UC-ID}/` (mặc định `docs/{UC-ID}/` — KHÔNG để trong `.agent/` ẩn):
-`REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`. KHÔNG tách mỗi bước phân tích thành file riêng.
+`REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`. KHÔNG tách mỗi bước phân tích thành file riêng.
 
 Phần spec-breakdown là **mục đầu tiên** của `REQUIREMENT_ANALYSIS.md`:
 - Bảng chức năng + input/output/constraint
 - Sơ đồ/list luồng chính & phụ
 - Danh sách giả định và câu hỏi mở (đánh dấu rõ điều CHƯA chắc)
 
-Đồng thời ghi mọi khoảng trống phát hiện vào `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`
-(theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`), mỗi gap có ID `GAP-xx`.
+Đồng thời ghi mọi khoảng trống phát hiện vào `{paths.qc_dir}/{UC-ID}/DOC_GAP.md`
+(theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`), mỗi gap có ID `GAP-xx`.
 
 Kết thúc bằng gợi ý: feature đã đủ rõ để chuyển sang `qa-planner` (phân tích rủi ro) chưa.

package/core/skills/qc/qa-analyst/spec-issue-reporter.md

@@ -0,0 +1,100 @@
+---
+version: 1.0
+updated: 2026-08-25
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/spec-issue-reporter.md
+upstream_sha: 5b5c0c886e92b474e0a5a8157ba58a7c3ce4b3f8
+---
+
+# Spec Issue Reporter — gom mọi điểm mơ hồ thành báo cáo gửi PO/BA/Dev
+
+Gom mọi điểm mơ hồ / thiếu / mâu thuẫn phát hiện được trong lúc phân tích thành **một** báo cáo
+có cấu trúc, đủ thông tin để người nhận trả lời được ngay.
+
+> **`/qc-analyze` nạp file này** *(B9 — hợp nhất 2026-08-25)*. Nó là luật viết cho
+> `DOC_GAP.template.md` — template **duy nhất** của file gap. Bản 9 cột cũ đã bỏ.
+>
+> **Một chỗ cố ý khác upstream:** mức nặng nhất dùng `🔴 Blocker`, không phải `Critical` —
+> `/qc-run-test` đọc đúng từ đó để đặt *"scenario đang chờ PO"* vào sổ trace.
+
+## Đầu vào
+
+Mọi dấu `?`, chỗ thiếu mapping, chỗ mâu thuẫn mà các skill phân tích khác đã ghi nhận.
+
+## Đầu ra
+
+> ⛔ **BẮT BUỘC theo template — tự-validate trước khi lưu.** Đây là skill hay xuất **sai
+> template** nhất: tự chế cột, gộp `Trạng thái` với `Câu trả lời`, thiếu `Giao cho đội` /
+> `Người trả lời`, dùng Loại phi chuẩn (`SYNC` / `Drift` / `FEASIBILITY`), quên section
+> *Ưu tiên xử lý* + *Chú thích*.
+>
+> TRƯỚC khi lưu: mở `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`, chạy hết
+> **"⚠️ Checklist bắt buộc trước khi lưu file"** ở cuối template, sửa cho khớp 100%.
+
+Một file gap gồm:
+
+1. **Section `Tài liệu đầu vào đã đọc để phân tích`** — BẮT BUỘC, đặt ngay sau metadata,
+   **trước** bảng gap. Bảng liệt kê **đầy đủ** mọi file đã đọc (spec chính + mọi ref-link +
+   transitive 1-hop): `# | Đường dẫn | Vai trò | Phiên bản`, kèm tổng số.
+   KHÔNG bỏ sót file nào đã 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"*.
+2. **Bảng gap 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`
+
+## Quy tắc
+
+- **Evidence bắt buộc** — dẫn **nguyên văn** in nghiêng + tham chiếu vị trí cụ thể
+  (`〔file §section〕`). Dùng ✕ khi mâu thuẫn giữa hai chỗ. Không phán đoán chủ quan.
+- **Cột 4 phải đủ bốn mục**, tách bằng `<br/>` thành từng dòng riêng trong cell:
+  ```
+  **Bối cảnh:** …<br/>**Vấn đề:** …<br/>**Tại sao quan trọng:** …<br/>**Gợi ý:** …
+  ```
+  Không viết bốn mục liên tiếp trên một dòng. Ngôn ngữ dễ hiểu cho PO/Design/Dev.
+  *"Tại sao quan trọng"* là thứ cho phép người nhận **xếp ưu tiên**; *"Gợi ý"* là thứ cho phép
+  họ **trả lời nhanh** thay vì nghĩ lại từ đầu.
+- **Tham chiếu BR/AC dùng ID GỐC trong PRD** (vd `FT-001-UC4-BR11`), **không** dùng ID nội bộ
+  do bước phân tích tự đánh số lại (vd `BR-UC4-12`). Hai hệ ID khác nhau; trộn vào là người
+  đọc không tra ngược được về PRD.
+- **Mức độ bắt buộc có emoji**: `🔴 Blocker` · `🟠 High` · `🟡 Medium` · `⚪ Low`.
+- **Pipe trong cell**: escape thành `\|` (vd `{a\|b\|c}`), nếu không sẽ vỡ bảng.
+- **Thêm hàng vào bảng đã có**: nối **ngay liền sau hàng cuối**, TUYỆT ĐỐI không chèn dòng
+  trắng giữa các hàng — dòng trắng làm Markdown tách thành hai bảng riêng và các gap mới
+  **không render** trong bảng chính. Thêm xong cập nhật luôn *Tổng số gap* ở header và bảng
+  *Ưu tiên xử lý*.
+- **KHÔNG thêm section "Change log"** và **KHÔNG thêm section "AI Assumptions"** — mọi giả định
+  AI tự suy là gap loại `ASSUMPTION` trong bảng, không tách thành section riêng.
+
+## Trạng thái hợp lệ
+
+`Open` · `Resolved` · `Out of Scope` · `Re-scoped → Covered`
+
+**Khi một trường hợp đã đánh dấu `Out of Scope` được yêu cầu viết test:**
+
+1. Kiểm PRD xem có ghi chú thay đổi phạm vi không — một change request có thể **dời trách
+   nhiệm kiểm tra** từ UC này sang UC khác.
+2. Có ghi chú rõ ràng → đổi trạng thái `Out of Scope` → `Re-scoped → Covered`, ghi test-case
+   mới vào cột *Câu trả lời*.
+3. Không tìm thấy ghi chú nhưng QC vẫn yêu cầu → **vẫn viết test** (QC chốt phạm vi), đồng
+   thời ghi chú lại để truy vết.
+
+## Xác định IN-SCOPE vs NGOÀI PHẠM VI — căn cứ SPEC, không dùng artifact tự sinh
+
+> ⚠️ **Nguồn quyết định phạm vi là SPEC, không phải tài liệu do chính pipeline QC sinh ra.**
+
+- Khi phán một hạng mục là in-scope hay ngoài phạm vi, phải trích **spec authority**: mục
+  *Scope/Phạm vi* của PRD, `@trace.platform` của file `.feature`, hoặc design-spec nêu rõ nền
+  tảng áp dụng.
+  **TUYỆT ĐỐI KHÔNG** lấy `TEST_PLAN.md` / `*.Test.md` dưới `{paths.qc_dir}` làm căn cứ — chúng
+  do chính pipeline này sinh ra, nên dùng chúng là **vòng lặp**: lấy *hệ quả* của phạm vi làm
+  *nguồn* của phạm vi.
+- **Bố cục file gap:** chỉ gap **in-scope** nằm trong bảng chính và tính vào *Ưu tiên xử lý*
+  (đây là gap sẽ chặn hoặc đẻ ra test). Gap **thật nhưng ngoài phạm vi** (thuộc feature khác)
+  và gap **lệch đồng bộ tài liệu** → gom vào section **"Ghi chú ngoài phạm vi"** riêng, không
+  trộn vào bảng chính, không tính ưu tiên. **Giữ audit trail, đừng xoá.**
+- Phân vân in hay out → mặc định **giữ in-scope + hỏi lại**. Loại nhầm ra ngoài phạm vi làm
+  **mất coverage trong im lặng** — nguy hiểm hơn hẳn việc thừa một gap ngoài lề.
+
+## Sau khi sinh file gap — BẮT BUỘC thẩm định
+
+Chạy `steps/gap-verify.md` trên tập gap vừa sinh trước khi bàn giao. Skill này **tìm** gap;
+nó không có cơ chế nào tự phát hiện gap mình vừa bịa ra. Xem `gap-verify` §"Nguyên tắc tối thượng".

package/core/skills/qc/qa-designer/e2e/journey.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — E2E Journey
@@ -18,7 +18,7 @@ Skill **tự chứa** để viết TC end-to-end: hành trình đầu→cuối x
 ---
 
 ## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAPS.md)`.
+- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
 - **Test Data** dạng list (tài khoản/role, dữ liệu lớp/buổi…) · **Steps** `[Action]`/`[Verify]` xuyên các màn ·
   **Expected** 1 bullet = chuỗi verify point (tạo thành công, mã đúng, định tuyến đúng, đồng bộ đúng, hiển thị danh sách).
 - ID journey `E2E-<FEATURE>-NN` · cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.

package/core/skills/qc/qa-designer/exploratory/charter.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Gen Test Charter — Exploratory

package/core/skills/qc/qa-designer/exploratory/explore-to-functional.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Explore-to-Functional Pipeline

package/core/skills/qc/qa-designer/functional/api.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — Functional API (không qua UI)
@@ -22,7 +22,7 @@ Chỉ cần load file này.
 - 1 file/feature · mỗi TC **1 concept** · metadata **list** (không bảng/emoji): Title · Feature ·
   Priority(P0/P1/P2) · Status(Draft) · Author(AI) · Tags · Trace · 🚫 Block(nếu có).
 - **Trace:** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)`; không có BR → `⚠️ Chưa có Business Rule`.
-- **🚫 Block:** TC phụ thuộc gap vẫn viết đủ + `[GAP-xx](DOC_GAPS.md) — lý do`.
+- **🚫 Block:** TC phụ thuộc gap vẫn viết đủ + `[GAP-xx](DOC_GAP.md) — lý do`.
 - **Test Data:** dạng **list** (request cụ thể: method/path/headers/body). **Steps:** `[Action]`/`[Verify]`.
   **Expected:** 1 bullet nêu rõ **status code + field response cần chốt** (không ✅/❌).
 - Cuối file: **Trace matrix** (BR↔TC, ⚠️ TC thiếu BR) + **bảng TC bị block** · bỏ nội dung gạch ngang.

package/core/skills/qc/qa-designer/functional/gui-feature.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — Functional GUI Feature (đa màn hình)
@@ -22,7 +22,7 @@ Skill **tự chứa** để viết TC functional cho feature có luồng span
 - 1 file/feature · mỗi TC **1 concept** · metadata **list** (không bảng/emoji): Title · Feature ·
   Priority(P0/P1/P2) · Status(Draft) · Author(AI) · Tags · Trace · 🚫 Block(nếu có).
 - **Trace:** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)`; không có BR → `⚠️ Chưa có Business Rule`.
-- **🚫 Block:** TC phụ thuộc gap vẫn viết đủ + `[GAP-xx](DOC_GAPS.md) — lý do`.
+- **🚫 Block:** TC phụ thuộc gap vẫn viết đủ + `[GAP-xx](DOC_GAP.md) — lý do`.
 - **Test Data:** dạng **list** (không bảng). **Steps:** `[Action]`/`[Verify]`, không `*Expected:*`/bước. **Expected:** 1 bullet cụ thể.
 - Cuối file: **Trace matrix** (BR↔TC, ⚠️ TC thiếu BR) + **bảng TC bị block** · không `#### Python Test Mapping` · bỏ nội dung gạch ngang.
 

package/core/skills/qc/qa-designer/functional/gui-screen.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — Functional GUI Screen (1 màn hình)
@@ -22,7 +22,7 @@ Skill **tự chứa** để viết TC functional cho 1 màn hình đơn lẻ (we
 - 1 file/feature · mỗi TC **1 concept** · metadata **list** (mỗi trường 1 dòng, không bảng/emoji):
   Title · Feature · Priority(P0/P1/P2) · Status(Draft) · Author(AI) · Tags · Trace · 🚫 Block(nếu có).
 - **Trace:** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)`; TC không có BR → `⚠️ Chưa có Business Rule`.
-- **🚫 Block:** TC phụ thuộc gap **vẫn viết đủ** + `[GAP-xx](DOC_GAPS.md) — lý do`; chưa chạy tới khi gap Answered.
+- **🚫 Block:** TC phụ thuộc gap **vẫn viết đủ** + `[GAP-xx](DOC_GAP.md) — lý do`; chưa chạy tới khi gap Answered.
 - **Test Data:** dạng **list** (`- **Trường:** giá trị`), không bảng.
 - **Test Steps:** `**[Action]**` / `**[Verify]**`, KHÔNG `- *Expected:*` sau bước. **Expected:** 1 bullet cụ thể (không ✅/❌).
 - Phân nhóm GUI/Functional · cuối file: **Trace matrix** (BR↔TC, ⚠️ TC thiếu BR) + **bảng TC bị block** · KHÔNG `#### Python Test Mapping` · bỏ nội dung gạch ngang.

package/core/skills/qc/qa-designer/integration/api.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — Integration API
@@ -20,7 +20,7 @@ verify luồng dữ liệu & contract giữa các thành phần. Chỉ cần loa
 ---
 
 ## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAPS.md)` (TC chặn vẫn viết đủ).
+- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)` (TC chặn vẫn viết đủ).
 - **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet nêu rõ chặng verify (response/bản ghi/event).
 - Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
 

package/core/skills/qc/qa-designer/integration/db.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — Integration DB
@@ -18,7 +18,7 @@ insert/update/soft-delete đúng giá trị, side-effect, toàn vẹn. Chỉ c
 ---
 
 ## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAPS.md)`.
+- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
 - **Test Data** dạng list (giá trị input) · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet nêu rõ **bảng.cột = giá trị**.
 - Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
 

package/core/skills/qc/qa-designer/integration/gui.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — Integration GUI ↔ Backend
@@ -19,7 +19,7 @@ lỗi từ server, đồng bộ trạng thái hai chiều. Chỉ cần load file
 ---
 
 ## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAPS.md)`.
+- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
 - **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet (API liên quan + biểu hiện UI kỳ vọng).
 - Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
 

package/core/skills/qc/qa-designer/integration/kafka.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — Integration Kafka (Message/Event)
@@ -18,7 +18,7 @@ Skill **tự chứa** để viết TC tích hợp qua Kafka: producer phát even
 ---
 
 ## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAPS.md)`.
+- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
 - **Test Data** dạng list (payload) · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet nêu **topic + field payload / hành vi consumer**.
 - Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
 

package/core/skills/qc/qa-designer/non-functional.md

@@ -1,7 +1,7 @@
 ---
 version: 1.0
 updated: 2026-06-11
-ported_from: ai-automation-qc-base
+ported_from: ui-automation-testing
 ---
 
 # Test Case — Non-Functional
@@ -18,7 +18,7 @@ Trọng tâm "hệ thống hoạt động TỐT thế nào". Chỉ cần load fi
 ---
 
 ## Format file TC (bắt buộc)
-- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAPS.md)`.
+- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAP.md)`.
 - **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet có **ngưỡng đo cụ thể** (không "nhanh/ổn định").
 - Cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
 

package/core/skills/qc/qa-planner/risk-model.md

@@ -0,0 +1,106 @@
+---
+version: 1.0
+updated: 2026-08-25
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-analyst/risk-acceptance-analyzer.md
+upstream_sha: 5eca5091acd30e063d20b63f12b04e2d1c78ac83
+port_completeness: partial
+---
+
+# Risk Model — cách tính mức rủi ro và dùng nó để chia độ sâu test
+
+`test-plan.md` có **khung** bảng rủi ro (`§6`) nhưng không có **cách điền**. File này là cách điền.
+
+Nạp cùng `test-plan.md` khi lập plan. Đầu ra không phải file riêng — nó điền vào `§6 Rủi ro`
+và `§5 Tiêu chí Vào/Ra` của `TEST_PLAN.md`.
+
+## Cố ý chỉ port một phần
+
+Bản upstream (`risk-acceptance-analyzer`) có 5 phase. Ba phase bị **cố ý bỏ** vì trạm 1 đã làm rồi:
+
+| Phase upstream | Vì sao không port |
+|---|---|
+| Test Conditions | trùng vai với `qa-analyst/spec-breakdown` + `business-rules` (trạm 1) |
+| Ambiguity & Gap | trùng vai với `DOC_GAP` + `steps/gap-verify.md` (trạm 1) |
+| Acceptance Criteria | trùng vai với `qa-analyst/acceptance-criteria` (trạm 1) |
+
+Chỉ port **Phase 3 (Risk Register)** và **Phase 5 (Ưu tiên + Entry/Exit)** — hai phần trạm 2 sở hữu.
+
+*Ghi `port_completeness: partial` ở frontmatter — lần đồng bộ sau đừng hiểu phần thiếu là
+"ta cố ý xoá nội dung".*
+
+---
+
+## Bước 1 — Liệt kê rủi ro sản phẩm
+
+Bảy nguồn rủi ro. Quét từng cái, không bỏ nguồn nào chỉ vì "feature này chắc không có":
+
+| # | Nguồn | Dấu hiệu trong PRD/BR |
+|---|---|---|
+| 1 | **Logic phức tạp** | nhiều điều kiện AND/OR lồng nhau, bảng định tuyến, công thức tính |
+| 2 | **Tiền / thanh toán** | giao dịch, hoàn tiền, mã giảm giá, hạn mức |
+| 3 | **Dữ liệu nhạy cảm** | thông tin cá nhân, số điện thoại, thông tin định danh |
+| 4 | **Tích hợp nhiều phần** | gọi dịch vụ khác, hàng đợi sự kiện, đồng bộ dữ liệu |
+| 5 | **Code mới hoặc sửa nhiều** | feature xây mới, hoặc vùng vừa refactor |
+| 6 | **Lịch sử lỗi cao** | vùng đã từng có bug — tra `{paths.bug_reports_dir}` cho UC/feature này |
+| 7 | **Ảnh hưởng nhiều người dùng** | luồng chính mọi người đều đi qua, màn đăng nhập, trang chủ |
+
+> Nguồn 6 là nguồn duy nhất **tra được bằng dữ liệu thật** trong framework — sổ bug nằm ở
+> `{paths.bug_reports_dir}`. Đừng đoán "vùng này chắc ổn"; mở ra đếm.
+
+## Bước 2 — Chấm mức cho từng rủi ro
+
+Hai chiều, mỗi chiều ba mức:
+
+- **Khả năng xảy ra** — Cao / Trung bình / Thấp
+- **Mức thiệt hại nếu xảy ra** — Cao / Trung bình / Thấp
+
+Nhân lại ra **P0 → P3**:
+
+| Khả năng \ Thiệt hại | Cao | Trung bình | Thấp |
+|---|:---:|:---:|:---:|
+| **Cao** | **P0** | **P1** | P2 |
+| **Trung bình** | **P1** | P2 | P3 |
+| **Thấp** | P2 | P3 | P3 |
+
+> **Chấm hai chiều riêng rồi mới nhân** — đừng chấm thẳng ra P0/P1 theo cảm tính. Hai chiều
+> tách nhau là chỗ tranh luận trở nên cụ thể: *"cái này thiệt hại cao nhưng khả năng thấp"*
+> là một câu nói được, còn *"cái này P1"* thì không cãi được, chỉ tin hoặc không tin.
+
+## Bước 3 — Dùng mức rủi ro để chia **độ sâu** test
+
+Đây là chỗ bảng rủi ro trả lại giá trị. Không có bước này thì nó chỉ là một bảng trang trí.
+
+| Mức | Test sâu tới đâu | Tự động hoá |
+|---|---|---|
+| **P0** | nhiều kỹ thuật cùng lúc: phân lớp tương đương + giá trị biên + bảng quyết định + chuyển trạng thái | ✅ ưu tiên — cả kiểm thử hồi quy |
+| **P1** | hai kỹ thuật trở lên, phủ đủ nhánh chính + nhánh lỗi | ✅ nếu ổn định |
+| **P2** | một kỹ thuật, phủ luồng thuận + một nhánh lỗi tiêu biểu | tuỳ |
+| **P3** | danh sách kiểm tay, không cần test case đầy đủ | ❌ |
+
+**Thứ tự chạy:** rủi ro cao **và** phụ thuộc thấp làm trước — không phải "P0 làm hết rồi mới tới P1".
+Một P0 đang chờ gap chặn thì không chạy được; làm P1 sẵn sàng trước là đúng.
+
+**Tháp test:** end-to-end tự động **chỉ** cho luồng P0/P1 trọng yếu. E2E cho P2/P3 là đắt và giòn —
+tiền không đáng.
+
+## Bước 4 — Điền Entry / Exit theo rủi ro
+
+`test-plan.md §5` đã có khung. Rủi ro làm nó cụ thể hơn:
+
+- **Entry** — mọi gap 🔴 chặn đã `Answered`; **và** mọi rủi ro P0 đã có ít nhất một cách giảm thiểu ghi rõ.
+- **Exit** — phủ 100% vùng P0 · không còn defect mở ở vùng P0/P1 · tỉ lệ pass đạt ngưỡng đã khai.
+
+> **Rủi ro P0 không có cách giảm thiểu = chưa đủ điều kiện bắt đầu.** Ghi ra một rủi ro rồi
+> không nói làm gì với nó là ghi cho có.
+
+---
+
+## Điền vào `TEST_PLAN.md §6`
+
+| Rủi ro | Nguồn (1–7) | Khả năng | Thiệt hại | Mức | Giảm thiểu (loại test + kỹ thuật) |
+|---|---|---|---|---|---|
+| … | 2 · tiền | Cao | Cao | **P0** | functional/api + giá trị biên; e2e luồng thanh toán |
+
+Mỗi dòng rủi ro phải **trỏ được về BR-xx hoặc GAP-xx** đã có ở `REQUIREMENT_ANALYSIS.md` /
+`DOC_GAP.md` — rủi ro không neo vào yêu cầu nào là rủi ro tự nghĩ ra.