## [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.

---

### 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` |
| `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` |

---

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

```
03.Testing/
├── 01.Testcases/
│   └── [functionId]/[functionId]_TestCase.md                  ← Gate 4 tạo
└── 07.AI-Artifacts/
    └── [functionId]/
        ├── [functionId]_01_Requirement_Analysis_Result.md     ← Gate 1 tạo
        ├── [functionId]_01_Requirement_Analysis_QA.md         ← Gate 1 tạo (nếu có issue)
        ├── [functionId]_02_Test_Scenarios_Result.md           ← Gate 2 tạo
        ├── [functionId]_02_Scenario_Building_QA.md            ← Gate 2 tạo (nếu có issue)
        ├── [functionId]_03_Test_Cases_Draft_Result.md         ← Gate 3 tạo
        ├── [functionId]_03_Test_Design_QA.md                  ← Gate 3 tạo (nếu có issue)
        ├── [functionId]_04_Test_Cases_Final_Result.md         ← Gate 4 tạo (cùng TestCase)
        └── [functionId]_04_Test_Review_QA.md                  ← Gate 4 tạo
```

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

---

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

```
(AI-Artifacts/ = 03.Testing/07.AI-Artifacts/ — 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
    ↓
Gate 1: Phân tích yêu cầu & Đánh giá rủi ro  → AI-Artifacts/[functionId]/
    ↓ APPROVED
Gate 2: Xây dựng Kịch bản (Scenario Building) → AI-Artifacts/[functionId]/
    ↓ APPROVED
Gate 3: Thiết kế Test Case chi tiết           → AI-Artifacts/[functionId]/
    ↓ APPROVED
Gate 4: Review & Tối ưu hóa                  → AI-Artifacts/[functionId]/
                                              + 03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md
    ↓ APPROVED (Fully / Conditionally)
Sẵn sàng thực thi kiểm thử
```

---

### GATE 1 — Phân tích yêu cầu & Đánh giá rủi ro (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 Critical/Major) — để Gate 2, 3, 4 phía sau hiếm khi phải dừng lại hỏi thêm.

**Đầu ra (Outputs):**
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_QA.md` (nếu có issue)

**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 `03.Testing/` trong root dự án:
   - **Tìm thấy** → thông báo xác nhận:
     ```
     ✓ Thư mục đầu ra: 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:
     ```
     03.Testing/01.Testcases/[functionId]/
     03.Testing/07.AI-Artifacts/[functionId]/
     ```
     → Thông báo:
     ```
     ✓ Đã tạo thư mục: 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 `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 **chưa** ở branch `feature/[functionId]/[taskId]`:
   - Hỏi QA: "Chưa có branch riêng cho task này trong AK-Docs. Tạo branch `feature/[functionId]/[taskId]` từ `main` — đồng ý không?"
   - QA đồng ý → chạy `ak docs branch [functionId] [taskId] --yes`
   - 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)
4. Nếu **đã** ở đúng branch (ví dụ resume từ session trước) → bỏ qua, tiếp tục.

> ❌ 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 `[functionId]_01_Requirement_Analysis_QA.md` (mục Assumptions, Bước 4) để 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 `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.

#### 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 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`
- Phân tích đầy đủ **16 mục** theo skill 00.01:
  1. Module/Màn hình/Feature cụ thể
  2. Ranh giới scope (In-Scope / Out-of-Scope)
  3. Feature Overview
  4. Main Flow (Happy Path)
  5. Alternative Flows / Ngoại lệ
  6. User Roles / Permissions
  7. Business Rules
  8. Validations (Required, Maxlength, Unique, Format, v.v.)
  9. State / Status
  10. API / External System
  11. Accessibility
  12. Compatibility (Browser/Device)
  13. Test Data dependencies
  14. Third-party integrations
  15. Risk / điểm dễ lỗi
  16. Q&A / Out of Scope
- Đá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 đó).

- **Critical/Major** → **KHÔNG** chỉ gộp vào một file QA 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):
  - Với mỗi nghi vấn ở mục 16 (Q&A/Out of Scope) hoặc phát sinh trong lúc phân tích 16 mục, ư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ở.
  - 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 Critical/Major nào chưa rõ**.
  - Không sinh Result artifact (Bước 3) trước khi toàn bộ Critical/Major đã được làm rõ.
- **Minor** → Ghi TBD marker (`[TBD — <issue-id>: mô tả]`), tiếp tục, carry-forward sang gate sau (không cần dừng hỏi).

#### Bước 3: Soạn thảo kết quả phân tích yêu cầu
- Artifact đầu ra phải có: Feature Summary, Actor & Persona, Business Rules (16 mục), Risk Matrix, Test Scope
- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`

#### Bước 4: Soạn thảo QA Artifact (biên bản resolution, nếu có issue)
- File này ghi lại **kết quả** của Bước 2b (đã hỏi gì, QA trả lời gì) — không phải cơ chế dừng chính.
- Cấu trúc: Metadata, Detected Issues (Severity), Clarification Questions kèm Câu trả lời đã nhận, Assumptions, Resolution Tracking
- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_QA.md`

#### Bước 5: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-1-[functionId].md`
- 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]` → chuyển Gate 2
→ Nếu blocked: làm theo gate-review skill response protocol

**Definition of Done:**
- [ ] `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 `01_Requirement_Analysis_QA.md`
- [ ] File `01_Requirement_Analysis_Result.md` có đủ 16 mục + Risk Matrix + Test Scope
- [ ] Toàn bộ Critical/Major đã đượ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ỏ
- [ ] File `01_Requirement_Analysis_QA.md` đã tạo nếu có issue, ghi lại đầy đủ câu hỏi + câu trả lời (Bước 2b)
- [ ] Không có giả định nào được tự ý chốt thành fact mà không đưa vào QA

> **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 — Xây dựng Kịch bản kiểm thử (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à `01_Requirement_Analysis_Result.md` đã hoàn chỉnh.

**Đầu vào (Inputs):**
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`

**Đầu ra (Outputs):**
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Test_Scenarios_Result.md`
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Scenario_Building_QA.md` (nếu có issue)

**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 `[functionId]_01_Requirement_Analysis_Result.md` — nắm toàn bộ 16 mục, Risk Matrix, Business Rules

#### 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)
- Kiểm tra có domain skill applicable: `.claude/skills/test-skills/categories/08-domain-skills/`
- 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 thảo kết quả Scenario Building
- Bảng Scenarios 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
- Business Flow Mapping (E2E diagram dạng text)
- Draft RTM (Scenario ID → Requirement ID từ `01_Requirement_Analysis_Result.md`)
- **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ừ `[functionId]_TestCase.md` bản trước (không chạy lại Bước 2/3 cho phần này). Ghi rõ 1 cột `Nguồn` (`carry-forward v{N_prev}` / `mới ở v{N}`) trong bảng Scenarios để Gate 3/4 biết phần nào cần thiết kế lại.
- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Test_Scenarios_Result.md`

#### Bước 5: Soạn thảo QA Artifact (nếu có issue — NGOẠI LỆ)
- **Chỉ tạo 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/assumption trong `01_Requirement_Analysis_Result.md` hoặc `01_Requirement_Analysis_QA.md` — đọc lại 2 file đó trước khi quyết định hỏi thêm.
- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Scenario_Building_QA.md`
- Minor issues → TBD marker + carry-forward, tiếp tục workflow

#### Bước 6: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-2-[functionId].md`
- 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:**
- [ ] 100% luồng Happy Path từ 16 mục đã bao phủ
- [ ] Có đủ Negative / Boundary / Exception / Permission scenarios
- [ ] Scenario ID format `TS_<SCREEN_NUMBER>_<SEQ>` đúng quy ước
- [ ] Draft RTM mapping Scenario → Requirement ID đầy đủ
- [ ] Critical/Major issues trong QA file đã giải quyết

> **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 — Thiết kế Test Case chi tiết

**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à `02_Test_Scenarios_Result.md` đã hoàn chỉnh.

**Đầu vào (Inputs):**
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Test_Scenarios_Result.md`

**Đầu ra (Outputs):**
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Cases_Draft_Result.md`
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Design_QA.md` (nếu có issue)

**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.

#### 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`

#### 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 6: Soạn thảo Draft Test Cases
- 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)
- Bổ sung: Coverage Matrix (Scenario ID → TC ID), Test Data tổng hợp
- Ghi TBD marker khi thiếu thông tin: `[TBD — <issue-id>: mô tả ngắn]`
- **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` được copy nguyên trạng từ `[functionId]_TestCase.md` bản trước — không chạy lại qua các category skill.
- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Cases_Draft_Result.md`

#### Bước 7: Soạn thảo QA Artifact (nếu có issue — NGOẠI LỆ)
- **Chỉ tạo 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/assumption trong artifact của Gate 1 hoặc Gate 2 — đọc lại các file đó trước khi quyết định hỏi thêm.
- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Design_QA.md`
- Cấu trúc: Metadata, Detected Issues, Clarification Questions, Assumptions, Resolution Tracking

#### Bước 8: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-3-[functionId].md`
- 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:**
- [ ] 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
- [ ] Coverage Matrix mapping Scenario ID → TC ID đầy đủ
- [ ] TBD marker ghi đúng format khi thiếu thông tin
- [ ] Critical/Major issues trong QA file đã giải quyết

> **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 & Tối ưu hóa

**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, và sinh artifact giao nộp hoàn chỉnh.

**Điều kiện vào Gate 4:** Gate 3 đã **APPROVED** và `03_Test_Cases_Draft_Result.md` đã hoàn chỉnh.

**Đầu vào (Inputs):**
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Cases_Draft_Result.md`

**Đầu ra (Outputs) — sinh ĐỒNG THỜI:**
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_04_Test_Cases_Final_Result.md`
- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_04_Test_Review_QA.md`
- `03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md`

> **Quy tắc Gate 4:** Ba artifact trên phải được sinh ĐỒNG THỜI. Không tạo một file mà thiếu file kia.

**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`
- Checklist review bắt buộc:
  - [ ] 100% Requirement (16 mục) có TC tương ứng?
  - [ ] Không có TC test item Out-of-Scope (mục 2 trong 16 mục)?
  - [ ] Steps rõ ràng, có thể reproduce (không mơ hồ)?
  - [ ] Expected Result cụ thể và đo được (tránh "hoạt động đúng")?
  - [ ] Không có TC trùng lặp logic?
  - [ ] TBD markers ghi đúng `[TBD — <issue-ref>: mô tả]`?
  - [ ] Minor issues carry-forward đã ghi nhận vào QA file?
- **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: Tối ưu hóa bộ Test Case
- Loại bỏ TC trùng lặp, gộp luồng nếu hợp lý
- Phát hiện TC test item Out-of-Scope → sửa và ghi vào Findings
- Kiểm tra traceability xuyên suốt: Req ID → Scenario ID → Draft TC ID → Final TC ID

#### Bước 3: Soạn thảo Final Result (gồm review metadata)
- Artifact `[functionId]_04_Test_Cases_Final_Result.md` gồm:
  - Review Summary (số TC tổng, pass/fail trong review)
  - Review Findings (danh sách issue phát hiện)
  - Coverage Validation (đối chiếu Req → TC)
  - Final Test Cases (Approved, đã loại trùng và out-of-scope)
  - RTM Final (Req ID → Scenario ID → TC ID)
  - Sign-off Status (xem bảng bên dưới)
- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_04_Test_Cases_Final_Result.md`

#### Bước 4: Soạn thảo QA Artifact
- Artifact `[functionId]_04_Test_Review_QA.md` gồm: Metadata, Findings, Issues, Sign-off Status
- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_04_Test_Review_QA.md`

#### Bước 5: Sinh TestCase Artifact — BẮT BUỘC đồng thời với Bước 3 & 4
- Artifact `[functionId]_TestCase.md` theo `testcase-template.md` — **chỉ gồm:**
  - **Mục 1**: Thông tin chung (điền functionId, ngày tạo, **`UC-Spec-Version`/`System-Requirement-Version` = version hiện tại đã dùng ở Gate 1 Bước 0.6 — bắt buộc, đây là mỏ neo cho lần chạy `create-testcase` tiếp theo xác định Mode CREATE/UPDATE**)
  - **Mục 2**: Kết quả kiểm thử tổng hợp (reset về 0 chờ execution — kể cả TC carry-forward từ Mode UPDATE, vì đây là bộ TC cho lần thực thi mới)
  - **Mục 3**: Danh sách Test Cases Chi Tiết (toàn bộ 5 sections đã Approved — Mode UPDATE: gồm cả TC carry-forward nguyên trạng lẫn TC mới/đổi, hợp nhất thành 1 bộ duy nhất, không tách riêng 2 danh sách)
- **KHÔNG chứa:** Review Summary, Findings, RTM, Coverage Matrix, Sign-off (thuộc `04_Final_Result.md`)
- Lưu: `03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md`

#### 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 TBD |
| ✅ **Conditionally Approved** | 0 Critical / 0 Major, còn Minor/TBD — được phép thực thi trừ TC có TBD |
| ⚠️ **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) — ghi `.aiflow/review/gate-4-[functionId].md`
- 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
→ Nếu blocked: làm theo gate-review skill response protocol

**Definition of Done:**
- [ ] `[functionId]_04_Test_Cases_Final_Result.md` có đủ Review Summary, Findings, Coverage Validation, RTM Final, Sign-off
- [ ] `[functionId]_TestCase.md` chỉ chứa Section 1+2+3 theo template chuẩn, không có review metadata
- [ ] Ba file sinh ĐỒNG THỜI — không tạo một thiếu file kia
- [ ] Traceability xuyên suốt: Req ID → Scenario ID → Draft TC ID → Final TC ID
- [ ] 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] \
  --slug <slug-ngắn> --content "<≤150 từ, 1 fact>" \
  --tags <tag1,tag2> --workflows create-testcase --source "[functionId] / Gate 4"
```

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 | `pr-impact-analysis` (Bước 1.5), `QA_Writing_Standards`, `00.01 Requirement Analysis`, `00.02 Risk Analysis` | `01_Requirement_Analysis_Result.md`, `01_QA.md` |
| Gate 2 | `_gate2-always-apply.md` (gộp 00.03 Scenario Builder + 01.06 Error Guessing + 03.02 Workflow Testing), Domain skills | `02_Test_Scenarios_Result.md`, `02_QA.md` |
| 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) | `03_Test_Cases_Draft_Result.md`, `03_QA.md` |
| Gate 4 | `00.04 TC Review`, `99.01 Coverage Review` | `04_Final_Result.md`, `04_QA.md`, `[functionId]_TestCase.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ụ — ghi rõ Assumption và TBD khi thiếu thông tin
- ❌ **KHÔNG** sinh `04_Final_Result.md` mà thiếu `[functionId]_TestCase.md` (hoặc ngược lại)
- ❌ **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/[functionId]/[taskId]` 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 QA artifact
- ✅ **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** ba artifact Gate 4 sinh ĐỒNG THỜI
- ✅ **BẮT BUỘC** Issue Critical/Major phải giải quyết xong trước khi sinh Result artifact
- ✅ **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 Critical/Major, trước khi chuyển Gate 2
- ❌ **KHÔNG** ở Gate 2-4 tạo QA artifact/hỏi lại cho vấn đề đã có câu trả lời hoặc assumption rõ ràng trong artifact của gate trước — QA artifact ở các gate này chỉ dành cho phát sinh THỰC SỰ MỚI
- ✅ **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