@educa-corp/sdd-framework 0.9.3 → 0.9.5

package/core/skills/qc/qa-designer/shared/skill-decision-tree.md

@@ -0,0 +1,93 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/skill-decision-tree.md
+upstream_sha: 57125f0c21512f2abcc55d00420e92c84c95fc8f
+---
+# Cây Quyết Định — Chọn Skill Đúng
+
+> Đọc file này khi không chắc nên dùng skill nào. Trả lời lần lượt các câu hỏi từ trên xuống.
+
+---
+
+## Bước 1 — Đối tượng test là gì?
+
+```
+Đối tượng test
+├── Hiển thị / validation / state của 1 screen       → [A] Xét tiếp Bước 2 (UI vs Integration GUI)
+├── User thực hiện workflow có mục tiêu nghiệp vụ    → [B] Xét tiếp Bước 3 (E2E vs Integration)
+├── 1 API endpoint (request/response/mã lỗi)         → api-testcase-designer
+├── NFR (performance/security/a11y/i18n)              → nfr-testcase-designer
+└── Luồng đa màn nằm trong 1 feature, không xuyên hệ thống → ui-testcase-designer (gui-feature)
+```
+
+---
+
+## Bước 2 — UI vs Integration GUI
+
+**Câu hỏi:** TC này có thể chạy với dữ liệu tĩnh/mock mà vẫn valid không?
+
+| Câu trả lời | Skill | Lý do (ISTQB) |
+|---|---|---|
+| **Có** — mock data đủ để verify | `ui-testcase-designer` | Component testing: verify UI behavior độc lập với backend |
+| **Không** — phải có API thật/stub mới verify được | `integration/gui` trong `integration-testcase-designer` | Integration testing: verify contract UI layer ↔ API layer |
+
+**Ví dụ phân biệt:**
+
+| Tình huống | Skill | Lý do |
+|---|---|---|
+| Dropdown có placeholder, đóng khi click ngoài | UI | Behavior tĩnh, không cần API |
+| Dropdown hiển thị đúng N item từ API response | Integration GUI | Verify data flow API → render |
+| Form validate email format | UI | Client-side validation, không cần server |
+| Form validate email "đã tồn tại" qua API | Integration GUI | Server-side validation = API call |
+| Bảng danh sách render đúng số cột, format | UI | Layout/display |
+| Bảng danh sách phản ánh đúng dữ liệu từ GET /list | Integration GUI | API data → UI sync |
+
+---
+
+## Bước 3 — E2E vs Integration
+
+**Câu hỏi:** Chủ thể của test là ai/cái gì?
+
+| Câu trả lời | Skill | Lý do (ISTQB) |
+|---|---|---|
+| **User** hoàn thành 1 mục tiêu nghiệp vụ từ đầu đến cuối | `e2e-testcase-designer` | System testing: user journey perspective |
+| **Module A ↔ Module B** trao đổi dữ liệu/contract đúng | `integration-testcase-designer` | Integration testing: system contract perspective |
+
+**Câu hỏi phụ để phân biệt rõ hơn:**
+
+> "Nếu tôi xóa hết step UI và chỉ test phần trao đổi dữ liệu, TC vẫn còn ý nghĩa không?"
+> - Có → Integration (bản chất là test handshake, UI chỉ là trigger)
+> - Không → E2E (user journey là trọng tâm, không thể tách ra)
+
+**Ví dụ phân biệt:**
+
+| Tình huống | Skill | Lý do |
+|---|---|---|
+| User đăng ký → nhận email → login → vào dashboard | E2E | User journey hoàn chỉnh, verify goal đạt được |
+| User tạo lớp học → lớp hiện trong danh sách | E2E | End-to-end từ action đến kết quả nhìn thấy |
+| Frontend gọi POST /enroll → DB ghi đúng bản ghi | Integration | Module contract: API ↔ DB, không phụ thuộc UI |
+| Service A gửi event Kafka → Service B xử lý đúng | Integration | System-to-system, không liên quan user |
+| Tạo đơn hàng qua UI → kiểm tra DB có bản ghi | Cả hai? | Nếu mục tiêu là "user đặt hàng thành công" → E2E; nếu mục tiêu là "POST /order ghi DB đúng" → Integration |
+
+---
+
+## Tóm tắt nhanh
+
+```
+Có API thật mới verify được?
+  └─ Không → UI
+  └─ Có, verify data flow 1 điểm → Integration GUI
+  └─ Có, user journey đầu-cuối → E2E
+  └─ Có, handshake 2 module/hệ thống → Integration
+```
+
+---
+
+## Quy tắc ưu tiên khi vẫn còn mơ hồ
+
+1. **UI ưu tiên nhỏ nhất:** viết TC nhỏ nhất có thể verify 1 behavior cụ thể.
+2. **Integration GUI** khi có server-side behavior: validation, lookup, list.
+3. **E2E chỉ cho P0/P1 critical path** (ISTQB Test Pyramid: E2E ít nhất, UI/Unit nhiều nhất).
+4. **Integration** khi tách được khỏi UI và vẫn có giá trị test.

package/core/skills/qc/qa-designer/shared/tc-metadata-format.md

@@ -0,0 +1,243 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/tc-metadata-format.md
+upstream_sha: a31d66a7a8dab19cf821c9102a88282b09e16cb9
+---
+# TC Metadata Format (Chuẩn chung)
+
+## ⚠️ Nguyên tắc format file TC (BẮT BUỘC — QC yêu cầu)
+
+- **TOÀN BỘ file TC viết dạng LIST — KHÔNG dùng bảng Markdown** (không ký tự `|`). Áp dụng cho: Test Steps, Tổng hợp TC, Trace Matrix, TC bị Block, metadata đầu file. *(Chỉ file TC output; tài liệu skill này giữ bảng minh hoạ bình thường.)*
+- **Gom nhóm theo LOẠI test** (không theo luồng nghiệp vụ): thứ tự cố định **GUI → Validation → Functional → Integration → NFR → E2E** (xem §Phân nhóm).
+- Khi tái cấu trúc/đảo nhóm: **GIỮ NGUYÊN mã `TC_<FEATURE>_NNN`**, chỉ đổi vị trí (mã không cần liền mạch theo thứ tự đọc).
+- **App/Web là 2 bộ TC ĐỘC LẬP, mỗi nền chạy FULL business-logic** — trùng logic giữa 2 nền là chủ đích, KHÔNG tính duplicate defect; mỗi file phải độc lập đạt full coverage — mỗi nền một thư mục riêng (`{qc_dir}/{TICKET-ID}/web/` vs `/app/`), và sổ trace cũng tách theo nền.
+
+## ⚠️ Quy tắc "1 bullet Expected = 1 TC ĐỘC LẬP" (BẮT BUỘC — QC yêu cầu, testcase ATOMIC)
+
+> **Cập nhật 2026-07-09 (QC chốt — ĐẢO rule cũ):** trước đây cho GỘP nhiều checkpoint cùng-1-hành-vi vào 1 Expected nhiều bullet. **Nay: mỗi Expected chỉ ĐÚNG 1 bullet; mọi TC nhiều bullet phải TÁCH thành nhiều TC độc lập.** KHÔNG còn ngoại lệ "gộp checkpoint".
+
+- **Test Steps chỉ chứa hành động.** Mỗi bước là `[Action]` hoặc `[Verify]` THUẦN — **KHÔNG gắn `→ [Expected] ...` ở cuối bước.** Oracle nằm ở `#### Expected Result`.
+- **Atomic = 1 OUTCOME, không chỉ đếm "1 bullet".** Mỗi TC đúng 1 `#### Expected Result` với ĐÚNG 1 bullet. Bullet compound (`A, B`) **chỉ OK khi cùng 1 outcome** (vd "chỉ 5 slide: đúng 5 dots; slide 6,7 không xuất hiện" · "form hiển thị đủ 3 trường"). **Bullet nối bằng `;` kiểu "khẳng-định + phủ-định/outcome độc lập"** (vd "Có lối Đăng nhập**;** KHÔNG có OTP" · "sang routing**;** không OTP") **= 2 outcome → TÁCH tiếp** — soi nhanh khi review: grep bullet chứa `;` + `không/KHÔNG`. Tuyệt đối KHÔNG ≥2 bullet trong 1 Expected.
+- **Nhiều điểm-kiểm / outcome → TÁCH thành nhiều TC ĐỘC LẬP, mỗi TC 1 bullet.** Áp cho MỌI trường hợp: outcome độc lập (BVA/Decision-rule/tiền đề khác) LẪN nhiều checkpoint của **cùng 1 hành vi** (VD "màn hiển thị đủ ô A + nút B + lối C" → **3 TC**, không còn gộp).
+- **⚠️ Chế độ ATOMIC TỐI ĐA (QC chốt 2026-07-14 — GIẢI mâu thuẫn 2 gạch trên):** khi user YÊU CẦU THẲNG "tách nhỏ nhất", **completeness list nổ từng thành phần** (kể cả "form đủ 3 trường" → **3 TC**; thẻ khung giờ đủ 5 field → 5 TC) — tức áp gạch "→ 3 TC", KHÔNG dùng ngoại lệ "compound cùng-1-outcome" cho completeness. **NHƯNG GIỮ 1 TC** cho: *predicate đa-điều-kiện định-nghĩa-1-khái-niệm* ("chưa bắt đầu & ≥10' = slot-hợp-lệ"), *ngưỡng* ("≥44pt·48dp", "WCAG AA ≥4.5:1"), *exclusivity* chọn-một, *qualifier* ("không chỉ bằng màu"). Trước khi thực thi: **hỏi 1 câu chốt ranh giới completeness** (quy mô ~95 vs ~130 TC) + dựng **bản đồ tách** (số mảnh/TC cha) rồi mới ghi. Chi tiết + thủ tục verify: `precision-rules.md §2.1`. (Mặc định lúc SINH MỚI vẫn cho compound cùng-1-outcome; chế độ tối đa chỉ khi user yêu cầu.)
+- **Mỗi TC tách là testcase ĐỘC LẬP** — KHÔNG phải "con", KHÔNG đánh `(1/N)`, KHÔNG suffix `001a/001b`:
+  - **Tiêu đề mô tả riêng** self-contained (ngữ cảnh màn/hành vi + điểm được kiểm), heading khớp `**Title:**`.
+  - **Giữ FULL Test Steps** — lặp đủ bước để tới trạng thái assert (KHÔNG cắt bước theo từng bullet).
+  - Metadata (Feature/Module/Priority/Status/Tags/Trace) + Preconditions **copy nguyên** từ TC gốc.
+- **`#### Teardown` là SECTION riêng, KHÔNG phải bullet Expected.** Khi tách bằng script: parse `#### Teardown` riêng — **đừng nuốt bullet teardown vào `#### Expected Result`** (bug đã gặp → sinh "TC teardown giả" có Expected="Xoá dữ liệu test…", steps↔expected mâu thuẫn, không pass/fail được). Mỗi TC tách **TẠO bản ghi DB** (register/tạo tài khoản mới) phải giữ `#### Teardown` riêng; flow **login trên seed** không cần.
+- **Renumber TUẦN TỰ toàn dải** khi tách. Đổi số cascade → **đồng bộ NGAY**: `Mục lục` (range mỗi nhóm) · `Tổng hợp` (count + priority) · note `· N TC` mỗi Nhóm · `Trace Matrix` (**expand range** cũ thành list id mới) · `TC bị Block` (map id cũ → các id con). Dùng script xác định + backup trước–sau (agent ghi file lớn hay lỗi âm thầm — xem gạch cuối mục này).
+- **Assertion loại-trừ (KHÔNG hiển thị / KHÔNG xảy ra) là oracle THẬT** → mỗi cái là 1 bullet = 1 TC riêng. Khi tách bằng script cơ học, **kiểm lại không đánh rơi** (đối chiếu backup).
+- **Bullet metadata KHÔNG phải outcome.** `- Mobile: \`@pytest.mark.flaky(...)\`` lọt trong Expected là **marker** → loại khỏi phép đếm outcome, **dời ra meta** (`- **Chạy (mobile):** …`). Đếm nhầm marker là "bullet thứ 2" sẽ kết luận SAI rằng file cần tách. Reviewer cờ `[MARKER_IN_EXPECTED]`.
+- **⚠️ Trước khi viết script tách/renumber — biết 5 bẫy này trước.** 5 bug **không throw exception** (script "chạy xong" rồi ghi file hỏng):
+  1. **Double-remap**: transformer vừa *sinh* ID vừa *remap* ID → regex khớp luôn **heading vừa sinh** → ID trùng. **Chỉ remap `preamble` + `tail`, KHÔNG remap phần vừa sinh.**
+  2. **2 namespace ID**: liệt kê namespace TRƯỚC khi rename (vd FEAT-01-2: nội bộ `TC_FEAT-01-2_{APP,WEB}_NNN` remap ĐƯỢC · **master** `TC_NNN`/`TC_FEAT-01-2_NNN` ở BLOCKED/TODO **KHÔNG remap**). Verify: `diff` tập master-ID backup↔new.
+  3. **Replace-section làm rơi dòng chưa mô hình hoá** (dòng `>` note trong Expected). Giữ trailing note.
+  4. **Tiêu đề cha ≠ prefix con**: auto-title `"<heading cha> — <bullet>"` nhân đôi khi heading cha liệt kê cả 2 vế.
+  5. **Invariant phải gồm DIFF ĐỊNH DẠNG**, không chỉ đếm: liên tục ID · 0 trùng · 1 bullet/TC · oracle lossless (diff vs backup) · 0 dead-ref · **0 dòng-trống-kép/nhiễu whitespace** · master-ID không đổi.
+- **Có file ĐÃ atomic sẵn** — phân tích phân bố bullet/TC trước, đừng tách lấy được. Quy trình bền: sửa **source/backup** → **tái sinh** bằng script xác định → verify → sai thì restore.
+
+## Content Oracle — exact-copy phải self-contained + đúng nguồn
+
+- Chuỗi text spec-defined mà TC assert (tiêu đề màn, nhãn, copy nút, thông báo lỗi) → **ghi nguyên văn trong Expected Result** để TC tự chứa, người đọc không phải mở spec mới biết kỳ vọng.
+- **BẮT BUỘC kiểm nguồn ĐÚNG feature trước khi chép:** mở design-spec/PRD của **chính feature đó** và xác nhận chuỗi tồn tại. **KHÔNG mượn chuỗi từ feature anh em** — VD copy P2 của FEAT-01-1 là *"Việc tạo **tài khoản** đang tạm thời bị gián đoạn…"* còn FEAT-01-2 là *"Việc tạo **câu hỏi** đang tạm thời bị gián đoạn…"*; chép nhầm → oracle sai.
+- Chuỗi **chưa** có trong PRD/design-spec (chỉ ở Figma / chưa chốt) → **KHÔNG bịa oracle**: để trống + gắn `🚫 Block: [GAP-UC{N}-{nnn}]` hoặc `Status: PENDING`, ghi rõ chờ ai chốt.
+- Cờ "MIỄN coverage / thuộc Design Spec" trong BDD **không** cấm assert nếu PRD/design-spec vẫn enumerate đủ chuỗi — vẫn được đưa vào Expected Result; chỉ hạ về mức generic khi thực sự không có nguồn chốt.
+
+## Metadata (bắt buộc, dạng list)
+
+Mỗi trường 1 dòng, không bảng, không emoji dư:
+
+```
+- **Title:** <tên TC ngắn gọn>
+- **Feature:** <tên feature>
+- **Priority:** P0 | P1 | P2
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** <lane>, <loại: smoke|sanity|regression>, <feature-tag>
+- **Trace:** BR-xx (ID gốc trong PRD/BDD ở `{paths.specs_dir}`)
+- **🚫 Block:** [GAP-UC{N}-{nnn}](../DOC_GAP.md) — <lý do> *(chỉ khi có)*
+```
+
+## Quy tắc Trace & Block
+
+- **Trace:** ghi `BR-xx` lấy từ ID trong `{paths.specs_dir}`; không có BR → `⚠️ Chưa có Business Rule`.
+- **🚫 Block:** TC phụ thuộc gap **vẫn viết đủ** + ghi `[GAP-UC{N}-{nnn}] — lý do`; chưa chạy tới khi gap Answered.
+
+## Cấu trúc TC
+
+```markdown
+### [TC_ID] — [Tên TC]
+- **Title:** ...
+- **Feature:** ...
+- **Priority:** P0|P1|P2
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** ...
+- **Trace:** BR-xx
+- **🚫 Block:** (nếu có)
+
+#### Preconditions
+- ...
+
+#### Test Data
+- field: giá trị
+
+#### Test Steps
+1. [Action] ...          ← chỉ hành động; KHÔNG gắn "→ [Expected] ..."
+2. [Verify] ...          ← chỉ điểm quan sát; oracle nằm ở Expected Result
+
+#### Expected Result
+- <1 bullet kết quả cuối cụ thể, đo được — xem §"1 Expected Result / TC">
+
+#### Teardown   ← CHỈ khi TC tạo/sửa bản ghi hoặc state THẬT
+- <cách cleanup: API DELETE / reset tài khoản test / fixture / `⚠️ Manual teardown required`>
+```
+
+## Quy tắc Teardown (khi nào CÓ / KHÔNG)
+
+- **CÓ Teardown** chỉ khi TC tạo/sửa **bản ghi DB hoặc state thật** tồn tại sau test (vd: ghi phân khúc vào tài khoản test, tạo bản ghi qua API thật).
+- **KHÔNG cần Teardown** khi TC chỉ cấu hình **mock / route intercept / network monitoring** — việc reset mock về default là trách nhiệm của **fixture `conftest.py`** (scope `function` tự teardown mỗi test). Ghi "Reset mock về default" trong từng TC là **thừa** → không thêm.
+- Lane test qua mock hoàn toàn (vd lane UI/E2E khi API SKIP) → hầu hết TC KHÔNG có Teardown; chỉ TC chạm tài khoản/state thật mới có.
+
+## Phân nhóm TC & đánh số nhóm (chuẩn chung)
+
+TC trong file được gom theo **nhóm phân loại nội dung** và đánh **số CỐ ĐỊNH theo LOẠI** — số nhóm gắn cứng với loại, loại KHÔNG có TC thì **BỎ TRỐNG số đó** (KHÔNG đánh tuần tự lại). *(QC chốt 2026-07-08 — thay quy ước "liên tục" cũ.)*
+
+Gom theo **LOẠI test**, số nhóm CỐ ĐỊNH theo loại, chỉ tạo nhóm THỰC SỰ có TC:
+
+1. **GUI** — UI tĩnh, label, layout, placeholder, icon, trạng thái hiển thị (không đổi state).
+2. **Validation** — field-level: validate input, EP/BVA, biên, error message, trạng thái nút enabled/disabled theo điều kiện, read-only, ràng buộc.
+3. **Functional** — nghiệp vụ/luồng: business logic, submit/navigation, decision table, use case hoàn chỉnh.
+4. **Integration** — bắt tay ≥2 module/dịch vụ (kể cả qua mock): đọc/ghi cross-service, handshake, data flow, contract.
+5. **NFR** — phi chức năng: performance, a11y/keyboard, WCAG, security, i18n, compatibility.
+6. **E2E** — journey đầu-cuối nhiều use case.
+
+**Quy tắc đánh số & phân nhóm:**
+- Gán số CỐ ĐỊNH theo loại: **GUI=1 · Validation=2 · Functional=3 · Integration=4 · NFR=5 · E2E=6**. Loại KHÔNG có TC → **BỎ TRỐNG số đó**. VD file chỉ có GUI + Validation + Functional + E2E → `Nhóm 1 — GUI` / `Nhóm 2 — Validation` / `Nhóm 3 — Functional` / **`Nhóm 6 — E2E`** (bỏ trống 4 Integration, 5 NFR). **E2E LUÔN là Nhóm 6, NFR luôn 5, Integration luôn 4** — KHÔNG dồn số.
+- Phân vân **Validation vs Functional**: chỉ test trạng thái field/nút/biên → Validation; có luồng/submit/navigation/logic → Functional. **KHÔNG tạo nhóm "Tương tác"/"Happy Path" riêng.**
+- Lane chỉ có functional (API/Integration/NFR, không có GUI) → bỏ nhóm GUI, bắt đầu từ nhóm phù hợp.
+- **GIỮ NGUYÊN mã TC** khi gom/đảo nhóm — chỉ đổi vị trí; mã không cần liền mạch theo thứ tự đọc.
+- Mọi tham chiếu số nhóm trong file (Trace Matrix, ghi chú) phải khớp số CỐ ĐỊNH đã gán.
+
+## Cuối file (bắt buộc)
+
+Cả 2 mục dạng LIST (không bảng):
+
+```markdown
+## Trace Matrix
+- **BR-xx:** TC_001, TC_002
+- **⚠️ BR-yy:** — (Chưa có TC)
+
+## TC bị Block
+- **GAP-03** — TC_005: Chờ openapi.yaml
+```
+
+> Không thêm section `#### Python Test Mapping`. Bỏ nội dung gạch ngang.
+
+> ⚠️ **Bổ sung khi Edit thêm TC mới:** nối bullet mới **ngay liền sau bullet cuối** của list (Trace Matrix / TC bị Block), KHÔNG chèn dòng trắng giữa các bullet. Kiểm lại số TC khớp sau khi thêm.
+
+---
+
+## Tài liệu shared liên quan (bắt buộc nạp khi viết TC)
+
+| File | Mục đích |
+|---|---|
+| `shared/action-keywords-glossary.md` | Từ điển action keywords chuẩn — Click/Enter/Verify/Assert... |
+| `shared/precision-rules.md` | Quy tắc lượng hóa Expected Result, cấm từ mơ hồ, đơn vị chuẩn |
+| `shared/duplicate-check-procedure.md` | Quy trình kiểm tra TC trùng lặp trước khi viết mới |
+| `shared/implicit-scenarios.md` | Danh sách implicit scenarios cần xét thêm |
+| `shared/skill-decision-tree.md` | Cây quyết định chọn đúng skill |
+
+---
+
+## Gap Escalation Path (Xử lý khi TC bị Block)
+
+Khi TC có `🚫 Block: [GAP-UC{N}-{nnn}]` — thực hiện theo timeline:
+
+| Thời điểm | Hành động |
+|---|---|
+| **T+0 (phát hiện gap)** | Ghi GAP vào `DOC_GAP.md` — ID, loại, mô tả, tác động, nguồn |
+| **T+2 (2 ngày)** | Chưa có phản hồi → ping QA Lead / PO |
+| **T+5 (5 ngày)** | Vẫn chưa có → ghi **assumption tạm thời** vào TC bị Block |
+| **T+7 (7 ngày)** | Leo thang PO/PM — gap ảnh hưởng sprint delivery |
+
+### Format Assumption khi gap chưa được trả lời (T+5):
+
+```
+⚠️ Assumption (T+5): API trả về HTTP 422 khi tên lớp trùng — dựa trên pattern UC1.
+Nếu behavior khác → cập nhật Expected Result và re-review.
+```
+
+### Quy trình khi gap được giải quyết (Answered):
+1. Cập nhật `DOC_GAP.md`: status → `Answered`, ghi note giải thích.
+2. Bỏ `🚫 Block` trong TC → cập nhật Expected Result nếu có assumption sai.
+3. Thông báo `qa-tc-reviewer` review lại TC.
+4. Nếu answer thay đổi scope → tạo TC mới hoặc split TC hiện tại.
+
+---
+
+# Phần riêng của framework *(B12 — không có ở upstream)*
+
+Mọi thứ trên là chuẩn của đội QC. Bốn thứ dưới đây là **của framework**, và mọi skill tầng test
+đều theo — đừng lặp lại chúng trong từng skill.
+
+## Hai file TC, chia theo "có qua giao diện"
+
+```
+{qc_artifact_dir}test-cases/
+├── TC_<FEATURE>.Test.md          ← mặc định
+│     ## Nhóm 1 — GUI          ## Nhóm 4 — Integration (qua UI)
+│     ## Nhóm 2 — Validation   ## Nhóm 5 — NFR
+│     ## Nhóm 3 — Functional   ## Nhóm 6 — E2E
+└── TC_<FEATURE>_API.Test.md      ← cờ --api
+      ## Nhóm 1 — Endpoint
+      ## Nhóm 2 — Integration API/DB/Kafka
+```
+
+**Câu hỏi phân file:** *"TC này verify được mà **không cần UI** không?"*
+→ **có** = file API · **không** = file giao diện. *(Trùng Bước 2 của `skill-decision-tree.md`.)*
+
+⚠️ **Đuôi file là `.Test.md`, không phải `.md`.** `/qc-run-test` và `/qc-review` tìm `*.Test.md`;
+ghi ra file thiếu phần `.Test` là ghi ra thứ **không trạm nào tìm thấy**, và không có gì báo lỗi.
+
+Đánh số `TC_<FEATURE>_NNN` **liên tục toàn file**, không đánh lại theo từng nhóm.
+
+## Trace — hai hệ, ghi cả hai
+
+| Trường | Dạng | Vì sao cần |
+|---|---|---|
+| `**Trace:**` | `[BR-xx](../REQUIREMENT_ANALYSIS.md#3-business-rules)` — không có BR → `⚠️ Chưa có Business Rule` | truy về luật nghiệp vụ |
+| `**@trace.verifies:**` | `{UC-ID}-SC{N}` (lấy từ `@trace.scenario` của file `.feature`) | **join key** để `/qc-run-test` ghi `qc_status` theo từng kịch bản vào sổ trace |
+
+Một `SC` map được nhiều TC. **Thiếu `@trace.verifies` thì kết quả chạy không vào được sổ** — TC
+vẫn chạy, vẫn pass/fail, nhưng không ai biết nó phủ kịch bản nào.
+
+Cuối file: **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách TC bị block** — cả hai **dạng danh
+sách**, không bảng (§Nguyên tắc format file đầu tài liệu này).
+
+## `🚫 Block` trỏ về file gap cấp PRD
+
+```
+- **🚫 Block:** [GAP-UC{N}-{nnn}](../DOC_GAP.md) — <lý do>
+```
+
+`DOC_GAP.md` nằm ở **thư mục cha** của `test-cases/`, nên liên kết đi lên một cấp. Mã gap mang
+UC (`GAP-UC1-001`) vì một file gap phủ cả PRD.
+
+## Dòng `Test-ID attribute`
+
+Ghi một dòng ở phần metadata **đầu file**:
+
+```
+Test-ID attribute: {attr}
+```
+
+Đọc `@trace.testid_attr` từ header tech-doc gộp (do `/map-testids` ghi). Bảng §4.5.6 chỉ cho
+**giá trị** test-id; đây là **tên thuộc tính** chứa chúng. `/qc-run-test` cần nó để cấu hình
+locator, `/qc-review` cần nó để biết selector trong script có đúng hợp đồng không.
+
+Thiếu field trong tech-doc → ghi `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)`.
+**Đừng bỏ trống và đừng tự đoán** — đoán sai thì mọi locator trượt 100%, và trượt vì lý do
+không liên quan gì tới thứ đang test.

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

@@ -102,5 +102,5 @@ tiền không đáng.
 |---|---|---|---|---|---|
 | … | 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` /
+Mỗi dòng rủi ro phải **trỏ được về `BR-xx` hoặc `GAP-UC{N}-{nnn}`** đã 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.

package/core/skills/qc/qa-reviewer/script/e2e.md

@@ -84,4 +84,12 @@ F. CONVENTION:
 
 Mỗi issue: `file:line` | severity | mô tả | suggestion fix.
 Severity: 🔴 fix ngay (missing cleanup, dữ liệu không verify cross-module, shortcut journey) · 🟠 quan trọng (timeout thiếu, assertion chỉ ở bước cuối) · 🟡 nhỏ (style, docstring/title sai).
-Score: A/B/C/D · Top 5 issue cần fix trước merge.
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.

package/core/skills/qc/qa-reviewer/script/exploratory.md

@@ -39,7 +39,15 @@ Review session note sau khi test, coaching QC cải thiện kỹ năng.
  
 ## Output
  
-Score: A (excellent) / B (good) / C (needs improvement) / D (redo)
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.
 Mỗi tiêu chí: ✅/⚠️/❌ + feedback cụ thể
 Top 3 improvement suggestions (coaching tone)
 Đề xuất charter tiếp theo nếu chưa đủ coverage

package/core/skills/qc/qa-reviewer/script/functional.md

@@ -98,4 +98,12 @@ empty step `:pass` · test gọi `_private()` · Counter≠Pagination → xfail
  
 Mỗi issue: file:line | severity | mô tả | suggestion fix.
 Severity: 🔴 fix ngay (sai logic, POM breach, silent fail) · 🟠 quan trọng (fragile selector, wrong column, missing assert) · 🟡 nhỏ (style, thừa wait, orphan constant).
-Score: A/B/C/D · Top 5 issue cần fix trước.
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.

package/core/skills/qc/qa-reviewer/script/integration.md

@@ -88,4 +88,12 @@ F. CONVENTION:
 
 Mỗi issue: `file:line` | severity | mô tả | suggestion fix.
 Severity: 🔴 fix ngay (mock thay real call, missing DB verify, no cleanup) · 🟠 quan trọng (thiếu error state, hardcode ID, timeout ngắn) · 🟡 nhỏ (style, marker thiếu sub-domain).
-Score: A/B/C/D · Top 5 issue cần fix trước merge.
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.

package/core/skills/qc/qa-reviewer/script/non-functional.md

@@ -123,4 +123,12 @@ def test_compatibility(browser_name, playwright):
 
 Mỗi issue: `file:line` | severity | mô tả | suggestion fix.
 Severity: 🔴 fix ngay (assertion không có ngưỡng, gọi production endpoint, hardcode credential) · 🟠 quan trọng (ngưỡng không khớp TC, thiếu parametrize, không teardown data) · 🟡 nhỏ (style, marker thiếu sub-domain, docstring thiếu ngưỡng).
-Score: A/B/C/D · Top 5 issue cần fix trước merge.
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.

package/core/skills/qc/qa-reviewer/shared/read-doc-gap-inputs.md

@@ -0,0 +1,26 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-reviewer/shared/read-doc-gap-inputs.md
+upstream_sha: 3caa1562399ef1167ac2dc620add2c6c729e55df
+---
+
+# Thủ tục: Nạp TOÀN BỘ tài liệu input từ DOC_GAP (BẮT BUỘC trước khi review TC)
+
+> Mục tiêu: reviewer phải đọc **đúng bộ tài liệu nguồn mà `/qc-analyze` đã dùng** để dựng TEST_PLAN + DOC_GAP — không chỉ file domain. Chỉ khi nắm đủ ngữ cảnh nguồn mới bắt được TC hiểu sai nghiệp vụ, thiếu case, hoặc trace sai spec.
+
+## Các bước
+
+1. **Tìm file DOC_GAP** tại `{qc_artifact_dir}DOC_GAP.md` — **một file cho cả PRD**, các UC là các hàng phân biệt bằng cột `UC`. Không có → chạy `/qc-analyze {TICKET-ID} {platform}` trước; **đừng soát TC trên ngữ cảnh thiếu** (soát mù thì kết luận "0 lỗi" là vô nghĩa).
+2. **`Read` toàn bộ DOC_GAP.** Định vị mục **`## Tài liệu đầu vào đã đọc để phân tích`** — bảng liệt kê **đầy đủ** file nguồn (cột "Đường dẫn", tính từ `{paths.specs_dir}/`), kèm vai trò & phiên bản.
+3. **`Read` TỪNG file trong bảng đó** — ghép prefix `{paths.specs_dir}/` vào đường dẫn ở cột. Đọc HẾT, không bỏ sót dòng nào (spec chính + ref bắt buộc + transitive 1-hop). Nếu bảng liệt kê phiên bản, kiểm tra file hiện tại khớp; lệch phiên bản → ghi chú vào REVIEW.
+4. **Đối chiếu chéo:** file nào có mặt ở header DOC_GAP ("Tài liệu nguồn (spec chính)"/"Coverage Attestation") mà thiếu trong bảng → vẫn đọc.
+5. Chỉ sau khi đã nạp xong toàn bộ input + file domain (`business-dictionary.md`, `product-definition/`) mới bắt đầu review — dùng chúng làm chuẩn đối chiếu để phán quyết `APPROVED` / `NEEDS_FIX`.
+
+## Nguyên tắc
+
+- **Chuẩn đối chiếu = tài liệu nguồn**, không phải suy đoán riêng của reviewer. Mọi nhận xét "TC hiểu sai/thiếu case" phải chỉ được về đoạn spec cụ thể trong các file đã đọc.
+- **Không đọc thiếu:** nếu DOC_GAP nói "Tổng: N tài liệu" thì phải mở đủ N.
+- Gap còn `Open` trong DOC_GAP: TC chạm vùng đó phải phản ánh đúng (đánh dấu blocked/assumption), không được coi như spec đã rõ.
+- Lane API: nếu DOC_GAP ghi SKIP → không đòi hỏi TC endpoint không tồn tại.