## [QA] 4-Gate TestCase Creation Workflow

> **For:** `create-testcase`
> **Persona:** Quality Assurance (QA)
> **Goal:** Chuyển đổi yêu cầu thô (SRS / Backlog / Jira / Spec file) thành bộ Test Case hoàn chỉnh sẵn sàng thực thi, tuân theo quy trình QA Workflow chuẩn.
> **Interaction Rules:** Hỏi ONE câu hỏi tại một thời điểm — đợi QA trả lời trước khi tiếp tục. KHÔNG hỏi nhiều câu cùng lúc.

---

### Quy tắc đặt câu hỏi — phụ thuộc, chất lượng, chống hỏi trùng, tự tìm hiểu trước khi hỏi

> Áp dụng cho **mọi câu hỏi** phát ra ở cả 4 Gate (chủ yếu Gate 1 Bước 2b). Người trả lời có thể là TESTER, BA, Dev hoặc khách hàng — mặc định coi như **không** đọc code.

#### QnA Log — nơi ghi mọi câu hỏi của 4 Gate

Mọi câu hỏi, câu trả lời, quyết định và issue cần người khác trả lời của cả 4 Gate ghi vào **một file**: `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md`. Không tạo file QA riêng cho từng gate.

- **Format:** dùng lại template QnA-Log của `create-spec` — `.claude/skills/ba-skills/skill-ba-qna-template-v1.md` (mỗi câu một khối: Tiêu đề, hai dòng thông tin, Hiện trạng, Bối cảnh, Vấn đề, Câu hỏi, Lựa chọn và đề xuất, Ví dụ minh họa, Câu trả lời, Người trả lời / Ngày trả lời / Nguồn; nhóm theo role; bảng "Quyết định đã chốt + hệ quả suy ra"; "Lịch sử cập nhật tài liệu"; dạng gọn khi hỏi trong chat). Khác biệt riêng của `create-testcase`:

  | Điểm | `create-testcase` |
  |---|---|
  | Đường dẫn | `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md` — một file, không đánh version. Mode UPDATE ghi tiếp vào file cũ, ghi vào "Lịch sử cập nhật tài liệu" |
  | Mã câu hỏi | **`TQ-01`, `TQ-02`…** (không dùng `QA-xx` để không trùng QnA-Log của BA cùng `functionId`) |
  | Mức độ | 🔴 **Blocking** (chưa trả lời thì output sai hoặc thiếu TC) · 🟡 **Non-blocking** (đi tiếp được, giữ marker) |
  | Marker trong output | `[PENDING - TQ-xx]` trong Test Plan / `TestCase.md` |
  | Người trả lời | QA Lead / BA / PM / Khách hàng |
  | Nguồn | Ngoài Khách hàng, BA…: thêm `UC Spec`, `System Requirement`, `Code` (AI tự suy ra được và QA xác nhận) |

- Câu hỏi lộ ra lỗ hổng của UC Spec / System Requirement (không chỉ là cách test) → ghi thêm ở Bối cảnh: `Cần BA cập nhật UC Spec`, để BA đưa vào QnA-Log của `create-spec`.

#### A. Phụ thuộc giữa các câu hỏi — không hỏi câu bị chặn

1. **Dựng bản đồ phụ thuộc trước khi hỏi câu đầu tiên.** Mỗi nghi vấn ghi thêm trường `Phụ thuộc`: `—` (độc lập) hoặc mã câu cha (`TQ-xx`) khi đáp án chỉ có nghĩa/chỉ xác định được tập lựa chọn sau khi câu cha đã có câu trả lời.
2. **Cascade defer.** Câu cha chưa có câu trả lời (đang chờ TESTER/khách hàng) → mọi câu phụ thuộc nó **KHÔNG** được hỏi trong vòng này, kể cả khi bản thân nó là 🔴 Blocking. Ghi trạng thái **`Blocked-by TQ-xx`** trong QnA Log, dùng chung marker `[PENDING - TQ-xx]` của câu cha thay vì tạo marker riêng.
3. **Thứ tự hỏi:** câu cha trước câu con; trong cùng mức, 🔴 Blocking trước 🟡 Non-blocking.
4. **Mở khoá:** câu cha có câu trả lời → soát lại câu con: đáp án đã bao phủ → đóng luôn, không hỏi; chưa bao phủ → mới đưa vào hàng đợi hỏi.
5. Cấm tách nhỏ hoặc diễn đạt lại một câu bị chặn để hỏi lách qua khoá này.

#### B. Chất lượng câu hỏi — dễ hiểu cho người không chuyên kỹ thuật

1. **Mỗi câu hỏi tự đứng một mình được**, đủ 4 phần:
   - **Bối cảnh** (1–3 câu): màn hình/nghiệp vụ nào, tình huống nào, tài liệu hiện ghi gì — ngôn ngữ nghiệp vụ. Ý cuối nêu **chưa chốt thì ảnh hưởng gì** (test case/luồng nào bị thiếu).

   > ❌ **KHÔNG** viết mục "Vì sao cần hỏi" thành một mục riêng — kể cả khi hỏi trực tiếp trong hội thoại. Nội dung đó đã gộp vào Bối cảnh ở trên, và hệ quả của từng lựa chọn đã nằm trong Options; tách ra thành mục riêng làm câu hỏi dài gấp đôi mà không thêm thông tin. Phản hồi thật từ PM khi đọc câu hỏi có mục này: "nội dung khá rườm rà".
   - **Câu hỏi**: đúng một ý. Hai ý → tách hai câu.
   - **Options kèm hệ quả từng option**, luôn có "Khác — mô tả ngắn".
2. **Ngôn ngữ:** không dùng tên bảng/cột/API/biến/file trong phần câu hỏi (cần thì để trong ngoặc phụ chú cuối câu). **Mọi từ viết tắt và thuật ngữ nội bộ phải giải nghĩa ngay lần đầu xuất hiện**, dạng `<viết tắt> (<nghĩa đầy đủ>)`. **Thuật ngữ, tên màn hình, nhãn tiếng Nhật không đứng một mình trong câu tiếng Việt/tiếng Anh** — áp dụng cho câu hỏi, artifact Gate 1–4, test case và Dev Checklist: mô tả khái niệm thì viết `tên gọi (chữ gốc)`, Steps/Expected Result cần khớp chữ trên màn hình thì viết `chữ gốc (tên gọi)`; tên gọi lấy từ cột `Viết trong tài liệu` của `AK-Docs/00.Project-Overview/Glossary.md`, chưa có thì đề xuất để QA xác nhận, không tự dịch rồi dùng luôn (xem `custom/rules/domain-terminology.md`, mục "Thuật ngữ tiếng Nhật", và `qa-writing-standards.md` §6.8).
3. **Câu hỏi phức tạp** (≥2 điều kiện, ảnh hưởng nhiều màn hình/luồng, hoặc nói về thứ tự/ưu tiên/thời điểm) bắt buộc kèm khối:

```
Ví dụ minh hoạ: <tình huống cụ thể, có số liệu/ngày giờ thật>
→ Nếu chọn A: <kết quả người dùng nhìn thấy>
→ Nếu chọn B: <kết quả người dùng nhìn thấy>
```

4. Bối cảnh không quá 3 câu. Không tóm được trong 3 câu → câu hỏi đang gộp nhiều vấn đề, phải tách.

#### C. Chống hỏi trùng — suy ra từ câu trả lời đã có

> Số lượng câu hỏi **không phải** thước đo chất lượng phân tích. Hỏi để làm rõ điểm mơ hồ là bắt buộc; hỏi lại điều đã chốt là lỗi.

1. **Duy trì bảng "Quyết định đã chốt + hệ quả suy ra"** trong QnA Log. Sau mỗi câu trả lời, ghi quyết định kèm các hệ quả suy ra trực tiếp — ví dụ "Không retry khi gửi thất bại" suy ra: không có số lần retry, không có khoảng cách retry, không retry cho kênh khác trong cùng luồng, không có test case cho luồng retry.
2. **So khớp theo ý định nghiệp vụ, không theo chữ.** Cấm hỏi lại cùng một quyết định bằng từ đồng nghĩa (`retry` = `gửi lại` = `thử lại` = `chạy lại`). Trùng ý định → không hỏi, ghi `Suy ra từ TQ-xx: <nội dung suy ra>`.
3. **Không chắc đáp án cũ có bao phủ hay không** → hỏi **đúng một câu xác nhận yes/no**: `Xác nhận nhanh: theo TQ-xx đã chốt "<quyết định>", suy ra "<hệ quả>". Đúng không?` — một lần duy nhất cho mỗi suy luận.
4. **Cấm hỏi lấy số lượng.** Câu hỏi không làm đổi nội dung Test Plan / scenario / test case → ghi thành giả định ở Test Plan mục 1.7 (Giả định & giới hạn), không hỏi.
5. **Người trả lời hỏi ngược "câu này có cần thiết không?"** → tín hiệu đã vi phạm mục C. Trả lời thẳng, rút câu hỏi nếu không cần (ghi `Rút — suy ra từ TQ-xx`), và rà lại toàn bộ câu chưa hỏi bằng mục C.2 trước khi hỏi tiếp.

#### D. Tự tìm hiểu trước khi hỏi — chỉ hỏi thứ không quan sát được

> Nguồn gốc quy tắc: QA phản ánh phải trả lời quá nhiều câu confirm về **thiết lập/quy ước dự án** (cách chuẩn bị dữ liệu test, phạm vi chạy trên Staging, trình duyệt, breakpoint...) — những thứ AI tự đọc repo/tài liệu là ra, hoặc có mặc định hợp lý. Hỏi những câu này làm loãng các câu hỏi nghiệp vụ thật sự cần QA quyết.

1. **Phân loại mọi nghi vấn trước khi mở miệng hỏi:**

   | Loại | Ví dụ | Xử lý |
   |---|---|---|
   | **Quan sát được** — câu trả lời nằm trong repo, tài liệu, config, hoặc có quy ước mặc định | Môi trường & URL, phạm vi chạy từng môi trường, trình duyệt/thiết bị, breakpoint responsive, danh sách ngôn ngữ, cách chuẩn bị dữ liệu test, có API/DB để xác minh không, ngôn ngữ viết tài liệu | **Tự tìm → tự điền → KHÔNG hỏi.** Ghi giá trị kèm nguồn; không có bằng chứng thì dùng mặc định và ghi `[mặc định]` |
   | **Chính sách / đánh đổi** — phụ thuộc ý muốn của dự án, không quan sát được | Tách TC theo chiều nào (`split`/`column`/`sample`), lặp ngôn ngữ phụ `full` hay `ui-text`, tiêu chí PASS cho giao dịch async | **Hỏi — nhưng kèm đề xuất sẵn**, gộp nhiều mục vào một bảng xác nhận |
   | **Mâu thuẫn / thiếu trong nghiệp vụ** | UC Spec nói A, System Requirement nói B; thiếu điều kiện biên | Hỏi theo mục A–C (từng câu một) |

2. **Bắt buộc quét nguồn trước khi kết luận "không biết".** Tối thiểu: repo source (config, i18n, script seed, test có sẵn, `.env*`, `README`), `AK-Docs/` (tài liệu môi trường, strategy, TestCase của function khác), UC Spec / System Requirement, mô tả ticket. Chưa quét mà đã hỏi = vi phạm.

3. **Hỏi bằng khẳng định, không bằng câu hỏi mở.** Đã suy ra được giá trị nhưng muốn chắc → viết `Tôi dùng <giá trị> (nguồn: <bằng chứng>) — sai thì báo tôi sửa.` và **chạy tiếp ngay**, không chờ trả lời. Chỉ mục `[CHỐT]` mới được dừng chờ.

4. **Gộp — không rải.** Nhiều mục cùng nhóm thiết lập/chính sách → một bảng xác nhận duy nhất, trả lời một lần (mẫu ở Gate 1 Bước 0.7). Cấm biến một bảng thành 5–10 câu hỏi liên tiếp.

5. **Ngân sách câu hỏi thiết lập:** tối đa **1 bảng xác nhận + 1 câu làm rõ** cho toàn bộ nhóm thiết lập/chính sách của cả 4 Gate. Hết ngân sách mà vẫn mơ hồ → áp dụng đề xuất, ghi Assumption, chạy tiếp. (Ngân sách này **không** áp cho câu hỏi làm rõ **nghiệp vụ** ở Bước 2b — loại đó vẫn hỏi đến khi hết nghi vấn 🔴 Blocking.)

#### E. Self-check bắt buộc trước khi gửi mỗi câu hỏi

Trả lời được cả 4 ý mới được gửi:
- Đáp án làm thay đổi **cụ thể mục nào** trong output (Test Plan Phần 1 / Risk Matrix / scenario / test case)? Không nêu được → không hỏi.
- **Đã quét repo/tài liệu chưa, và câu này có thuộc loại "quan sát được" ở mục D không?** Có → tự điền, không hỏi.
- Người không technical đọc có hiểu ngay không? Không → viết lại theo mục B.
- Đã được trả lời hoặc suy ra được từ quyết định đã chốt chưa (mục C), và có đang bị chặn bởi câu cha nào không (mục A)?

---

### Thuật ngữ nghiệp vụ (áp dụng cả 4 Gate)

Mọi artifact (Test Plan, QnA Log, Test Case, Review Result, Dev Checklist, report) dùng đúng từ mà UC Spec, System Requirement, QnA-Log của cùng functionId và `AK-Docs/00.Project-Overview/Glossary.md` đã dùng — theo `custom/rules/domain-terminology.md`. Không tự dịch từ dự án (`buyer`, `group`, `product`), không tự đặt tên phân hệ / menu / màn hình ("cửa hàng", "cổng", "trang quản trị"), không để chữ tiếng Nhật đứng một mình trong câu. Từ chưa có trong Glossary → hỏi QA/BA rồi ghi vào Glossary. Động từ thao tác UI và thuật ngữ IT: `custom/rules/ui-action-wording.md` (bản gốc của bảng từ vựng `qa-writing-standards.md` mục 6.11). UC Spec và System Requirement dùng cùng bộ từ này, nên Steps / Expected Result chép được sang từ UC Spec mà không phải đổi từ.

Skill `gate-review` (Step 2b) kiểm lại trước mỗi lần dừng gate.

---

### Pre-flight BẮT BUỘC — Đồng bộ Source & Docs (đầu MỖI Gate)

> Áp dụng cho **cả 4 Gate** bên dưới — không chỉ Gate 1. Chạy đủ các bước sau **trước khi** thực hiện bất kỳ hành động nào khác của gate đó.

1. **Sync repo source (bên trong, không phải AK-Docs/Shared-Docs):** xác định thư mục repo source liên quan (field `repo` trong context, hoặc repo duy nhất mở trong workspace) → `cd` vào đó → chạy `git status --porcelain`; nếu working tree sạch, chạy `git pull --ff-only`. Nếu có thay đổi chưa commit, branch diverged, hoặc không có remote tracking branch → bỏ qua pull (không phải lỗi).
2. **Sync `AK-Docs/`:** `cd` vào `AK-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
3. **Sync `Shared-Docs/`:** `cd` vào `Shared-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
4. Sau khi xong, `cd` quay lại thư mục làm việc ban đầu trước khi tiếp tục các bước khác của gate.

Nếu `AK-Docs/` hoặc `Shared-Docs/` chưa tồn tại tại workspace root, hoặc không phải git repo → bỏ qua bước tương ứng, không cảnh báo.

> ❌ **KHÔNG** tự ý liệt kê (`git branch -a`), checkout, hoặc đọc/diff nhiều branch trong repo source để tự dò tìm "nhánh đang phát triển" của feature — rất tốn token và thời gian, và dễ đọc nhầm code chưa hoàn chỉnh/chưa merge. Bước 1 chỉ `git pull` đúng branch hiện tại đang checkout (thường là `main`/`develop`). Nếu cần biết chính xác code nào đã thay đổi cho ticket này → xem bước **Dev Artifacts Check** (Bước 1.5, Gate 1, bên dưới): hỏi TESTER cung cấp PR link hoặc commit SHA/branch name cụ thể, rồi fetch/diff **đúng** phạm vi đó qua skill `pr-impact-analysis`.

**Nếu bất kỳ lệnh `git pull` nào ở Bước 1–3 thất bại** → **KHÔNG dừng workflow** — hiển thị cảnh báo và tiếp tục gate với dữ liệu local hiện có:

```
⚠️ CẢNH BÁO: Không thể pull [tên repo] — [lý do lỗi].
→ Đang tiếp tục Gate [N] với dữ liệu local hiện tại, có thể chưa mới nhất.
```

---

### QA Skills

Các skill sau đây được cài tự động vào `.claude/skills/test-skills/` khi chạy `ak init` hoặc `ak up`.

| Skill | File |
|---|---|
| `PR Impact Analysis` | `.claude/skills/pr-impact-analysis/SKILL.md` |
| `QA Writing Standards` | `.claude/skills/test-skills/rules/qa-writing-standards.md` |
| `Directory & Naming Convention` | `.claude/skills/test-skills/rules/directory-and-naming-convention.md` |
| `Template TestCase` | `.claude/skills/test-skills/template/testcase-template.md` |
| `Template Test Strategy` | `.claude/skills/test-skills/template/test-strategy-template.md` |
| `Template Dev Checklist` | `.claude/skills/test-skills/template/dev-checklist-template.md` |
| `Template Test Plan` | `.claude/skills/test-skills/template/test-plan-template.md` |
| `Template Review Result` | `.claude/skills/test-skills/template/review-result-template.md` |
| `Template Brief Gate 3` | `.claude/skills/test-skills/template/gate3-brief-template.md` |
| `Template QnA Log` (dùng chung với `create-spec`) | `.claude/skills/ba-skills/skill-ba-qna-template-v1.md` |
| `00.01 Requirement Analysis` | `.claude/skills/test-skills/categories/00-core/00.01.requirement-analysis.md` |
| `00.02 Risk Analysis` | `.claude/skills/test-skills/categories/00-core/00.02.risk-analysis.md` |
| `00.03 Test Scenario Builder` | `.claude/skills/test-skills/categories/00-core/00.03.test-scenario-builder.md` |
| `00.04 TestCase Review` | `.claude/skills/test-skills/categories/00-core/00.04.testcase-review.md` |
| `01.01 BVA` | `.claude/skills/test-skills/categories/01-test-design/01.01.boundary-value-analysis.md` |
| `01.02 EP` | `.claude/skills/test-skills/categories/01-test-design/01.02.equivalence.partitioning.md` |
| `01.03 Decision Table` | `.claude/skills/test-skills/categories/01-test-design/01.03.decision-table.md` |
| `01.04 State Transition` | `.claude/skills/test-skills/categories/01-test-design/01.04.state.transition.md` |
| `01.05 Pairwise` | `.claude/skills/test-skills/categories/01-test-design/01.05.pairwise.md` |
| `01.06 Error Guessing` | `.claude/skills/test-skills/categories/01-test-design/01.06.error-guessing.md` |
| `02.01 UI Layout` | `.claude/skills/test-skills/categories/02-ui-testing/02.01.UI-layout.md` |
| `02.02 Form Validation` | `.claude/skills/test-skills/categories/02-ui-testing/02.02.form-validation.md` |
| `02.03 Navigation` | `.claude/skills/test-skills/categories/02-ui-testing/02.03.navigation.md` |
| `02.04 Localization` | `.claude/skills/test-skills/categories/02-ui-testing/02.04.localization.md` |
| `03.01 CRUD Testing` | `.claude/skills/test-skills/categories/03-business-testing/03.01.CRUD-testing.md` |
| `03.02 Workflow Testing` | `.claude/skills/test-skills/categories/03-business-testing/03.02.workflow-testing.md` |
| `03.03 Permission Testing` | `.claude/skills/test-skills/categories/03-business-testing/03.03.permission-testing.md` |
| `03.04 Dependency Validation` | `.claude/skills/test-skills/categories/03-business-testing/03.04.dependency-validation.md` |
| `03.05 Notification Testing` | `.claude/skills/test-skills/categories/03-business-testing/03.05.notification-testing.md` |
| `03.06 Calculation Testing` | `.claude/skills/test-skills/categories/03-business-testing/03.06.calculation.testing.md` |
| `04.01 Database Testing` | `.claude/skills/test-skills/categories/04-data-testing/04.01.database-testing.md` |
| `04.04 Duplicate Handling` | `.claude/skills/test-skills/categories/04-data-testing/04.04.duplicate-handling.md` |
| `05.04 File Upload/Download` | `.claude/skills/test-skills/categories/05-integration/05.04.file-upload-download.md` |
| `99.01 Coverage Review` | `.claude/skills/test-skills/categories/99-review/99.01.coverage-review.md` |
| `08.01 Domain CMS` | `.claude/skills/test-skills/categories/08-domain-skills/CMS.md` |
| `08.02 Domain E-Commerce` | `.claude/skills/test-skills/categories/08-domain-skills/Ecommerce.md` |
| `08.03 Domain Blockchain — Wallet / Transfer / Staking` | `.claude/skills/test-skills/categories/08-domain-skills/Blockchain-Wallet-Staking.md` |
| `08.04 Domain NFT — Gacha / Mint / Marketplace` | `.claude/skills/test-skills/categories/08-domain-skills/NFT-Gacha-Marketplace.md` |

---

### Cấu trúc thư mục đầu ra

```
AK-Docs/03.Testing/
├── 00.Strategies/
│   └── Test-Strategy.md                                        ← project-level; AI tự điền mục [AI SUY LUẬN], QA chốt mục [CHỐT] ở Gate 1 Bước 0.7 (tạo từ template nếu chưa có)
└── 01.Testcases/
    └── [functionId]/
        ├── [functionId]_QnA Log.md          ← Gate 1–4 ghi (mọi câu hỏi, câu trả lời, quyết định)
        ├── [functionId]_Test Plan.md        ← Gate 1 (Phần 1 Phân tích), Gate 2 (Phần 2 Scenario), Gate 3 (Phần 3 Coverage)
        ├── [functionId]_TestCase.md         ← Gate 3 dựng bằng `ak tc build`, Gate 4 chỉ Edit
        ├── [functionId]_Review Result.md    ← Gate 4 (Findings, Coverage Validation, RTM, Sign-off)
        ├── [functionId]_Dev_Checklist.md    ← Gate 4 (checklist Dev tự kiểm trước khi bàn giao QA)
        └── _parts/                          ← tạm trong Gate 3 (brief + file part), `ak tc build` xoá khi dựng xong
```

Ví dụ: `functionId = AD06` → thư mục gốc là `AK-Docs/03.Testing/`

> `create-testcase` **không** ghi gì vào `AK-Docs/03.Testing/07.AI-Artifacts/`. Bộ TC chỉ được viết **một lần** (Gate 3, vào file part) rồi dựng thành `TestCase.md` bằng code — không có Draft, không có bản chép lại ở Gate 4.
>
> Tên file có dấu cách → mọi lệnh shell phải đặt đường dẫn trong ngoặc kép, ví dụ `ak tc lint --doc "AK-Docs/03.Testing/01.Testcases/AD06/AD06_Test Plan.md"`.

> ⚠️ **Quy tắc đường dẫn (bắt buộc):** `AK-Docs/` là sibling folder nằm ở workspace root (cạnh source repo). Mọi đường dẫn đầu ra trong workflow này đều nằm **bên trong** `AK-Docs/` — luôn ghi file theo đường dẫn đầy đủ `AK-Docs/03.Testing/...`. **CẤM** tạo thư mục `03.Testing/` ở workspace root hoặc bên trong source repo.

---

### Quy trình tổng quan 4 Gates

```
(TC/ = AK-Docs/03.Testing/01.Testcases/[functionId]/ — viết tắt cho ngắn gọn)

[Input: UC Spec + System Requirement (bắt buộc, cảnh báo nếu thiếu) / SRS / Jira / Backlog / Spec file] → Pre-flight: BẮT BUỘC xác định functionId
    ↓
Test Strategy pre-check: AI tự điền mọi mục [AI SUY LUẬN] từ repo/tài liệu (không hỏi) → gộp 1 bảng xác nhận cho các mục [CHỐT] (chính sách tách TC) → QA trả lời "ĐỒNG Ý" là chạy tiếp
    ↓
Gate 1: Phân tích & Q&A        → TC/[functionId]_Test Plan.md (Phần 1) + TC/[functionId]_QnA Log.md
    ↓ APPROVED
Gate 2: Test Plan (Scenario)   → TC/[functionId]_Test Plan.md (Phần 2)
    ↓ APPROVED
Gate 3: Tạo testcase           → TC/_parts/ (tc-writer viết theo section) → `ak tc build` → TC/[functionId]_TestCase.md
                                 + TC/[functionId]_Test Plan.md (Phần 3 Coverage)
    ↓ APPROVED
Gate 4: Review                 → Edit TC/[functionId]_TestCase.md (chỉ TC có finding)
                                 + TC/[functionId]_Review Result.md + TC/[functionId]_Dev_Checklist.md
    ↓ APPROVED (Fully / Conditionally)
Sẵn sàng thực thi kiểm thử
```

**Model theo gate:** phiên chính Gate 1, 2 dùng tier Mạnh effort high; Gate 3, 4 tier Mạnh effort medium; agent `tc-writer` ở Gate 3 tier Vừa (bảng quy đổi tier → model của từng công cụ: `custom/agents/model-tiers.json`). Đổi model ở đầu phiên mới của gate, không đổi giữa gate.

---

### GATE 1 — Phân tích & Q&A (auto-start)

**Mục tiêu:** Tiếp nhận đầu vào, hiểu nghiệp vụ, xác định phạm vi kiểm thử, nhận diện rủi ro và **đào sâu làm rõ toàn bộ vấn đề mơ hồ ngay tại gate này** (hỏi QA từng câu một, tiếp tục đến khi hết nghi vấn 🔴 Blocking) — để Gate 2, 3, 4 phía sau hiếm khi phải dừng lại hỏi thêm.

**Đầu ra (Outputs):**
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md` — Thông tin chung + Phần 1 (Phân tích)
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md` — khi có câu hỏi

**Bước thực hiện:**

**Pre-flight (bắt buộc, chạy trước Bước 0):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.

#### Bước 0: Pre-flight — Xác định functionId và thư mục đầu ra

**Xác định `functionId` (BẮT BUỘC):**

Kiểm tra theo thứ tự ưu tiên:
1. Trường `functionId` hoặc `screenId` trong `.aiflow/context/current.json`
2. Rút gọn từ `ticketId` — bỏ dấu gạch, giữ ký hiệu (ví dụ: `AD-06` → `AD06`)
3. Nếu không tìm thấy → **BẮT BUỘC hỏi QA ngay**:

```
Không tìm thấy functionId trong context.
Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-LOGIN, PM-003):
```

→ Đợi QA trả lời, ghi nhận giá trị, dùng cho toàn bộ workflow. KHÔNG ĐƯỢC TIẾP TỤC NẾU CHƯA CÓ functionId.

**Xác định thư mục đầu ra:**

1. Kiểm tra tồn tại thư mục `AK-Docs/` ở workspace root (sibling folder cạnh source repo):
   - **Không tìm thấy `AK-Docs/`** → **DỪNG**, không tự tạo bất kỳ thư mục nào, thông báo QA:
     ```
     ✗ Không tìm thấy thư mục AK-Docs/ ở workspace root.
     → Vui lòng clone AK-Docs cạnh source repo (xem .aiflow/docs/Project-Structure.md) rồi chạy lại.
     ```
   - **Tìm thấy** → sang bước 2.
2. Kiểm tra tồn tại thư mục `AK-Docs/03.Testing/`:
   - **Tìm thấy** → thông báo xác nhận:
     ```
     ✓ Thư mục đầu ra: AK-Docs/03.Testing/
     ✓ functionId: [functionId]
     → Bắt đầu Gate 1...
     ```
   - **Không tìm thấy** → tạo toàn bộ cây thư mục **bên trong `AK-Docs/`** (không tạo `03.Testing/` ở workspace root):
     ```
     AK-Docs/03.Testing/01.Testcases/[functionId]/
     ```
     → Thông báo:
     ```
     ✓ Đã tạo thư mục: AK-Docs/03.Testing/
     ✓ functionId: [functionId]
     → Bắt đầu Gate 1...
     ```

#### Bước 0.5: Đảm bảo đang làm việc trên branch riêng của task (AK-Docs)

Trước khi ghi bất kỳ file nào vào `AK-Docs/03.Testing/`, đảm bảo AK-Docs đang ở branch riêng của task này, không phải `main` (mọi thay đổi `AK-Docs` phải qua branch + Merge Request, PM duyệt cuối cùng trước khi merge vào `main`):

1. Lấy `taskId` từ trường `taskId` trong `.aiflow/context/current.json`.
2. Kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`).
3. Nếu **đã** ở `feature/[taskId]` (hoặc `feature/[taskId]-<mô-tả>` của đúng task này — ví dụ resume từ session trước) → bỏ qua, tiếp tục.
4. Nếu **chưa**: liệt kê branch đã có của task — `git -C AK-Docs branch --list "feature/[taskId]" "feature/[taskId]-*"`:
   - **Chưa có branch nào** → hỏi QA: "Chưa có branch riêng cho task này trong AK-Docs. Tạo branch `feature/[taskId]` từ `main` — đồng ý không?" → QA đồng ý thì chạy `ak docs branch [taskId] --yes`.
   - **Đã có branch cho task này** → hỏi QA chọn 1 trong 2: làm tiếp trên branch cũ (`ak docs branch [taskId] --reuse --yes`), hoặc tạo branch mới có hậu tố mô tả phần việc lần này (`ak docs branch [taskId] <mô-tả> --yes` → `feature/WONDER-1071-create-ui`, `feature/WONDER-1071-update-backend`).
   - **QA từ chối** → tiếp tục Gate 1 trên nhánh hiện tại của AK-Docs (QA tự quản lý branch).

> ❗ Branch chỉ gồm `feature/[taskId]` — KHÔNG chèn functionId. Format cũ `feature/[functionId]/[taskId]` đã bỏ vì khi không suy ra được functionId nó sinh ra branch lặp `feature/WONDER-1071/WONDER-1071`.
> ❌ Không tự thêm `--yes` khi chưa thấy QA gõ xác nhận rõ ràng trong hội thoại.

#### Bước 0.6: Kiểm tra UC Spec & System Requirement (input bắt buộc, cảnh báo non-blocking)

**Mục tiêu:** Test Case phải được thiết kế dựa trên cả UC Spec (yêu cầu nghiệp vụ do BA chốt) **và** System Requirement (bản dịch kỹ thuật cho Dev — Validation Rule, Exception/Error Handling, Acceptance Test) — thiếu một trong hai, TC dễ bỏ sót case mà Dev đã implement hoặc case BA đã đặc tả.

1. Tìm UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (version cao nhất, không phải bản archive).
2. Tìm System Requirement: `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v*.md` (version cao nhất).
3. Nếu tìm thấy System Requirement, đọc 2 header của nó: `UC-Spec-Version` (phải khớp version UC Spec tìm được ở bước 1) và `Status` (phải là `✅ Approved`).

Nếu **bất kỳ** điều kiện sau không thỏa mãn → hiển thị cảnh báo tương ứng, **không dừng/không cancel Gate 1** — vẫn tiếp tục với dữ liệu hiện có:

| Tình huống | Cảnh báo hiển thị |
|---|---|
| Không tìm thấy UC Spec | `⚠️ CẢNH BÁO: Không tìm thấy UC Spec cho [functionId] — Test Case sẽ chỉ dựa trên System Requirement (nếu có) + input khác, thiếu ngữ cảnh nghiệp vụ gốc.` |
| Không tìm thấy System Requirement | `⚠️ CẢNH BÁO: Không tìm thấy System Requirement cho [functionId] — Test Case sẽ chỉ dựa trên UC Spec, có thể thiếu Validation Rule/Exception Handling/Acceptance Test mà Dev đã chốt riêng.` |
| Có System Requirement nhưng `UC-Spec-Version` không khớp UC Spec hiện tại | `⚠️ CẢNH BÁO: System Requirement đang trace theo UC Spec v[X], nhưng UC Spec hiện tại là v[Y] — nội dung có thể lỗi thời.` |
| Có System Requirement, khớp version, nhưng `Status` ≠ `✅ Approved` | `⚠️ CẢNH BÁO: System Requirement cho [functionId] chưa Approved (Status: [giá trị hiện tại]) — nội dung có thể còn thay đổi.` |

→ Với mọi cảnh báo trên: ghi lại tình huống này vào Test Plan mục 1.7 (Giả định & giới hạn) để QA/Dev biết rõ giới hạn của phân tích — không chỉ hiển thị rồi bỏ qua.

Nếu tất cả điều kiện thỏa mãn → thông báo ngắn rồi tiếp tục:

```
✓ UC Spec: v[N]
✓ System Requirement: v[N] (✅ Approved, khớp UC Spec v[N])
→ Tiếp tục Gate 1...
```

**Xác định Mode (CREATE / UPDATE) — BẮT BUỘC, chạy ngay sau bước kiểm tra ở trên:**

> Trả lời Vấn đề B ở `docs/internal/Token Problems.md` (§2.2/§3.2) — trước bản này, `create-testcase` không kiểm tra TestCase cũ đã tồn tại, nên mỗi lần UC Spec/System Requirement bump version, cả 4 Gate chạy lại từ đầu cho toàn bộ UC dù chỉ 1 BR đổi.

1. Tìm `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md` đã tồn tại chưa. Nếu có, đọc header **UC-Spec-Version**/**System-Requirement-Version** của nó (Mục 1, xem `testcase-template.md`).
2. **Không tồn tại** → Mode = **CREATE**. Hành vi giữ nguyên như trước — chạy đủ 4 Gate cho toàn bộ UC.
3. **Tồn tại, `UC-Spec-Version` khớp UC Spec hiện tại (và `System-Requirement-Version` khớp, nếu có System Requirement)** → không cần chạy lại — báo QA: "TestCase cho `functionId` này đã khớp UC Spec/System Requirement hiện tại, không cần chạy `create-testcase` lại."
4. **Tồn tại, `UC-Spec-Version` hoặc `System-Requirement-Version` cũ hơn hiện tại** → Mode = **UPDATE**. Dùng **Change Log** của `UC-Spec_v{N}.md` (mục 6, xem `skill-ba-uc-template-v1.md`) và/hoặc `System-Requirement_v{N}.md` (Section 9) để xác định chính xác Flow/BR/FR/VR/ER nào đổi giữa version cũ (mà TestCase đang trace) và version hiện tại — đây là phạm vi delta cho Gate 2/3 bên dưới.

⚠️ **Chưa "triệt để" 100%** (xem §4 tài liệu trên) — Mode UPDATE kế thừa đúng rủi ro của Mode UPDATE ở `create-spec`, cộng thêm rủi ro riêng: TC mới cho BR đổi có thể bỏ sót **tổ hợp** giữa BR mới và BR không đổi (combinatorial). Gate 4 Bước 1 bên dưới có checklist riêng cho việc này — không được bỏ qua.

5. **Strategy đổi version:** TestCase đã tồn tại có header `Test-Strategy-Version` cũ hơn `Strategy-Version` hiện tại của `Test-Strategy.md` (kiểm ở Bước 0.7) → Mode = **UPDATE** kể cả khi UC Spec không đổi. Phạm vi delta = mọi TC bị ảnh hưởng bởi phần strategy thay đổi (vd thêm ngôn ngữ EN với chính sách `split` → sinh thêm toàn bộ bộ TC EN; đổi thiết bị từ `sample` sang `column` → thêm cột kết quả cho mọi TC).

#### Bước 0.7: Test Strategy của dự án — AI suy luận trước, QA chỉ chốt phần chính sách

**Mục tiêu:** số lượng và cách tách Test Case phụ thuộc vào chiến lược test của dự án. Trước đây bước này hỏi QA **toàn bộ** các mục, kể cả những mục AI tự tìm hiểu được (URL môi trường, cách chuẩn bị dữ liệu, breakpoint, trình duyệt, phạm vi chạy từng môi trường) — QA phải trả lời hàng chục câu confirm cho những thứ đã nằm sẵn trong repo hoặc có mặc định hợp lý. Bước này giờ chia làm hai loại (xem 3 mức trong `test-strategy-template.md`):

| Loại | Cách xử lý | Chặn Gate 1? |
|---|---|---|
| `[AI SUY LUẬN]` | AI **tự tìm hiểu và tự điền**, kèm nguồn. Không có bằng chứng → dùng giá trị mặc định ghi sẵn trong template. **Cấm hỏi QA từng mục này.** | ❌ Không |
| `[CHỐT]` | AI vẫn phải **đề xuất sẵn giá trị + lý do**; QA chỉ cần trả lời `ĐỒNG Ý` hoặc sửa vài dòng. | ✅ Có — nhưng chỉ **một** lần hỏi gộp |

1. **Tìm file:** `AK-Docs/03.Testing/00.Strategies/Test-Strategy.md`. Chưa có → copy `.claude/skills/test-skills/template/test-strategy-template.md` tới đó (AK-Docs đã ở branch của task nhờ Bước 0.5).

2. **Bước tự tìm hiểu (BẮT BUỘC, làm trước khi hỏi bất kỳ câu nào).** Với **mọi** mục `[AI SUY LUẬN]` còn trống/placeholder, AI phải quét các nguồn sau rồi tự điền `<giá trị> [AI — nguồn: <đường dẫn/tài liệu>]`; không tìm thấy gì → điền giá trị mặc định của mục đó và ghi `[AI — mặc định]`:

   | Mục | Nguồn phải quét trước khi kết luận |
   |---|---|
   | Domain nghiệp vụ | UC Spec, mô tả ticket, `README`, tên module trong repo |
   | 1.1 Trình duyệt PC | `browserslist`/`package.json`, config Playwright–Cypress, tài liệu trong `00.Strategies/` |
   | 1.2 Thiết bị mobile | Prototype/UC Spec có layout mobile không, repo có React Native/Flutter/WebView không |
   | 1.3 Responsive | `tailwind.config.*`, biến SCSS, `@media` trong CSS, prototype |
   | 1.4 Môi trường + phạm vi chạy | `.env*`, `README`, config CI/CD, tài liệu môi trường trong `AK-Docs/` (mặc định: Staging = Full, Dev = Critical + High) |
   | 2 Ngôn ngữ, ngôn ngữ chính | File i18n (`locales/`, `messages/`, `i18n/*.json`, `*.po`), ngôn ngữ text trong UC Spec |
   | 4 Loại test, xác minh DB/API, tamper | Repo có tầng API / test E2E sẵn không; UC Spec có gọi API/ghi DB không |
   | 5 Cách chuẩn bị dữ liệu | Script seed/fixture/factory, màn Admin tạo được dữ liệu, API tạo dữ liệu, faucet testnet |
   | 5 Tài khoản test | Tài liệu/sheet tài khoản đã có trong `AK-Docs/`; không có → mặc định "TC ghi theo vai trò" |
   | 6 Ngôn ngữ viết TC | Ngôn ngữ các tài liệu `AK-Docs/` hiện có của dự án |

   ❌ Không được hỏi QA một mục `[AI SUY LUẬN]` khi chưa quét hết nguồn tương ứng. Quét xong vẫn không có bằng chứng → **dùng mặc định, vẫn không hỏi.**

3. **Xác định các mục `[CHỐT]` còn thiếu** (chỉ 3 nhóm, tất cả đều nhân/tách số lượng TC):
   - Mục 2 — "Phạm vi lặp cho ngôn ngữ phụ" (chỉ khi mục 2 có > 1 ngôn ngữ).
   - Mục 3 — bảng Dimension Policy (gồm dòng "Biến thể nghiệp vụ": đối chiếu UC Spec / System Requirement, UC có biến thể rõ ràng — nhiều currency, nhiều loại thành viên, bật/tắt OTP — mà bảng chưa có dòng tương ứng → coi là thiếu).
   - Mục 4 — "Tiêu chí PASS cho giao dịch bất đồng bộ" (chỉ khi UC có async / blockchain / webhook).

   Với **từng** mục thiếu, AI phải tự điền sẵn giá trị đề xuất kèm lý do một dòng — QA không phải nghĩ từ đầu.

4. **Hỏi đúng MỘT lần, gộp toàn bộ vào một khối** (đây là biểu mẫu, không phải chuỗi câu hỏi — ngoại lệ có chủ đích của Interaction Rule "một câu một lần"):

   ```
   📋 XÁC NHẬN TEST STRATEGY — trả lời 1 lần là xong
   File: AK-Docs/03.Testing/00.Strategies/Test-Strategy.md (Strategy-Version: <vN hoặc "mới tạo">)

   ① CẦN BẠN CHỐT (ảnh hưởng trực tiếp số lượng Test Case)

   | # | Mục | AI đề xuất | Vì sao đề xuất vậy | Nếu đổi |
   |---|-----|-----------|--------------------|---------|
   | 1 | Lặp ngôn ngữ phụ (JP chính, EN phụ) | ui-text | Logic nghiệp vụ không đổi theo ngôn ngữ trong UC Spec | full → nhân đôi toàn bộ TC |
   | 2 | Chiều "Biến thể nghiệp vụ" (AUBE/OWL/ETH) | split | 3 token có ràng buộc phí khác nhau (UC Spec mục 4.2) | column → 1 TC, 3 cột kết quả |
   | 3 | Chiều "Thiết bị" (PC/Android/iPhone) | column | Cùng kịch bản, chỉ khác nơi chạy | split → nhân 3 số TC |
   | 4 | Domain nghiệp vụ → domain skill nạp | Blockchain-Wallet-Staking.md + NFT-Gacha-Marketplace.md | UC nhắc ví custodial, USDC và lượt quay Gacha | bỏ 1 file → mất sàn bao phủ của domain đó |

   ② AI ĐÃ TỰ ĐIỀN (không cần trả lời — chỉ sửa nếu sai)

   | Mục | Giá trị | Nguồn |
   |------|---------|-------|
   | Môi trường | Staging = Full, Dev = Critical + High | mặc định |
   | Cách chuẩn bị dữ liệu | Qua API | tests/helpers/api-client.ts |
   | Ngôn ngữ | JP (chính), EN | src/i18n/{ja,en}.json |
   | Trình duyệt PC | Chrome latest | mặc định |
   | ... | ... | ... |

   Trả lời:
   • "ĐỒNG Ý" → chốt toàn bộ như trên, chạy tiếp ngay.
   • Hoặc chỉ ghi số cần đổi: "1: full; 3: split" — phần còn lại giữ nguyên.
   ```

   - **"ĐỒNG Ý" / "OK" / "cứ làm đi" / "tuỳ AI" = chốt toàn bộ đề xuất.** Ghi giá trị vào file, xoá mọi marker `[AI — ...]` ở các mục `[CHỐT]` (giữ marker ở mục `[AI SUY LUẬN]` để truy vết nguồn), điền `Người chốt` = người vừa trả lời, `Ngày chốt` = hôm nay, tăng `Strategy-Version`.
   - QA chỉ sửa vài dòng → áp dụng đúng phần đó, phần còn lại coi như đã chốt. **Không hiển thị lại toàn bộ biểu mẫu.**
   - **Tối đa 1 vòng hỏi lại**, và chỉ khi câu trả lời cho một mục `[CHỐT]` mơ hồ tới mức không map được vào `split`/`column`/`sample` (vd "test mobile nữa nhé"). Hỏi đúng một câu cho toàn bộ chỗ mơ hồ đó. Vẫn mơ hồ sau vòng này → áp dụng đề xuất của AI, ghi `[ÁP DỤNG ĐỀ XUẤT — QA chưa chốt rõ]` vào file và vào mục "Test Strategy áp dụng", rồi chạy tiếp.
   - ❌ **KHÔNG** hỏi lại các mục ở khối ②. ❌ **KHÔNG** sinh artifact Gate 1 (Bước 1 trở đi) khi khối ① chưa được trả lời.

5. **Đã đủ** → hiển thị tóm tắt rồi tiếp tục:

   ```
   ✓ Test Strategy: <Strategy-Version> (chốt bởi <Người chốt>, <Ngày chốt>)
   ✓ Domain: <Domain nghiệp vụ> → domain skill áp dụng: <file trong 08-domain-skills/ hoặc "không có">
   ✓ Chiều split: Ngôn ngữ [JP, EN — phụ: ui-text] × Biến thể [AUBE, OWL, ETH] × OTP [on, off]
   ✓ Chiều column: Thiết bị [PC-Chrome, Android-Chrome, iPhone-Safari]
   ✓ Chiều sample: Trình duyệt PC [Chrome]
   ✓ AI tự điền (QA chưa rà): Môi trường, Cách chuẩn bị dữ liệu, Responsive breakpoint
   → Tiếp tục Gate 1...
   ```

   - Ghi toàn bộ tóm tắt này — **kèm danh sách mục AI tự điền và nguồn của từng mục** — vào Test Plan mục **1.5 "Test Strategy áp dụng"** (Bước 3). Gate 2/3/4 đọc lại từ đây, không đọc lại toàn bộ `Test-Strategy.md`.
   - Compatibility (trình duyệt / thiết bị) lấy trực tiếp từ strategy, không suy diễn thêm.
   - Nếu strategy có "Nguồn regression bắt buộc đọc" (mục 6) → đọc danh sách bug/ticket ở Bước 1, ghi vào Test Plan mục 1.6 (Risk Matrix) để Gate 3 sinh TC regression cho từng bug.

#### Bước 1: Đọc và tổng hợp đầu vào
- Đọc `.aiflow/context/current.json` — tiêu đề, mô tả, acceptance criteria, liên kết tài liệu
- Đọc `UC-Spec_v{N}.md` (tìm thấy ở Bước 0.6) — yêu cầu nghiệp vụ gốc: Main/Alternative/Exception Flow, Business Rules (BR-NNN), UI Components
- Nếu tìm thấy `System-Requirement_v{N}.md` ở Bước 0.6 → đọc toàn bộ, dùng làm input kỹ thuật bổ sung cho Bước 2 (Phân tích yêu cầu): đối chiếu Functional/Non-Functional Requirements (`FR-*`, `NFR-*`), Validation Rules (`VR-*`), Exception & Error Handling (`ER-*`), Acceptance Test Scenarios (`AT-*`) — TC ở Gate 3 phải bao phủ cả các `AT-*`/`ER-*` này, không chỉ Business Rules trong UC Spec
- Nếu description có URL → chạy `ak fetch-links <url>` để tải nội dung
- Nếu có `supplementaryContext[]` → đọc từng item (SRS file, Figma link, API spec, spec MD file)
- Nếu có file yêu cầu thô được chỉ định → đọc file đó

**Mode UPDATE:** đọc thêm `[functionId]_TestCase.md` hiện có (bản trước khi update) làm baseline — TC map tới BR/FR **không đổi** (theo Change Log đã đọc ở Bước 0.6) được giữ nguyên xuyên suốt Gate 2–4, chỉ TC map tới phần **đổi/mới** mới đi qua lại pipeline đầy đủ.

#### Bước 1.5: Dev Artifacts Check (PR/Commit-based)

**Mục tiêu:** xác định **chính xác** phạm vi code đã thay đổi cho ticket này, để mở rộng coverage (regression scope) mà **không** phải tự dò/đọc toàn bộ branch đang phát triển của feature (tốn token, tốn thời gian, dễ đọc nhầm code chưa xong).

1. Kiểm tra ticket/context có PR link đính kèm không (`.aiflow/context/current.json`, mô tả ticket).
2. **Có PR link, hoặc TESTER đã khai báo `PR: <url>` trong chat** → **INVOKE** skill `pr-impact-analysis` ngay, dùng PR đó.
3. **Chưa có PR/commit nào được biết** → hỏi TESTER **một câu duy nhất**:

```text
Để xác định đúng phạm vi ảnh hưởng code (tránh phải rà toàn bộ branch), bạn cung cấp giúp PR link hoặc commit SHA/branch name của thay đổi cho ticket này (có thể nhiều PR/commit nếu multi-repo). Nếu chưa có, gõ "chưa có" để bỏ qua bước này.
```

4. Xử lý câu trả lời của TESTER:
   - Cung cấp PR/commit/branch → **INVOKE** skill `pr-impact-analysis` với thông tin đó (dùng fallback `git fetch` + `git diff main...<branch>` nếu không phải PR).
   - Trả lời "chưa có" → ghi nhận vào `test-plan/impact-analysis.md` (hoặc tương đương) "chưa có dev artifacts — sẽ re-check ở Gate 3", **không block Gate 1**.
5. Kết quả `pr-impact-analysis` (màn hình ảnh hưởng trực tiếp/gián tiếp, đề xuất regression TCs) được dùng làm input bổ sung cho Bước 2 và Gate 2 (Scenario Building) — **không** dùng để xác định expected result (vẫn lấy từ ticket/UC Spec/System Requirement).

> ❌ **KHÔNG** tự ý `git branch -a`, checkout, hoặc đọc lần lượt nhiều branch để tìm "code đang phát triển" — luôn đi qua PR/commit cụ thể mà TESTER xác nhận, qua skill `pr-impact-analysis`.
> Ở Gate 3 (trước khi thiết kế TC chi tiết), re-run bước này nếu đã có `impact-analysis.md` từ Gate 1 — dùng Delta Detection của `pr-impact-analysis` (so SHA cũ/mới) để bắt commit mới, không đọc lại toàn bộ diff.

#### Bước 2: Phân tích yêu cầu và đánh giá rủi ro
- **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md` — đọc trước để nắm quy ước chung
- **READ rule:** `custom/rules/document-wording.md` — chuẩn hành văn + nguyên tắc mỗi mục tự chứa đủ nội dung
- **READ rule:** `custom/rules/domain-terminology.md` + `AK-Docs/00.Project-Overview/Glossary.md` — lập danh sách thuật ngữ UC Spec / QnA-Log đã dùng (actor, phân hệ, menu, màn hình, nút); mọi artifact sau dùng đúng danh sách đó
- **READ rule:** `custom/rules/ui-action-wording.md` — động từ thao tác UI, trạng thái UI, thuật ngữ IT chuẩn
- **READ (nếu có):** `AK-Docs/03.Testing/00.Strategies/Review-Feedback-Rules.md` — các rule reviewer đã chốt ở những ticket trước (xem `gate-review` skill, Mode 3). Rule trong file này **bắt buộc** như `qa-writing-standards.md`; không có file → bỏ qua, không hỏi lại
- **READ skill:** `.claude/skills/test-skills/categories/00-core/00.01.requirement-analysis.md`
- **READ skill:** `.claude/skills/test-skills/categories/00-core/00.02.risk-analysis.md`
- **Xác định domain skill (BẮT BUỘC):** lấy "Domain nghiệp vụ" từ `Test-Strategy.md` (Bước 0.7) **và** rà UC Spec / System Requirement / code theo mục "Khi nào áp dụng" ở đầu từng file trong `.claude/skills/test-skills/categories/08-domain-skills/`. Khớp file nào → **READ** file đó ngay tại Gate 1 (mục kiến thức nền + câu hỏi bắt buộc làm rõ của domain) và ghi tên file vào Test Plan mục 1.4 "Domain skill áp dụng". Gate 2/3/4 bắt buộc đọc lại đúng các file này — không phải tuỳ chọn.
  - Ví dụ: UC nhắc ví custodial, gas, `tx_hash`, stake/claim → `Blockchain-Wallet-Staking.md`; đưa các câu D-01..D-07 chưa có đáp án trong tài liệu vào hàng đợi hỏi của Bước 2b.
  - Ví dụ: UC nhắc quay Gacha, lootbox, tỉ lệ rơi, mint NFT, `tokenId`, metadata/IPFS, danh sách lượt trúng gần đây → `NFT-Gacha-Marketplace.md` (câu G-01..G-10). Gacha thanh toán bằng token → nạp **cả hai** file, không chọn một.
  - **Khớp nhiều domain thì nạp hết.** Coverage floor của từng file cộng dồn, không thay thế nhau.
- **Đối chiếu spec với code đang chạy** (khi có quyền đọc source): với mỗi giá trị mặc định, điều kiện chặn, error code quan trọng, so UC Spec với code. Lệch → ghi thành câu hỏi 🔴 Blocking trong QnA Log, hỏi QA chốt bên nào đúng — không tự chọn spec (ví dụ thực tế: spec ghi OTP mặc định Unchecked, code mặc định Checked).
- Phân tích theo 16 mục của skill 00.01 để **tìm** điểm thiếu, mâu thuẫn và rủi ro — nhưng **chỉ ghi ra** những gì UC Spec / System Requirement chưa có:
  - **Đọc, không chép:** mục 4 Main Flow, 5 Alternative Flows, 7 Business Rules, 8 Validations, 9 State, 10 API đã nằm trong UC Spec / System Requirement đã Approved. Không chép lại các mục này vào Test Plan — chỗ nào cần nhắc thì dẫn ID gốc (`BR-xx`, `VR-xx`, `FR-xx`, `ER-xx`, `AT-xx`). Gate 3 đọc thẳng UC Spec / System Requirement để lấy message và giá trị nguyên văn.
  - **Ghi vào Test Plan Phần 1:** phạm vi In/Out-of-Scope (mục 2), Actor & quyền (mục 6), biến thể nghiệp vụ, domain skill, Test Strategy áp dụng, Risk Matrix (mục 15 + đánh giá rủi ro), giả định & giới hạn.
  - **Ghi vào QnA Log:** mọi điểm chưa rõ / mâu thuẫn (mục 16).
  - Không có UC Spec / System Requirement (Bước 0.6 cảnh báo thiếu) → nội dung nào chỉ có trong ticket / SRS / file khác thì mới tóm tắt vào Test Plan mục 1.1–1.3, kèm nguồn.
- Đánh giá rủi ro theo skill 00.02: kỹ thuật, dữ liệu, nghiệp vụ, hệ thống

#### Bước 2b: Đào sâu làm rõ với QA/Stakeholder (Interactive Clarification)
**Mục tiêu:** xử lý dứt điểm mọi mơ hồ/nghi vấn ngay tại Gate 1 — đây là gate DUY NHẤT được phép dừng lại hỏi tự do; Gate 2-4 sau đó chỉ hỏi cho phát sinh thực sự mới (xem quy tắc ở các Gate đó).

- **🔴 Blocking** → **KHÔNG** chỉ ghi vào QnA Log rồi im lặng chờ. Hỏi ngay trong hội thoại theo đúng Interaction Rule đã khai báo (hỏi **TỪNG CÂU MỘT**, đợi QA trả lời rồi mới hỏi câu tiếp theo, KHÔNG hỏi dồn nhiều câu):
  - **Trước khi hỏi câu đầu tiên:** điền trường `Phụ thuộc` cho mọi nghi vấn và sắp thứ tự hỏi theo [Quy tắc đặt câu hỏi mục A](#a-phụ-thuộc-giữa-các-câu-hỏi--không-hỏi-câu-bị-chặn) — câu cha trước câu con, 🔴 Blocking trước 🟡 Non-blocking.
  - Với mỗi nghi vấn phát sinh trong lúc phân tích, ưu tiên đề xuất 2-3 cách hiểu/giả định hợp lý để QA chọn nhanh (multiple-choice) thay vì hỏi mở.
  - **Trước mỗi câu, chạy self-check mục E** (đáp án đổi output nào / đã quét nguồn chưa / người không technical hiểu được không / đã trả lời hoặc suy ra được chưa / có bị chặn không). Trượt ý nào → không hỏi, ghi lý do vào QnA Log (`Suy ra từ TQ-xx` / `Blocked-by TQ-xx`) hoặc ghi giả định vào Test Plan mục 1.7.
  - Hỏi trong chat bằng **dạng gọn** của template QnA-Log (khoảng 12 dòng; QA gõ `chi tiết` thì in khối đầy đủ). Nội dung theo [mục B](#b-chất-lượng-câu-hỏi--dễ-hiểu-cho-người-không-chuyên-kỹ-thuật): đủ Bối cảnh (kèm ảnh hưởng nếu chưa chốt) / Câu hỏi một ý / Options kèm hệ quả và đề xuất, giải nghĩa mọi viết tắt, thêm "Ví dụ minh họa" nếu câu hỏi phức tạp. **Không** viết mục "Vì sao cần hỏi" riêng.
  - Sau **mỗi** câu trả lời: ghi khối đầy đủ vào QnA Log (trạng thái `Confirmed`, Người trả lời / Ngày / Nguồn), ghi quyết định + hệ quả suy ra vào bảng ở [mục C](#c-chống-hỏi-trùng--suy-ra-từ-câu-trả-lời-đã-có), rà lại các câu chưa hỏi — câu nào đã được bao phủ thì đóng `Suy ra từ TQ-xx`, không hỏi; câu con của câu vừa được trả lời thì mở khoá.
  - Tiếp tục hỏi tuần tự, đào sâu thêm nếu câu trả lời còn hé lộ nghi vấn mới, cho đến khi **không còn 🔴 Blocking nào chưa rõ** (nghi vấn ở trạng thái `Blocked-by TQ-xx` do câu cha chưa trả lời không tính là "chưa hỏi").
  - Không ghi Test Plan Phần 1 (Bước 3) trước khi toàn bộ 🔴 Blocking đã được làm rõ.
- **🟡 Non-blocking** → ghi vào QnA Log trạng thái `Open`, đặt marker `[PENDING - TQ-xx]` tại chỗ liên quan trong Test Plan, tiếp tục, carry-forward sang gate sau (không cần dừng hỏi).

#### Bước 3: Soạn Test Plan — Thông tin chung + Phần 1 (Phân tích)
- **READ template:** `.claude/skills/test-skills/template/test-plan-template.md`
- Điền bảng **Thông tin chung** (functionId, UC-Spec-Version, System-Requirement-Version, Test-Strategy-Version, Mode) và **Phần 1**: 1.1 Phạm vi kiểm thử, 1.2 Actor & quyền, 1.3 Biến thể nghiệp vụ (vd currency AUBE / OWL / ETH, kèm khác biệt logic), 1.4 Domain skill áp dụng, 1.5 Test Strategy áp dụng (tóm tắt ở Bước 0.7 bước 5), 1.6 Risk Matrix, 1.7 Giả định & giới hạn
- Không chép Main Flow / Alt Flow / Business Rules / Validations / State / API (xem Bước 2) — dẫn ID gốc
- Mode UPDATE: Test Plan đã có → cập nhật tại chỗ, không tạo file mới
- Lưu: `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md`

#### Bước 4: Hoàn tất QnA Log
- QnA Log đã được ghi dần ở Bước 2b. Bước này rà lại: mọi câu đã hỏi có khối đầy đủ theo template `skill-ba-qna-template-v1.md` (mã `TQ-xx`), trạng thái đúng (`Open` / `Confirmed` / `Blocked-by TQ-xx`), bảng **Quyết định đã chốt + hệ quả suy ra** cập nhật, "Lịch sử cập nhật tài liệu" có dòng cho Gate 1
- Không có câu hỏi nào → không tạo file
- Lưu: `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md`

#### Bước 5: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — dừng gate chờ QA đọc output (không tạo checklist để tick)
- Hiển thị gate pause message — đợi **APPROVED**

**Khi APPROVED:**
→ **INVOKE** `gate-review` skill (verify mode) — chạy `ak review check --gate 1 --ticket [functionId]`
→ Nếu passed: `ak gate 1 approved --ticket [functionId]` → cập nhật dòng `[functionId]` trong `AK-Docs/00.Project-Overview/Function-List.md` thành `QA 🔵` (theo `custom/rules/function-list-status.md`) → chuyển Gate 2
→ Nếu blocked: làm theo gate-review skill response protocol

**Definition of Done** (AI tự kiểm trước khi dừng gate — QA không phải tick, không đưa danh sách này cho QA):
- [ ] Thuật ngữ khớp UC Spec / QnA-Log / Glossary (`custom/rules/domain-terminology.md`): không từ đồng nghĩa, không tên phân hệ / menu tự đặt, không chữ tiếng Nhật đứng một mình
- [ ] Động từ thao tác UI và thuật ngữ IT theo `custom/rules/ui-action-wording.md`: grep `bấm|nhấn nút|ấn nút|tích chọn|bỏ tích|chọn tay|gõ vào|điền vào|ô nhập|hộp xác nhận|thông báo góc|khung lỗi|rời ô|kéo thả|di chuột|máy chủ|bộ nhớ đệm|chuyển hướng` — 0 hit ngoài chữ gốc trích nguyên văn
- [ ] `functionId` đã được xác định, thư mục đầu ra đã sẵn sàng
- [ ] Đã chạy Bước 0.6 (kiểm tra UC Spec + System Requirement); nếu có cảnh báo, đã ghi vào Test Plan mục 1.7
- [ ] Đã chạy Bước 0.7: mọi mục `[CHỐT]` của `Test-Strategy.md` đã được QA trả lời (hoặc ghi `[ÁP DỤNG ĐỀ XUẤT — QA chưa chốt rõ]`); mọi mục `[AI SUY LUẬN]` đã có giá trị kèm nguồn `[AI — ...]`; tóm tắt strategy + danh sách mục AI tự điền đã ghi vào Test Plan mục 1.5
- [ ] Đã xác định và đọc domain skill áp dụng (hoặc ghi rõ "không có domain skill phù hợp")
- [ ] Test Plan có đủ Thông tin chung + Phần 1 (1.1–1.7) theo `test-plan-template.md`
- [ ] Test Plan **không** chép lại Main Flow / Alt Flow / Business Rules / Validations / State / API của UC Spec / System Requirement — chỉ dẫn ID gốc
- [ ] Toàn bộ 🔴 Blocking đã được hỏi trực tiếp (từng câu một) và có câu trả lời từ QA — không còn nghi vấn bỏ ngỏ (trừ câu đang `Blocked-by TQ-xx` theo câu cha chưa trả lời)
- [ ] Không có câu hỏi nào được phát ra khi câu cha còn chưa trả lời, và không có câu nào hỏi lại điều đã chốt hoặc suy ra được (bảng Quyết định đã chốt)
- [ ] Mọi câu hỏi đã gửi đều có đủ Bối cảnh (kèm ảnh hưởng nếu chưa chốt) / Câu hỏi một ý / Options kèm hệ quả, viết tắt đã giải nghĩa, câu phức tạp có ví dụ minh họa
- [ ] Không câu hỏi nào còn mục "Vì sao cần hỏi" tách riêng
- [ ] QnA Log (nếu có câu hỏi) đúng format `skill-ba-qna-template-v1.md`, mã `TQ-xx`, ghi đủ câu hỏi + câu trả lời của Bước 2b
- [ ] Không có giả định nào được tự ý chốt thành fact — giả định nằm ở Test Plan mục 1.7 hoặc QnA Log
- [ ] **Viết cho người đọc nghiệp vụ** (`document-wording.md` mục 3): mọi kết luận lấy từ code được viết thành câu nghiệp vụ tự đủ nghĩa + dòng/cột `Source code:` làm bằng chứng. Chạy `ak tc lint --doc` trên Test Plan và QnA Log, 0 `error`; mỗi `warn` xử lý hoặc ghi lý do vào Test Plan mục 1.7
  ```bash
  ak tc lint --doc "AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md" "AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md"
  ```

> **Telemetry:** Run `ak gate 1 start --ticket [functionId]` khi bắt đầu gate này.
> Run `ak gate 1 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.

---

### GATE 2 — Test Plan (Scenario Building)

**Mục tiêu:** Phác thảo các kịch bản kiểm thử mức cao (High-level Scenarios) bao phủ toàn bộ luồng nghiệp vụ, trường hợp ngoại lệ và các rủi ro đã nhận diện ở Gate 1.

**Điều kiện vào Gate 2:** Gate 1 đã **APPROVED** và Test Plan Phần 1 đã hoàn chỉnh.

**Đầu vào (Inputs):**
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md` (Phần 1)
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md` (bảng Quyết định đã chốt)
- UC Spec + System Requirement (đọc thẳng Flow / BR / FR / VR / ER / AT)

**Đầu ra (Outputs):**
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md` — Phần 2 (Scenario)
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md` — chỉ khi có câu hỏi thực sự mới

> Gate 2 là checkpoint rẻ (~60 KB) để QA duyệt phạm vi và chiều `split` / `column` / `sample` — quyết định nhân trực tiếp ra số TC — **trước** phần đắt nhất là viết TC ở Gate 3. Không gộp Gate 2 vào Gate 1 hay Gate 3.

**Bước thực hiện:**

**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.

#### Bước 1: Đọc artifact đầu vào
- Đọc Test Plan Phần 1 — phạm vi, actor, biến thể, Test Strategy áp dụng, Risk Matrix
- Đọc UC Spec + System Requirement — Main / Alternative / Exception Flow, Business Rules, `FR-*`, `VR-*`, `ER-*`, `AT-*` (Test Plan không chép lại các phần này)
- Đọc bảng "Quyết định đã chốt" trong QnA Log

#### Bước 2: Áp dụng skills xây dựng kịch bản (luôn áp dụng)
- **READ skill:** `.claude/skills/test-skills/categories/_gate2-always-apply.md` (gộp 00.03.test-scenario-builder + 01.06.error-guessing + 03.02.workflow-testing — xem ghi chú đầu file gộp)
- **READ domain skill** đã ghi ở Test Plan mục 1.4 "Domain skill áp dụng" (BẮT BUỘC nếu có). Mọi viewpoint trong phần "coverage floor" của domain skill phải xuất hiện thành ≥ 1 scenario, hoặc được ghi `N/A — <lý do>` trong Draft RTM.
- Xây dựng kịch bản đa chiều:
  - Happy Path (Main Flow)
  - Negative scenarios
  - Boundary conditions
  - Exception scenarios (double-click, timeout, mất mạng)
  - Permission / Role-based scenarios
  - E2E (End-to-End) business flow

#### Bước 3: Áp dụng skills có điều kiện
- **[Nếu có status/lifecycle field]** READ: `.claude/skills/test-skills/categories/01-test-design/01.04.state.transition.md` — thiết kế kịch bản cho mọi transition hợp lệ và không hợp lệ
- **[Nếu phụ thuộc feature/service khác]** READ: `.claude/skills/test-skills/categories/03-business-testing/03.04.dependency-validation.md` — kịch bản khi dependency lỗi
- **[Nếu có notification trigger]** READ: `.claude/skills/test-skills/categories/03-business-testing/03.05.notification-testing.md`

#### Bước 4: Soạn Test Plan Phần 2 (Scenario)
- Ghi vào Test Plan, `## Phần 2 — Scenario (Gate 2)`, đúng tên cột của `test-plan-template.md` (`ak tc build --plan` đọc bảng 2.1 theo cột `Scenario ID`)
- Bảng 2.1 Danh sách scenario với format:
  - Scenario ID: `TS_<SCREEN_NUMBER>_<SEQ>` (vd: `TS_06_001` cho AD06)
  - Cột: Scenario ID, Feature/Module, Check List, Scenario Type, Target Req ID, Priority, Test Data, **Chiều split áp dụng**, Nguồn
  - Scenario viết **một lần, trung lập với chiều split** (không nhân bản scenario theo ngôn ngữ / biến thể ở gate này). Cột "Chiều split áp dụng" ghi scenario sẽ được nhân theo chiều nào ở Gate 3: `Tất cả` (mặc định) · `Chỉ <giá trị>` (vd `Chỉ ETH` cho viewpoint riêng của native coin) · `Ngôn ngữ: chỉ chính` (logic không có text hiển thị, khi phạm vi ngôn ngữ phụ là `ui-text`).
- **2.2 Bảng Dự kiến số lượng TC** (để QA duyệt quy mô ngay từ Gate 2, tránh bất ngờ ở Gate 3 — số này cũng quyết định có chia agent ở Gate 3 hay không): số scenario × hệ số nhân của từng chiều split theo cột trên → tổng TC dự kiến. Ví dụ: 140 scenario, trong đó 120 nhân `Biến thể [3]`, 20 `Chỉ ETH`; ngôn ngữ phụ EN `ui-text` áp dụng cho 45 scenario → dự kiến `120×3 + 20 + 45×3 = 515` TC.
- 2.3 Business Flow Mapping (E2E diagram dạng text)
- 2.4 Draft RTM (Requirement ID của UC Spec / System Requirement → Scenario ID)
- **Mode UPDATE:** chỉ xây dựng scenario mới/đầy đủ cho phần Req ID **đổi/mới** (đã xác định ở Gate 1 Bước 0.6) — scenario map tới Req ID không đổi giữ nguyên nội dung từ Test Plan Phần 2 bản trước (không chạy lại Bước 2/3 cho phần này). Cột `Nguồn` (`carry-forward v{N_prev}` / `mới ở v{N}`) cho Gate 3/4 biết phần nào cần thiết kế lại.
- Lưu: `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md`

#### Bước 5: Ghi câu hỏi phát sinh vào QnA Log (NGOẠI LỆ)
- **Chỉ hỏi khi có vấn đề THỰC SỰ MỚI**, chỉ lộ ra khi xây dựng kịch bản (vd: một nhánh luồng nghiệp vụ không thấy được ở mức phân tích yêu cầu). **KHÔNG** hỏi lại điều đã có câu trả lời trong QnA Log hoặc giả định ở Test Plan mục 1.7 — đọc lại trước khi quyết định hỏi thêm.
- Ghi tiếp vào `[functionId]_QnA Log.md` (mã `TQ-xx` nối tiếp), thêm dòng "Lịch sử cập nhật tài liệu" cho Gate 2
- 🟡 Non-blocking → marker `[PENDING - TQ-xx]` + carry-forward, tiếp tục workflow

#### Bước 6: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — dừng gate chờ QA đọc output (không tạo checklist để tick)
- Hiển thị gate pause message — đợi **APPROVED**

**Khi APPROVED:**
→ **INVOKE** `gate-review` skill (verify mode) — chạy `ak review check --gate 2 --ticket [functionId]`
→ Nếu passed: `ak gate 2 approved --ticket [functionId]` → chuyển Gate 3
→ Nếu blocked: làm theo gate-review skill response protocol

**Definition of Done** (AI tự kiểm trước khi dừng gate — QA không phải tick, không đưa danh sách này cho QA):
- [ ] Thuật ngữ khớp UC Spec / QnA-Log / Glossary (`custom/rules/domain-terminology.md`): không từ đồng nghĩa, không tên phân hệ / menu tự đặt, không chữ tiếng Nhật đứng một mình
- [ ] Động từ thao tác UI và thuật ngữ IT theo `custom/rules/ui-action-wording.md`: grep `bấm|nhấn nút|ấn nút|tích chọn|bỏ tích|chọn tay|gõ vào|điền vào|ô nhập|hộp xác nhận|thông báo góc|khung lỗi|rời ô|kéo thả|di chuột|máy chủ|bộ nhớ đệm|chuyển hướng` — 0 hit ngoài chữ gốc trích nguyên văn
- [ ] 100% luồng Happy Path của UC Spec (Main Flow) đã bao phủ
- [ ] Có đủ Negative / Boundary / Exception / Permission scenarios
- [ ] Scenario ID format `TS_<SCREEN_NUMBER>_<SEQ>` đúng quy ước; bảng 2.1 đúng tên cột của `test-plan-template.md`
- [ ] Draft RTM mapping Requirement ID → Scenario đầy đủ
- [ ] Mọi viewpoint coverage floor của domain skill áp dụng đã có scenario hoặc `N/A — <lý do>`
- [ ] Mọi scenario có cột "Chiều split áp dụng"; có bảng Dự kiến số lượng TC
- [ ] Không còn câu hỏi 🔴 Blocking nào `Open` trong QnA Log
- [ ] Test Plan viết cho người đọc nghiệp vụ — chạy `ak tc lint --doc "<Test Plan>.md"` (và QnA Log nếu có thay đổi), 0 `error` (`document-wording.md` mục 3)

> **Telemetry:** Run `ak gate 2 start --ticket [functionId]` khi bắt đầu gate này.
> Run `ak gate 2 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.

---

### GATE 3 — Tạo testcase

**Mục tiêu:** Cụ thể hóa các kịch bản thành Test Case chi tiết với đầy đủ bước thực hiện, dữ liệu test và kết quả mong đợi cụ thể, đo được — bất kỳ ai cũng có thể thực thi được.

**Điều kiện vào Gate 3:** Gate 2 đã **APPROVED** và Test Plan Phần 2 đã hoàn chỉnh.

**Đầu vào (Inputs):**
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md` (Phần 1, Phần 2)
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md` (bảng Quyết định đã chốt)
- UC Spec + System Requirement — nguồn message, nhãn, giá trị **nguyên văn**

**Đầu ra (Outputs):**
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md` — dựng bằng `ak tc build` từ file part, **không** viết tay
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md` — Phần 3 (Coverage)
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md` — chỉ khi có câu hỏi thực sự mới

> **Bộ TC chỉ được viết một lần.** TC viết vào file part tạm trong `_parts/`, rồi `ak tc build` ghép thành `TestCase.md` bằng code. Agent chính **không** đọc lại rồi viết lại nội dung các part (đó là nguyên nhân hết quota ở WONDER-1156: 322 TC bị viết 3–4 lần). Gate 4 chỉ Edit đúng TC có finding.

**Bước thực hiện:**

**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.

#### Bước 0.7: Dev Artifacts Check — Delta Detection

Nếu `test-plan/impact-analysis.md` đã có PR/commit từ Gate 1 (Bước 1.5) → re-run `pr-impact-analysis` (Delta Detection): so SHA đã ghi với SHA hiện tại, nếu có commit mới thì chỉ đọc diff phần thêm mới, bổ sung TC nếu cần. Không có gì mới hoặc chưa từng có PR → bỏ qua, không cần hỏi lại TESTER.

> **Ai đọc Bước 1–5.5:** người viết TC — agent chính khi viết một mình, hoặc từng agent `tc-writer` khi chia agent (Bước 6). Agent `tc-writer` chỉ đọc phần quy tắc section mình cần (ví dụ section 3.3 cần phần Form Validation của `_gate3-ui-always-apply.md`, không cần phần CRUD); brief ghi rõ phần nào.

#### Bước 1: Đọc template và quy ước bắt buộc
- **READ template:** `.claude/skills/test-skills/template/testcase-template.md` — **BẮT BUỘC** tuân thủ 100%
- **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md`
- **READ rule:** `custom/rules/document-wording.md` — hành văn tự nhiên (không "cố/cố gắng/thử/tiến hành") + mỗi ô tự chứa đủ nội dung (không tham chiếu sang case khác, sang SRS/UC Spec/System Requirement/mail template, hay sang mục khác của tài liệu)
- **READ rule:** `custom/rules/domain-terminology.md` + `AK-Docs/00.Project-Overview/Glossary.md` — Test Case dùng đúng từ UC Spec / QnA-Log, không tự đặt tên phân hệ / menu
- **READ rule:** `custom/rules/ui-action-wording.md` — động từ thao tác UI, trạng thái UI, thuật ngữ IT chuẩn

#### Bước 2: Áp dụng kỹ thuật thiết kế TC cơ bản (luôn áp dụng)
- **READ:** `.claude/skills/test-skills/categories/_gate3-test-design-always-apply.md` (gộp 01.01 BVA + 01.02 EP + 01.03 Decision Table + 01.06 Error Guessing — xem ghi chú đầu file gộp)
  - 01.01 BVA — cho tất cả trường số/text có giới hạn
  - 01.02 EP — phân nhóm giá trị tương đương
  - 01.03 Decision Table — cho logic có nhiều điều kiện
  - 01.06 Error Guessing → toàn bộ section 3.5 Exceptions

#### Bước 3: Thiết kế TC UI (luôn áp dụng)
- **READ:** `.claude/skills/test-skills/categories/_gate3-ui-always-apply.md` (gộp 02.01–02.04 — xem ghi chú đầu file gộp)
  - 02.01 UI Layout — đối chiếu layout, spacing, font với Figma
  - 02.02 Form Validation — **MANDATORY** — ma trận validation TẤT CẢ trường input (cả Required và Optional)
  - 02.03 Navigation — TC truy cập URL, nút Back/Forward, Deep Link
  - 02.04 Localization — TC ký tự Kanji, Halfwidth/Fullwidth, đa ngôn ngữ

#### Bước 4: Thiết kế TC Business và Data (luôn áp dụng)
- **READ:** `.claude/skills/test-skills/categories/_gate3-business-data-always-apply.md` (gộp 03.01 + 03.03 + 04.01 + 04.04 — xem ghi chú đầu file gộp)
  - 03.01 CRUD Testing — CRUD flows
  - 03.03 Permission Testing — phân quyền theo Actor
  - 04.01 Database Testing — xác minh dữ liệu lưu đúng vào DB
  - 04.04 Duplicate Handling — ràng buộc Unique

#### Bước 5: Áp dụng skills có điều kiện
- **[Nếu có file upload field]** READ: `.claude/skills/test-skills/categories/05-integration/05.04.file-upload-download.md` — định dạng, dung lượng, MIME spoofing, drag & drop
- **[Nếu có status/lifecycle field]** READ: `.claude/skills/test-skills/categories/01-test-design/01.04.state.transition.md`
- **[Nếu nhiều tham số đầu vào cần tổ hợp]** READ: `.claude/skills/test-skills/categories/01-test-design/01.05.pairwise.md`
- **[Nếu có notification trigger]** READ: `.claude/skills/test-skills/categories/03-business-testing/03.05.notification-testing.md`
- **[Nếu có calculated/computed fields]** READ: `.claude/skills/test-skills/categories/03-business-testing/03.06.calculation.testing.md`

#### Bước 5.5: Domain skill & ma trận lỗi (BẮT BUỘC)
- **READ domain skill** đã ghi ở Test Plan mục 1.4 "Domain skill áp dụng" — thiết kế TC cho **từng** viewpoint coverage floor và áp dụng phần "Kỹ thuật thiết kế bắt buộc" của domain đó.
- **Ma trận Error code × Điểm submit** — luôn áp dụng khi flow có ≥ 2 điểm gửi dữ liệu lên server (vd bước Confirm và bước Verify OTP) hoặc có nhánh rẽ (bật/tắt OTP): hàng = mọi error code / message lỗi server của flow (lấy từ System Requirement `ER-*`, UC Spec và code), cột = mọi điểm có thể phát sinh lỗi đó (validate FE, từng bước submit ở từng nhánh, gọi API trực tiếp). Mỗi ô khả thi = 1 TC riêng; ô không khả thi ghi lý do. Agent chính lập ma trận ở Bước 6.1 (để giao TC cho đúng section) và ghi vào Test Plan mục 3.3. Lý do: cùng một lỗi (vd thiếu phí gas) phải được chặn đúng ở **mọi** điểm submit — test 1 điểm không chứng minh điểm còn lại.
- **Mỗi giá trị của phân vùng tương đương = 1 TC** — không gộp nhiều giá trị không hợp lệ vào 1 TC kiểu "39 hoặc 41 ký tự (2 sub-case tách riêng khi tự động hoá)", và không để Comment "áp dụng tương tự cho API/biến thể khác". Những câu kiểu này nghĩa là còn TC chưa viết.
- **Test cả 2 tầng FE và BE** cho mọi rule validation có thể bị bỏ qua từ client (trim, format, giới hạn số): 1 TC trên UI + 1 TC gọi API trực tiếp, khi `Test-Strategy.md` mục 4 bật "Test bằng cách gọi API trực tiếp".
- **Regression:** mỗi bug/ticket regression trong Test Plan mục 1.6 (Risk Matrix) = ≥ 1 TC, ghi số ticket vào cột Ticket ID.

#### Bước 6: Viết Test Cases vào file part rồi dựng `TestCase.md`

##### 6.1. Agent chính — lập brief và phân công

- **Khi nào chia agent:** tổng TC dự kiến ở Test Plan mục 2.2 **> 80** → chia theo section 3.1–3.5 (section quá lớn thì chia tiếp theo màn hình / field), mỗi phần giao cho một agent `tc-writer`. **≤ 80** → agent chính tự viết, vẫn ghi ra file part (một hoặc nhiều part) để dùng chung `ak tc build`.
- **READ template:** `.claude/skills/test-skills/template/gate3-brief-template.md` → điền và lưu `AK-Docs/03.Testing/01.Testcases/[functionId]/_parts/gate3-brief.md`. Brief gồm: nguồn bắt buộc đọc, thuật ngữ trích Glossary, **câu Pre-condition chuẩn theo role** (chỉ để câu chữ đồng nhất — mỗi TC vẫn viết Pre-condition đầy đủ trong ô của nó), quy ước TC ID, bảng phân công (section, Scenario ID, **dải TC ID riêng**, đường dẫn file part).
- Agent `tc-writer` là agent con định nghĩa sẵn (`.claude/agents/tc-writer.md`, `.codex/agents/tc-writer.toml`, `.gemini/agents/tc-writer.md`, `.cursor/agents/tc-writer.md` — `ak init` / `ak up` sinh, model tier Vừa). Mỗi agent nhận: đường dẫn brief + đúng phần scenario của section mình — **không** đưa toàn bộ Test Plan hay artifact khác.
- ❌ Không để agent con tự soạn brief hay tự chọn dải ID. ❌ Không bật agent song song khi chưa có brief.

##### 6.2. Viết TC vào file part

- File part: `AK-Docs/03.Testing/01.Testcases/[functionId]/_parts/03_part-<section>.md`. Dòng đầu bắt buộc: `<!-- ak-part: section=<số section> range=<ID đầu>..<ID cuối> -->`; sau đó là tiêu đề section và bảng TC.
- Viết TC theo đúng template chuẩn — **không tự định nghĩa cấu trúc mới**
- TC ID format: `TC-<FEATURE>-<SEQ>` (vd: `TC-TAG-001`, `TC-LOGIN-005`)
- Naming convention **mọi section** (không chỉ 3.3): TC Name **bắt buộc** bắt đầu bằng `"Kiểm tra..."` (section 3.3 Validation cụ thể hơn: `"Kiểm tra trường [Tên Trường]..."`) — xem đầy đủ Wording Standards ở `qa-writing-standards.md` mục 6 (path/URL phải kèm menu+tên màn hình, không dùng element id trần, không cross-reference case khác, không gộp case, giữ nguyên tên tiếng Nhật, giữ keyword dự án)
- Cấu trúc output theo 5 sections của template:
  - **Section 3.1**: Access & Authorization
  - **Section 3.2**: UI/UX (layout, giao diện)
  - **Section 3.3**: Input Validation (sub-table riêng cho từng field)
  - **Section 3.4**: Business Rules (CRUD, logic nghiệp vụ, DB verify)
  - **Section 3.5**: Exceptions & Systems (Error Guessing cases)
- **Mở rộng theo Test Strategy (BẮT BUỘC)** — đọc bảng chiều ở Test Plan mục 1.5 "Test Strategy áp dụng" và cột "Chiều split áp dụng" của từng scenario:
  - **Chiều `split`** → sinh TC riêng cho từng giá trị. Tổ chức file thành các **khối**, mỗi khối là 1 tổ hợp giá trị split và chứa đủ 5 section 3.1–3.5 bên trong, tiêu đề khối dạng `## 3.[k]. [Tên chức năng] — Ngôn ngữ: [JP] — [Biến thể]: [AUBE]`. TC ID thêm mã chiều: `TC-<FEATURE>-<VARIANT>-<LANG>-<SEQ>` (vd `TC-TRANSFER-AUBE-JP-001`); chiều nào chỉ có 1 giá trị thì bỏ mã chiều đó.
  - Mỗi TC nhân bản phải được **cụ thể hoá theo giá trị của nó**, không copy nguyên văn: message lỗi đúng nguyên văn ngôn ngữ đó, symbol/tên token đúng biến thể, dữ liệu test và pre-condition đúng ràng buộc của biến thể (vd ETH: gas trừ vào chính số dư ETH; AUBE: gas trừ vào ETH riêng).
  - Ngôn ngữ phụ với phạm vi `ui-text` → chỉ sinh các TC có kiểm tra text / label / message / định dạng hiển thị / email; ngôn ngữ phụ `full` → sinh toàn bộ.
  - Scenario ghi `Chỉ <giá trị>` → chỉ sinh ở khối của giá trị đó.
  - **Chiều `column`** → không nhân TC; thêm vào bảng TC một cột kết quả cho mỗi giá trị, đặt ngay sau cột `Expected Result` (vd `PC-Chrome | Android | iPhone`), mặc định `Untest`. Mục 2 "Kết quả kiểm thử tổng hợp" tách số liệu theo từng cột này.
  - **Chiều `sample`** → không nhân, ghi giá trị đại diện vào Pre-condition (vd "Thực hiện trên Chrome (PC)").
- Thiếu thông tin: đã có câu hỏi trong QnA Log → marker `[PENDING - TQ-xx]`; chưa có → báo agent chính (Bước 7), `tc-writer` không tự hỏi QA
- Chỉ dùng TC ID trong dải được giao; không sửa file part khác
- Chạy `ak tc lint "<file part>"` trên part của mình tới khi 0 `error`
- **Mode UPDATE:** chỉ thiết kế TC chi tiết (qua BVA/EP/Decision Table/Error Guessing ở Bước 2, UI/Business/Data ở Bước 3–4) cho scenario đánh dấu `mới ở v{N}` từ Gate 2 Bước 4. TC map tới scenario `carry-forward` **không** viết lại vào part — `ak tc build --base` giữ nguyên chúng từ `TestCase.md` hiện có.

##### 6.3. Agent chính — Test Plan Phần 3 (Coverage)

Agent chính **không** đọc lại toàn bộ nội dung các part. Mỗi `tc-writer` khi xong trả về bảng `Scenario ID → TC ID` của part mình (agent chính tự viết thì tự ghi lại trong lúc viết); agent chính gộp các bảng đó để ghi Test Plan `## Phần 3 — Coverage (Gate 3)`, đúng tên cột của `test-plan-template.md`:
- 3.1 Coverage Matrix (`| Scenario ID | TC ID |`, gồm mọi TC nhân bản; không có TC thì `N/A — <lý do>`)
- 3.2 Coverage floor domain skill (viewpoint ID → TC ID hoặc `N/A — <lý do>`)
- 3.3 Ma trận Error × Điểm submit
- 3.4 Đối chiếu số lượng (TC dự kiến ở Phần 2.2 vs TC thực tế, giải thích chênh lệch > 10%)
- 3.5 Test Data tổng hợp

**TC bổ sung sau khi các part đã viết** (ô khả thi của ma trận Error × Điểm submit chưa có TC, câu trả lời ở Bước 7, scenario thiếu TC do `ak tc build` báo): đặt TC vào **đúng sub-table `####`** cùng site / màn hình / chức năng với nó. Ví dụ TC "lưu khi sửa `group` gặp lỗi server" thuộc sub-table "Tạo / sửa `group`". ❌ Không mở sub-table mới ở cuối section 3.5 chỉ vì TC được viết sau.
- **Cách 1 (ưu tiên):** Edit part chứa sub-table đó — chèn dòng ngay sau dòng TC cuối của sub-table, dùng ID còn trống trong dải của part. Chỉ Read đoạn quanh sub-table, không đọc lại cả part.
- **Cách 2** (dải ID của part đã hết, hoặc part còn đang do agent khác viết): ghi part bổ sung `_parts/03_part-<section>-extra.md` với dải ID mới chưa giao cho ai. `section=` là section của sub-table đích. Tiêu đề `####` chép **y nguyên** tiêu đề sub-table đích, ngay dưới là bảng TC, không thêm ghi chú. `ak tc build` gộp các dòng đó vào sub-table cùng tên và in `N TC gộp vào sub-table "…"`. Không thấy dòng này → tiêu đề chưa khớp, sửa tiêu đề rồi build lại.
- Chỉ mở sub-table mới khi chưa có sub-table nào cùng site / màn hình / chức năng — đặt trong part của đúng section.

##### 6.4. Dựng `TestCase.md` bằng `ak tc build`

```bash
ak tc build "AK-Docs/03.Testing/01.Testcases/[functionId]/_parts/"03_part-*.md \
  --out "AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md" \
  --plan "AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md"
# Mode UPDATE: thêm --base "AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md"
```

- Lệnh dựng Mục 1 (lấy từ bảng Thông tin chung của Test Plan), Mục 2 reset về 0 (tách cột theo chiều `column`), Mục 3 chép **nguyên văn** bảng TC từ các part theo thứ tự section (part có tiêu đề `####` trùng sub-table của part trước → dòng TC được gộp vào sub-table đó); báo lỗi khi trùng TC ID, ID ngoài dải của part, scenario không có TC, TC ID trong Coverage Matrix không tồn tại; tự chạy `ak tc lint`.
- Thành công (0 `error`) → lệnh xoá các part và thư mục `_parts/`. Lỗi → part được giữ lại: sửa **đúng part** gây lỗi (hoặc Coverage Matrix) rồi chạy lại. ❌ Không sửa tay `TestCase.md` để né lỗi build.
- Mode UPDATE: `--base` giữ TC carry-forward, thay TC cùng ID, thêm TC mới — kết quả là **một** bộ TC duy nhất.

#### Bước 7: Ghi câu hỏi phát sinh vào QnA Log (NGOẠI LỆ)
- **Chỉ hỏi khi có vấn đề THỰC SỰ MỚI**, chỉ lộ ra khi thiết kế test case chi tiết (vd: một tổ hợp dữ liệu biên chưa từng được nhắc tới). **KHÔNG** hỏi lại điều đã có câu trả lời trong QnA Log hoặc giả định ở Test Plan mục 1.7 — đọc lại trước khi quyết định hỏi thêm.
- Agent chính gom điểm chưa rõ do các `tc-writer` báo về, hỏi QA (từng câu một), ghi tiếp vào `[functionId]_QnA Log.md` (mã `TQ-xx` nối tiếp) và thêm dòng "Lịch sử cập nhật tài liệu" cho Gate 3. Câu trả lời làm đổi TC → sửa part tương ứng **trước** khi chạy `ak tc build`.

#### Bước 8: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — dừng gate chờ QA đọc output (không tạo checklist để tick)
- Hiển thị gate pause message — đợi **APPROVED**

**Khi APPROVED:**
→ **INVOKE** `gate-review` skill (verify mode) — chạy `ak review check --gate 3 --ticket [functionId]`
→ Nếu passed: `ak gate 3 approved --ticket [functionId]` → chuyển Gate 4
→ Nếu blocked: làm theo gate-review skill response protocol

**Definition of Done** (AI tự kiểm trước khi dừng gate — QA không phải tick, không đưa danh sách này cho QA):
- [ ] Thuật ngữ khớp UC Spec / QnA-Log / Glossary (`custom/rules/domain-terminology.md`): không từ đồng nghĩa, không tên phân hệ / menu tự đặt, không chữ tiếng Nhật đứng một mình
- [ ] Động từ thao tác UI và thuật ngữ IT theo `custom/rules/ui-action-wording.md`: grep `bấm|nhấn nút|ấn nút|tích chọn|bỏ tích|chọn tay|gõ vào|điền vào|ô nhập|hộp xác nhận|thông báo góc|khung lỗi|rời ô|kéo thả|di chuột|máy chủ|bộ nhớ đệm|chuyển hướng` — 0 hit ngoài chữ gốc trích nguyên văn
- [ ] 100% tuân thủ `testcase-template.md` — không tự định nghĩa cấu trúc mới
- [ ] Mọi trường input (cả Required và Optional) đã qua ma trận skill 02.02
- [ ] TC Name mọi section bắt đầu bằng `"Kiểm tra"` (section 3.3: `"Kiểm tra trường [Tên Trường]..."`)
- [ ] 100% tuân thủ Wording Standards `qa-writing-standards.md` mục 6 — không lộ element id/code thuần, không cross-reference case khác, không gộp case, path/URL kèm menu+tên màn hình, giữ nguyên tên tiếng Nhật
- [ ] `TestCase.md` được dựng bằng `ak tc build` (không viết tay, không chép lại nội dung part); lệnh chạy xong không còn lỗi và `_parts/` đã được xoá
- [ ] TC bổ sung sau khi viết part nằm trong sub-table cùng site / màn hình / chức năng — không có sub-table nào bị mở lại lần hai ở cuối section hoặc ở section khác
- [ ] Chia agent khi TC dự kiến > 80: đã có brief chung `_parts/gate3-brief.md`, mỗi agent một dải TC ID riêng
- [ ] **Linter sạch lỗi** — `ak tc build` tự chạy `ak tc lint` trên `TestCase.md`, 0 `error`. Linter kiểm cùng lúc: tham chiếu ra ngoài ô ở **mọi** cột kể cả Comment (§6.5 — bắt cả `TC-XXX-001` nằm giữa câu, `như trên`, `case này/kia`, `xem mục/SRS/UC`, `câu ①`, `revision 3`), hành văn dịch máy (§6.12), Expected Result rỗng nghĩa và Expected không map đủ theo từng step (§6.13). Mỗi `warn` (mã `BR/FR/VR/ER` để trần, dấu hiệu gộp case) phải xử lý hoặc ghi lý do vào Test Plan mục 3.4
- [ ] Expected Result của mọi TC có Steps từ 2 bước trở lên được đánh số 1:1 theo Steps, mỗi mục là kết quả quan sát được ngay sau bước đó (`qa-writing-standards.md` mục 6.13)
- [ ] Coverage Matrix (Test Plan mục 3.1) mapping Scenario ID → TC ID đầy đủ — `ak tc build --plan` không báo lỗi
- [ ] Mọi chiều `split` đã sinh đủ khối TC; mọi chiều `column` đã có cột kết quả; không còn TC ghi nhiều giá trị của cùng 1 chiều split (vd "AUBE/OWL/ETH") — kiểm bằng `grep -nE "AUBE ?/ ?OWL|áp dụng tương tự|sub-case|gộp mô tả"` (thay tên biến thể của dự án), 0 hit
- [ ] Coverage floor domain skill: mọi viewpoint có TC hoặc `N/A — <lý do>`
- [ ] Ma trận Error × Điểm submit có trong Test Plan mục 3.3, mọi ô khả thi có TC
- [ ] Có bảng Đối chiếu số lượng (dự kiến Gate 2 vs thực tế) ở Test Plan mục 3.4
- [ ] Marker `[PENDING - TQ-xx]` trỏ tới câu hỏi có thật trong QnA Log
- [ ] Không còn câu hỏi 🔴 Blocking nào `Open` trong QnA Log
- [ ] Test Plan Phần 3 chạy `ak tc lint --doc` 0 `error`

> **Telemetry:** Run `ak gate 3 start --ticket [functionId]` khi bắt đầu gate này.
> Run `ak gate 3 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.

---

### GATE 4 — Review (user review, AI Edit)

**Mục tiêu:** Chốt chặn chất lượng toàn bộ bộ Test Case — bao phủ 100% yêu cầu, không trùng lặp, loại bỏ out-of-scope — bằng cách **review và Edit tại chỗ**, không viết lại bộ TC.

**Điều kiện vào Gate 4:** Gate 3 đã **APPROVED** và `[functionId]_TestCase.md` đã được dựng bằng `ak tc build`.

**Đầu vào (Inputs):**
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md`
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Test Plan.md` (Phần 1 phạm vi, Phần 3 Coverage)
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_QnA Log.md`

**Đầu ra (Outputs):**
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md` — **Edit** đúng TC có finding (sửa, xoá trùng, xoá out-of-scope, thêm TC thiếu)
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Review Result.md`
- `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Dev_Checklist.md`

> **Quy tắc Gate 4:** ❌ **KHÔNG** viết lại hay chép lại bộ TC — kể cả vào `Review Result.md`. Chỉ dùng Edit trên đúng dòng TC có finding. Viết lại hàng trăm TC trong một lượt vừa tốn token output nhất của cả luồng, vừa dễ rơi TC, bị cắt giữa chừng, tự tóm tắt hoặc đổi câu chữ QA đã APPROVED ở Gate 3.

**Bước thực hiện:**

**Pre-flight (bắt buộc, chạy trước Bước 1):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.

#### Bước 1: Review nội dung và đánh giá bao phủ
- **READ skill:** `.claude/skills/test-skills/categories/00-core/00.04.testcase-review.md`
- **READ skill:** `.claude/skills/test-skills/categories/99-review/99.01.coverage-review.md`
- Đọc `TestCase.md` **theo từng section** 3.1–3.5 (và từng khối `split`). Mỗi section kết thúc bằng một dòng kết quả trong Findings của `Review Result.md`, kể cả "0 finding" — không được bỏ trống section nào.
- Checklist review bắt buộc:
  - [ ] 100% Requirement ID của UC Spec / System Requirement (Draft RTM ở Test Plan mục 2.4) có TC tương ứng?
  - [ ] Không có TC test item Out-of-Scope (Test Plan mục 1.1)?
  - [ ] Steps rõ ràng, có thể reproduce (không mơ hồ)?
  - [ ] Expected Result cụ thể và đo được (tránh "hoạt động đúng", "Hiển thị đầy đủ")?
  - [ ] Expected Result đánh số 1:1 theo Steps — mỗi bước có kết quả quan sát được riêng (`qa-writing-standards.md` mục 6.13)?
  - [ ] Đã chạy `ak tc lint` trên `[functionId]_TestCase.md` sau khi Edit (Bước 5) và 0 `error`?
  - [ ] Phần tử đã bị gỡ khỏi phạm vi theo comment reviewer không còn xuất hiện ở bất kỳ cột nào của bất kỳ case nào (xem `gate-review` Mode 3 — Impact Sweep)?
  - [ ] Rule trong `AK-Docs/03.Testing/00.Strategies/Review-Feedback-Rules.md` (nếu có) đã được áp dụng cho **toàn bộ** bộ TC, không chỉ case bị comment?
  - [ ] Không có TC trùng lặp logic?
  - [ ] Marker `[PENDING - TQ-xx]` trỏ tới câu hỏi có thật trong QnA Log, câu đã `Confirmed` thì marker đã được thay bằng nội dung chốt?
  - [ ] Finding cần người khác trả lời đã ghi vào QnA Log (mã `TQ-xx`) và Findings dẫn mã đó?
- **Checklist tuân thủ Test Strategy & domain (bắt buộc ở mọi Mode):**
  - [ ] Mỗi tổ hợp giá trị của các chiều `split` có đủ khối TC; số TC mỗi khối hợp lý so với khối ngôn ngữ chính / biến thể khác (khối thiếu hẳn một section so với khối anh em → phải giải thích).
  - [ ] Mỗi chiều `column` có đủ cột kết quả ở mọi bảng TC.
  - [ ] Coverage floor của domain skill: 100% viewpoint có TC hoặc `N/A — <lý do>` hợp lý (lý do kiểu "không cần" / "tương tự case khác" không được chấp nhận).
  - [ ] Ma trận Error × Điểm submit: 100% ô khả thi có TC.
  - [ ] Đối chiếu số lượng: TC thực tế lệch > 10% so với dự kiến Gate 2 → có giải thích trong Findings.
  - [ ] Mọi TC happy path của giao dịch bất đồng bộ có Expected Result đủ tiêu chí PASS ở strategy mục 4 (vd 4 lớp DB + API + tx_hash + UI).
  - [ ] **Rà lại các mục AI tự điền ở Bước 0.7** (danh sách nằm trong Test Plan mục 1.5 "Test Strategy áp dụng"): giá trị nào giờ đã có bằng chứng ngược lại (vd TC cho thấy dự án có màn mobile mà strategy ghi `N/A`) → sửa `Test-Strategy.md`, tăng `Strategy-Version`, ghi vào Findings. Đây là **điểm rà duy nhất** cho nhóm này — không hỏi lại QA ở các gate trước.
- **Mode UPDATE — checklist bắt buộc bổ sung (không được bỏ qua, xem `docs/internal/Token Problems.md` §4.2, Vấn đề B):**
  - [ ] Với mỗi BR/FR **mới đổi**, kiểm tra **tổ hợp** với BR/FR **không đổi** có cùng chạm field/entity/màn hình không (vd rule validation mới × rule phân quyền cũ, rule mới × 1 state/lifecycle đã có) — case chỉ lộ ra khi 2 rule tương tác với nhau, không lộ ra khi xét TC mới độc lập.
  - [ ] Tìm thấy tổ hợp có khả năng sinh case mới → thêm TC mới (không bỏ qua chỉ vì không nằm trong scenario "mới/đổi" ban đầu ở Gate 2).
  - [ ] Không coi "TC mới đúng riêng lẻ, TC carry-forward không đổi" là đủ điều kiện ✅ Fully/Conditionally Approved — phải qua đúng checklist tổ hợp này trước.

#### Bước 2: Sửa `TestCase.md` bằng Edit — chỉ TC có finding
- Ghi số TC **trước review** (số `ak tc build` đã in ở Gate 3, hoặc đếm lại bằng `ak tc lint`).
- Mỗi finding → **Edit** đúng dòng TC đó trong `[functionId]_TestCase.md`: sửa nội dung, xoá TC trùng lặp, xoá TC Out-of-Scope, thêm TC thiếu (chèn ngay sau dòng TC cuối của sub-table cùng site / màn hình / chức năng — không mở sub-table mới hay thêm vào cuối Mục 3 khi đã có sub-table phù hợp; ID tiếp theo chưa dùng trong section, không tái sử dụng ID đã xoá). ❌ Không đọc toàn file rồi ghi đè cả file.
- Câu hỏi đã `Confirmed` trong QnA Log → thay marker `[PENDING - TQ-xx]` bằng nội dung chốt.
- Xoá / thêm TC → cập nhật Coverage Matrix (Test Plan mục 3.1) cho khớp.
- Kiểm tra traceability xuyên suốt: Req ID → Scenario ID → TC ID.

#### Bước 3: Soạn `Review Result.md`
- **READ template:** `.claude/skills/test-skills/template/review-result-template.md`
- Gồm: 1. Review Summary (số TC trước / xoá / thêm / sau, kết quả lint), 2. Findings (một dòng kết quả cho **từng section**, kể cả "0 finding"; bảng finding dẫn TC ID và mã `TQ-xx` nếu có), 3. Coverage Validation, 4. RTM Final (Req ID → Scenario ID → TC ID), 5. Dev Checklist (số dòng; Mode UPDATE: thêm / xoá / sửa), 6. Sign-off (Bước 6)
- ❌ Không chép TC vào file này — chỉ dẫn TC ID
- Số TC sau review phải bằng `trước − xoá + thêm` và khớp số TC thực tế trong `TestCase.md`
- Lưu: `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Review Result.md`

#### Bước 4: Cập nhật QnA Log
- Finding cần PM / BA / khách hàng trả lời → ghi tiếp vào `[functionId]_QnA Log.md` (mã `TQ-xx` nối tiếp), thêm dòng "Lịch sử cập nhật tài liệu" cho Gate 4. Không có gì mới → không sửa file.

#### Bước 5: Kiểm `TestCase.md` sau khi Edit
- `TestCase.md` đã được `ak tc build` dựng ở Gate 3 theo `testcase-template.md` — Gate 4 **không** sinh lại file. Chỉ kiểm:
  - **Mục 1**: `UC-Spec-Version` / `System-Requirement-Version` = version đã dùng ở Gate 1 Bước 0.6, **`Test-Strategy-Version`** = `Strategy-Version` đã dùng ở Gate 1 Bước 0.7 — bắt buộc, đây là mỏ neo cho lần chạy `create-testcase` tiếp theo xác định Mode CREATE/UPDATE. `Test-Strategy.md` vừa đổi version ở Bước 1 → Edit lại dòng này. Điền Người kiểm duyệt / Ngày kiểm duyệt.
  - **Mục 2**: Kết quả kiểm thử tổng hợp vẫn là 0 (chờ execution); số TC khớp sau khi xoá / thêm.
  - **Mục 3**: Mode UPDATE — TC carry-forward và TC mới/đổi nằm trong **một** bộ duy nhất.
- **KHÔNG chứa:** Review Summary, Findings, RTM, Coverage Matrix, Sign-off (thuộc `Review Result.md` / Test Plan)
- **Chạy linter (BẮT BUỘC):**
  ```bash
  ak tc lint "AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md"
  ```
  Còn `error` → sửa đúng TC lỗi rồi chạy lại cho tới khi sạch; **không** ký Sign-off khi linter còn `error`. Mỗi `warn` xử lý hoặc ghi lý do vào `Review Result.md` mục 2.

#### Bước 5b: Sinh Dev Checklist

Checklist tự kiểm dành cho **Dev**, để Dev chạy trước khi bàn giao QA. Chạy ngay sau Bước 5, khi bộ TC đã chốt.

- **READ template:** `.claude/skills/test-skills/template/dev-checklist-template.md` — tuân thủ 100% cấu trúc và quy tắc trong đó
- Artifact `[functionId]_Dev_Checklist.md` gồm:
  - **Mục 1**: Thông tin chung (functionId, nguồn Test Case, `UC-Spec-Version` / `System-Requirement-Version` copy từ Mục 1 của file TestCase, ngày tạo)
  - **Mục 2**: Checklist FE — 5 nhóm: Happy case · Validation cơ bản · Yêu cầu riêng của task · Case liên quan đến API · Case ngoại lệ
  - **Mục 3**: Checklist BE — đúng 5 nhóm như trên
  - **Mục 4**: Tiêu chí hoàn thành
- Cột bảng: `ID | Checklist Name | Expected Result | Result | Note | TC ID`. Cột `Result` và `Note` sinh ra để trống — Dev điền khi chạy
- ID: `<FE|BE>-[functionId]-[3 chữ số]`, ví dụ `FE-AD06-001`, `BE-WONDER-1035-012`. Số thứ tự chạy độc lập cho FE và BE, liên tục trong từng section
- **Nguồn nội dung — chỉ bốc từ `[functionId]_TestCase.md`:**
  - Mỗi dòng checklist map tới **đúng một** TC có thật trong bộ TC vừa Approved; ghi TC ID đó vào cột `TC ID`
  - ❌ **KHÔNG gộp** nhiều TC thành một dòng. ❌ **KHÔNG tự sinh** dòng không có TC tương ứng — thiếu vùng nào thì đó là lỗ hổng của bộ TC, ghi vào Findings của `Review Result.md`, không vá bằng cách bịa dòng checklist
  - Chọn TC **đại diện** cho mỗi nhóm; nhiều TC cùng kiểm một điều (vd 6 TC maxlength cho 6 field) → chọn TC của field rủi ro nhất
- **Section không có TC thuộc phạm vi của nó** → giữ nguyên heading, ghi đúng một dòng `N/A — bộ TestCase không có case kiểm qua API/DB.` Task chỉ chạm một phía → section còn lại ghi `N/A — task không thay đổi backend.` Không xoá heading, không bịa dòng để lấp chỗ trống
- **Mode UPDATE** — đọc `[functionId]_Dev_Checklist.md` hiện có, đối chiếu cột `TC ID` với bộ TC mới:
  - TC ID không còn trong bộ TC mới (đã xoá hoặc gộp) → **xoá** dòng checklist tương ứng
  - TC ID còn nhưng nội dung TC đã đổi → cập nhật `Checklist Name` và `Expected Result`, giữ nguyên `Result` và `Note` nếu Dev đã điền
  - TC main mới xuất hiện → thêm dòng, ID lấy số thứ tự kế tiếp trong section (không tái sử dụng ID đã xoá)
  - Ghi số dòng thêm/xoá/sửa vào `Review Result.md` mục 5
- Lưu: `AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Dev_Checklist.md`
- **Chạy linter ngay sau khi lưu (BẮT BUỘC):**
  ```bash
  ak tc lint --checklist AK-Docs/03.Testing/01.Testcases/[functionId]/[functionId]_Dev_Checklist.md
  ```
  Còn `error` → sửa file rồi chạy lại cho tới khi sạch; **không** ký Sign-off khi linter còn `error`.

#### Bước 6: Xác nhận Sign-off Status

| Status | Điều kiện |
|---|---|
| ✅ **Fully Approved** | 0 Critical / 0 Major / 0 Minor còn mở, 0 `[PENDING - TQ-xx]` |
| ✅ **Conditionally Approved** | 0 Critical / 0 Major, còn Minor hoặc `[PENDING - TQ-xx]` — được phép thực thi trừ TC còn PENDING |
| ⚠️ **Need Update** | Còn Major issue chưa giải quyết |
| ❌ **Rejected** | Còn Critical issue, coverage < 100%, hoặc vi phạm template |

#### Bước 7: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — dừng gate chờ QA đọc output (không tạo checklist để tick)
- Hiển thị gate pause message — đợi **APPROVED**

**Khi APPROVED:**
→ **INVOKE** `gate-review` skill (verify mode) — chạy `ak review check --gate 4 --ticket [functionId]`
→ Nếu passed: `ak gate 4 approved --ticket [functionId]` → Bộ Test Case hoàn thành, sẵn sàng thực thi. Function List giữ `QA 🔵` — test case chưa chạy; `QA ✅` chỉ có sau sign-off GO của Executing Flow (`custom/rules/function-list-status.md`)
→ Nếu blocked: làm theo gate-review skill response protocol

**Definition of Done** (AI tự kiểm trước khi dừng gate — QA không phải tick, không đưa danh sách này cho QA):
- [ ] Thuật ngữ khớp UC Spec / QnA-Log / Glossary (`custom/rules/domain-terminology.md`): không từ đồng nghĩa, không tên phân hệ / menu tự đặt, không chữ tiếng Nhật đứng một mình
- [ ] Động từ thao tác UI và thuật ngữ IT theo `custom/rules/ui-action-wording.md`: grep `bấm|nhấn nút|ấn nút|tích chọn|bỏ tích|chọn tay|gõ vào|điền vào|ô nhập|hộp xác nhận|thông báo góc|khung lỗi|rời ô|kéo thả|di chuột|máy chủ|bộ nhớ đệm|chuyển hướng` — 0 hit ngoài chữ gốc trích nguyên văn
- [ ] `[functionId]_Review Result.md` có đủ Review Summary, Findings (một dòng kết quả cho **từng section**), Coverage Validation, RTM Final, Dev Checklist, Sign-off — và **không** chép TC
- [ ] Số TC trước / xoá / thêm / sau trong Review Summary khớp số TC thực tế của `TestCase.md`
- [ ] `TestCase.md` chỉ bị sửa bằng Edit ở đúng TC có finding — không viết lại, không ghi đè cả file
- [ ] `[functionId]_TestCase.md` chỉ chứa Section 1+2+3 theo template chuẩn, không có review metadata
- [ ] `[functionId]_Dev_Checklist.md` có đủ section FE và BE, mỗi section đủ 5 nhóm (nhóm/section nào N/A đã ghi lý do cụ thể)
- [ ] Mọi dòng của `[functionId]_Dev_Checklist.md` có cột `TC ID` trỏ tới TC có thật trong `[functionId]_TestCase.md` — không dòng nào mồ côi
- [ ] Đã chạy `ak tc lint --checklist` trên `[functionId]_Dev_Checklist.md` và 0 `error`
- [ ] Coverage Matrix (Test Plan mục 3.1) đã cập nhật theo TC xoá / thêm
- [ ] Traceability xuyên suốt: Req ID → Scenario ID → TC ID
- [ ] `ak tc lint --doc` trên `Review Result.md` (và QnA Log nếu có thay đổi), 0 `error`
- [ ] Checklist tuân thủ Test Strategy & domain (Bước 1) đạt 100%; `Test-Strategy-Version` đã ghi vào Mục 1 của `[functionId]_TestCase.md`
- [ ] Sign-off status đã xác định (Fully / Conditionally / Need Update / Rejected)

> **Telemetry:** Run `ak gate 4 start --ticket [functionId]` khi bắt đầu gate này.
> Run `ak gate 4 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.

#### Bước 7.5: Retrospect + đề xuất memory draft

Sau khi Gate 4 APPROVED, đúc kết những gì học được. **Ưu tiên trước:** nếu review ở Bước 7 từng phát hiện Major/Critical issue phải sửa lại, đó là bài học giá trị nhất — đảm bảo có draft cho đúng issue đó. Sau đó mới thêm lỗi/bẫy môi trường gặp khi test, business rule cần làm rõ thêm. Tạo **draft local** cho từng candidate (chưa cần duyệt — `_pending/` chỉ ở local, xem `docs/common/Memory-Architecture-v1.0.md`):

```
ak memory draft --category 01.Lessons/qa --function-id <[functionId] | global> \
  --slug <slug-ngắn> --content "<≤150 từ, 1 fact>" \
  --tags <tag1,tag2> --workflows create-testcase --source "[functionId] / Gate 4"
```

**Chọn scope theo nội dung, không theo nơi phát sinh:** memory vẫn đúng khi làm chức năng khác của dự án (convention, bẫy kỹ thuật chung, quy tắc nghiệp vụ toàn hệ thống) → `--function-id global`; chỉ đúng với riêng chức năng này → `--function-id [functionId]`. Không ghi tiến độ task (đã làm tới đâu, còn dở gì) vào memory — tiến độ nằm ở tài liệu của task.

**Memory dựa trên file cụ thể** (UC Spec, System Requirement, file code) → thêm `--refs <đường dẫn từ workspace root>`, ví dụ `--refs AK-Docs/02.BA-Specs/.../UC-Spec_v2.md`. `ak memory health` sẽ báo memory outdated khi file đó thay đổi hoặc bị xóa.

**Tags theo chủ đề, không theo giá trị:** gắn tag cho điều memory nói tới (`date-format`, `refund-limit`), không gắn giá trị cụ thể (`yymm`, `ddmmyy`, `5000-yen`). Nhờ vậy khi QA đổi ý, bản cũ và bản mới luôn trùng tag và `ak memory draft` bắt được mâu thuẫn.

**Khi QA đổi ý:** nếu draft mới nói ngược với một memory đã có (trong `<PROJECT_MEMORY>` hoặc trong danh sách "tag trùng" mà `ak memory draft` in ra), hỏi QA xác nhận rồi tạo draft với `--supersedes <id cũ>` — bản cũ bị ẩn khỏi recall ngay trên máy này và được chuyển vào `_deprecated/` trong cùng MR khi submit.

**Báo scope và hỏi QA (bắt buộc khi có draft):** sau khi tạo draft (gồm cả draft tạo lúc sửa issue ở Bước 7), liệt kê từng draft kèm phạm vi rồi hỏi một lần:

```
Memory draft vừa tạo (local, chưa chia sẻ với team):
1. mem-F003-<slug> — <tóm tắt 1 dòng> — chỉ áp dụng cho [functionId]
2. mem-global-<slug> — <tóm tắt 1 dòng> — áp dụng toàn dự án
Memory nào dùng chung toàn dự án (mọi chức năng)? Trả lời số thứ tự (vd `1`), hoặc `giữ nguyên`.
```

QA chọn dùng chung một draft đang gắn [functionId] → `ak memory rescope <path draft> --global` (path lấy từ output `ak memory draft`). QA muốn thu hẹp một draft global → `ak memory rescope <path draft> --function-id [functionId]`. Chờ QA trả lời rồi mới sang Bước 8.

Category khác hữu ích ở đây: `00.Shared/domain` (business rule phát hiện khi thiết kế test), `00.Shared/glossary` (thuật ngữ — flat, không cần `--function-id`). Bỏ qua bước này nếu không có gì thực sự mới. Nếu `ak memory draft` báo trùng, đừng tạo bản mới — báo cho QA để họ quyết định sửa bản cũ.

#### Bước 8: Submit AK-Docs lên remote qua Merge Request

Sau khi Gate 4 đã APPROVED (bộ Test Case hoàn thành):

1. Soạn title + description cho Merge Request (tóm tắt bộ Test Case vừa hoàn thành, sign-off status, link ticket gốc), hiển thị cho QA xem trước.
2. Hỏi QA: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?"
   - QA đồng ý → chạy `ak docs submit --title "..." --description "..." --yes`
   - QA từ chối → dừng, để QA tự commit/tạo MR khi sẵn sàng
3. Thông báo QA: MR đã mở, chờ **PM review & merge vào `main`** — đây là bước duyệt cuối cùng cho tài liệu, không phải QA tự merge.

> ❌ Không tự thêm `--yes` khi chưa thấy QA gõ xác nhận rõ ràng trong hội thoại.

---

### Bản đồ Skills theo Gate

| Gate | Skills đọc | Output |
|---|---|---|
| Gate 1 | `test-strategy-template` + `00.Strategies/Test-Strategy.md` (Bước 0.7 — chỉ mục `[CHỐT]` chặn), `pr-impact-analysis` (Bước 1.5), `QA_Writing_Standards`, `00.01 Requirement Analysis`, `00.02 Risk Analysis`, Domain skill áp dụng (`08-domain-skills/`), `test-plan-template`, `skill-ba-qna-template-v1` | `Test Plan.md` (Thông tin chung + Phần 1), `QnA Log.md` |
| Gate 2 | `_gate2-always-apply.md` (gộp 00.03 Scenario Builder + 01.06 Error Guessing + 03.02 Workflow Testing), Domain skill áp dụng (bắt buộc nếu có) | `Test Plan.md` (Phần 2), `QnA Log.md` (nếu có câu hỏi mới) |
| Gate 3 | `pr-impact-analysis` (Delta Detection nếu có PR từ Gate 1), `testcase-template`, `_gate3-test-design-always-apply.md` (gộp 01.01 BVA + 01.02 EP + 01.03 Decision Table + 01.06 Error Guessing), `_gate3-ui-always-apply.md` (gộp 02.01–02.04), `_gate3-business-data-always-apply.md` (gộp 03.01 + 03.03 + 04.01 + 04.04), Domain skill áp dụng (bắt buộc nếu có), `gate3-brief-template` + agent `tc-writer`, `ak tc build` | `_parts/` (tạm) → `TestCase.md`, `Test Plan.md` (Phần 3), `QnA Log.md` (nếu có câu hỏi mới) |
| Gate 4 | `00.04 TC Review`, `99.01 Coverage Review`, `dev-checklist-template` (Bước 5b), Domain skill áp dụng (mục checklist Gate 4) | Edit `TestCase.md`, `Review Result.md` (`review-result-template`), `Dev_Checklist.md` |

---

### Quy tắc bắt buộc

- ❌ **KHÔNG** tự ý liệt kê/checkout/đọc nhiều branch trong repo source để dò tìm thay đổi code — xác định phạm vi ảnh hưởng code phải qua PR link hoặc commit SHA/branch cụ thể do TESTER cung cấp (Bước 1.5, Gate 1) + skill `pr-impact-analysis`
- ❌ **KHÔNG** bỏ qua thứ tự Gate — luôn đi từ Gate 1 → 2 → 3 → 4
- ❌ **KHÔNG** tự suy diễn nghiệp vụ — thiếu thông tin thì ghi giả định ở Test Plan mục 1.7 hoặc câu hỏi trong QnA Log kèm marker `[PENDING - TQ-xx]`
- ❌ **KHÔNG** ghi file nào của `create-testcase` vào `AK-Docs/03.Testing/07.AI-Artifacts/` — output chỉ gồm QnA Log, Test Plan, TestCase, Review Result, Dev Checklist trong `01.Testcases/[functionId]/`
- ❌ **KHÔNG** viết bộ TC quá một lần: Gate 3 viết vào file part, `ak tc build` dựng `TestCase.md`; agent chính không đọc-rồi-viết-lại các part; Gate 4 chỉ Edit TC có finding
- ❌ **KHÔNG** tiến gate tiếp theo khi còn issue Critical hoặc Major chưa giải quyết
- ✅ **BẮT BUỘC** chạy Bước 0 ở Gate 1 — xác nhận `functionId` và thư mục đầu ra trước khi làm bất cứ điều gì
- ✅ **BẮT BUỘC** chạy Bước 0.5 ở Gate 1 — đảm bảo AK-Docs đang ở branch `feature/[taskId]` (hoặc `feature/[taskId]-<mô-tả>`) trước khi ghi file đầu tiên
- ✅ **BẮT BUỘC** chạy Bước 0.6 ở Gate 1 — kiểm tra UC Spec + System Requirement (tồn tại, khớp version, Approved); thiếu/lệch → cảnh báo yellow **không chặn Gate**, ghi vào Test Plan mục 1.7
- ✅ **BẮT BUỘC** chạy Bước 0.7 ở Gate 1 — nhưng chỉ mục `[CHỐT]` (chính sách tách TC) mới **chặn Gate 1**, và chỉ được hỏi **một lần duy nhất bằng một bảng gộp** kèm đề xuất sẵn cho từng dòng
- ❌ **CẤM** hỏi QA bất kỳ mục `[AI SUY LUẬN]` nào của `Test-Strategy.md` (môi trường, URL, phạm vi chạy từng môi trường, trình duyệt, breakpoint, cách chuẩn bị dữ liệu, tài khoản test, độ sâu xác minh DB/API, ngôn ngữ viết TC...) — AI tự quét nguồn theo bảng ở Bước 0.7 bước 2, không có bằng chứng thì dùng giá trị mặc định của template
- ✅ **BẮT BUỘC** ghi nguồn cho mọi giá trị AI tự điền (`[AI — nguồn: <đường dẫn>]` hoặc `[AI — mặc định]`) và liệt kê chúng trong khối ② của bảng xác nhận + mục "Test Strategy áp dụng" — QA phải thấy được AI đã dựa vào đâu
- ❌ **KHÔNG** gộp nhiều giá trị của một chiều `split` (ngôn ngữ, biến thể nghiệp vụ, role...) vào 1 TC, và không ghi "áp dụng tương tự" thay cho việc viết TC
- ✅ **BẮT BUỘC** đọc domain skill áp dụng ở Gate 1–4 và phủ 100% coverage floor của nó (TC hoặc `N/A — <lý do>`)
- ✅ **BẮT BUỘC** đọc skill từ `.claude/skills/test-skills/` — không suy luận từ bộ nhớ
- ✅ **BẮT BUỘC** invoke `gate-review` cuối mỗi gate và chờ APPROVED
- ✅ **BẮT BUỘC** tuân thủ 100% `testcase-template.md` ở Gate 3 và Gate 4
- ✅ **BẮT BUỘC** Gate 3 chia agent `tc-writer` khi TC dự kiến > 80, mỗi agent dùng chung brief `_parts/gate3-brief.md` và một dải TC ID riêng
- ❌ **KHÔNG** thêm dòng Dev Checklist không map tới TC nào trong `[functionId]_TestCase.md`, và không gộp nhiều TC vào một dòng checklist — thiếu vùng nào thì ghi vào Findings của `Review Result.md` như lỗ hổng của bộ TC
- ✅ **BẮT BUỘC** câu hỏi 🔴 Blocking phải có câu trả lời trước khi ghi phần Test Plan của gate đó
- ✅ **BẮT BUỘC** Gate 1 là gate đào sâu Q&A chính — hỏi QA từng câu một (Bước 2b) cho đến khi hết nghi vấn 🔴 Blocking, trước khi chuyển Gate 2
- ❌ **KHÔNG** ở Gate 2-4 hỏi lại vấn đề đã có câu trả lời trong QnA Log hoặc giả định rõ ràng ở Test Plan mục 1.7 — câu hỏi ở các gate này chỉ dành cho phát sinh THỰC SỰ MỚI
- ✅ **BẮT BUỘC** điền trường `Phụ thuộc` cho mọi nghi vấn trước khi hỏi câu đầu tiên; câu cha chưa trả lời → câu con ghi `Blocked-by TQ-xx`, KHÔNG hỏi, không tách nhỏ để hỏi lách (xem [Quy tắc đặt câu hỏi](#quy-tắc-đặt-câu-hỏi--phụ-thuộc-chất-lượng-chống-hỏi-trùng-tự-tìm-hiểu-trước-khi-hỏi))
- ✅ **BẮT BUỘC** mỗi câu hỏi có đủ Bối cảnh (kèm ảnh hưởng nếu chưa chốt) / Câu hỏi một ý / Options kèm hệ quả, giải nghĩa mọi viết tắt ngay lần đầu, và kèm "Ví dụ minh hoạ" nếu câu hỏi phức tạp
- ❌ **KHÔNG** viết mục "Vì sao cần hỏi" thành mục riêng — gộp vào Bối cảnh
- ❌ **KHÔNG** hỏi lại điều đã chốt hoặc suy ra được từ quyết định đã chốt, kể cả khi diễn đạt bằng từ đồng nghĩa — ghi `Suy ra từ TQ-xx`; nghi ngờ thì hỏi **một** câu xác nhận yes/no
- ❌ **KHÔNG** thêm câu hỏi để danh sách trông đầy đủ hoặc để "phòng hờ" — số câu hỏi không phải thước đo chất lượng phân tích
- ✅ **BẮT BUỘC** chạy bước "Xác định Mode (CREATE / UPDATE)" ở Gate 1 Bước 0.6 trước khi làm bất cứ điều gì khác — không mặc định chạy đủ 4 Gate cho toàn bộ UC nếu TestCase cũ đã tồn tại và khớp version cũ đã biết
- ✅ **BẮT BUỘC** (Mode UPDATE) chạy checklist tổ hợp BR-mới × BR-cũ ở Gate 4 Bước 1 trước khi ký Sign-off — đây là mitigation bắt buộc, không phải tuỳ chọn (xem `docs/internal/Token Problems.md` §4.2)
- ✅ **BẮT BUỘC** ghi `UC-Spec-Version`/`System-Requirement-Version` vào Mục 1 của `[functionId]_TestCase.md` ở mọi Mode — đây là mỏ neo cho lần chạy tiếp theo xác định Mode
- ✅ **BẮT BUỘC** chạy `ak tc lint` trên file part (Gate 3, mỗi `tc-writer`), trên `TestCase.md` (Gate 3 qua `ak tc build`, Gate 4 Bước 5), và `ak tc lint --checklist` trên file Dev Checklist ở Gate 4 (Bước 5b) — còn `error` thì không đóng gate, không ký Sign-off
- ✅ **BẮT BUỘC** chạy `ak tc lint --doc` trên Test Plan, QnA Log và Review Result — kết luận lấy từ code phải là câu nghiệp vụ tự đủ nghĩa kèm dòng/cột `Source code:` (`document-wording.md` mục 3); Tester/BA/PM đọc được mà không mở source, đồng thời có bằng chứng để nhờ Dev kiểm lại
- ✅ **BẮT BUỘC** đọc `AK-Docs/03.Testing/00.Strategies/Review-Feedback-Rules.md` ở Gate 1 khi file tồn tại, và áp dụng rule trong đó cho **toàn bộ** bộ TC — rule reviewer đã chốt ở ticket trước có hiệu lực như quy chuẩn của kit
- ❌ **KHÔNG** sửa xong dòng bị comment rồi coi là đã xử lý comment — mọi comment phải qua Impact Sweep của `gate-review` Mode 3 (quét keyword toàn file, báo `0 remaining hit`)
