@relipa/ai-flow-kit 0.1.2 → 0.1.4-beta.0

package/custom/templates/shared/create-spec-workflow.md

@@ -0,0 +1,441 @@
+## [BA] 4-Gate Spec Creation Workflow
+
+> **For:** `create-spec`
+> **Persona:** Business Analyst (BA)
+> **Goal:** Chuyển đổi yêu cầu thô (Jira / Backlog / file) thành tài liệu Đặc tả Use Case (UC Spec) hoàn chỉnh để bàn giao Dev/Test, tuân theo quy trình UCflow.
+> **Interaction Rules:** Hỏi ONE câu hỏi tại một thời điểm — đợi BA trả lời trước khi tiếp tục. KHÔNG hỏi nhiều câu cùng lúc.
+
+---
+
+### BA Skills
+
+Các skill sau đây được cài tự động vào `.claude/skills/ba-skills/` khi chạy `ak init` hoặc `ak up`.
+
+| Skill | File |
+|---|---|
+| `skill-ba-phan-tich-ban-dau` | `.claude/skills/ba-skills/skill-ba-phan-tich-ban-dau-v1.md` |
+| `skill-ba-qa` | `.claude/skills/ba-skills/skill-ba-qa-v1.md` |
+| `skill-ba-prototype` | `.claude/skills/ba-skills/skill-ba-prototype-v1.md` |
+| `skill-ba-ve-luong-mermaid` | `.claude/skills/ba-skills/skill-ba-ve-luong-mermaid-v1.md` |
+| `skill-ba-xay-dung-business-rules` | `.claude/skills/ba-skills/skill-ba-xay-dung-business-rules-v1.md` |
+| `skill-ba-viet-spec-uc` | `.claude/skills/ba-skills/skill-ba-viet-spec-uc-v1.md` |
+| `template-phan-tich-ban-dau` | `.claude/skills/ba-skills/skill-ba-template-phan-tich-ban-dau-v1.md` |
+| `template-qa` | `.claude/skills/ba-skills/skill-ba-qa-template-v1.md` |
+| `template-uc` | `.claude/skills/ba-skills/skill-ba-template-uc-v1.md` |
+
+---
+
+### Cấu trúc thư mục đầu ra
+
+```
+docs/ak-{project}/spec/
+├── phan-tich/
+│   ├── [functionId]_phan-tich(1).md     ← Gate 1 tạo
+│   └── [functionId]_phan-tich(n).md     ← Gate 2 cập nhật (tăng version)
+├── QA/
+│   ├── [functionId]_QA(1).md            ← Gate 1 tạo
+│   └── [functionId]_QA(m).md            ← Gate 2 tạo thêm nếu còn Open
+├── design/
+│   └── [functionId]_design.html         ← Gate 3 tạo
+└── UC/
+    └── [functionId]_UC.md               ← Gate 4 tạo
+```
+
+Ví dụ: `functionId = AD10`, `project = coinbook` → thư mục gốc là `docs/ak-coinbook/spec/`
+
+---
+
+### Quy trình tổng quan 4 Gates
+
+```
+(spec/ = docs/ak-{project}/spec/ — viết tắt cho ngắn gọn)
+
+[Input: Jira / Backlog / file] → Pre-flight: xác định functionId + thư mục đầu ra
+    ↓
+Gate 1: Phân tích yêu cầu & Tạo Q&A       → spec/phan-tich/ + spec/QA/
+    ↓ APPROVED
+Gate 2: Cập nhật phản hồi Q&A ←─────────────────────────────────────────┐
+    ↓ còn Open → tạo QA(m+1) → đợi BA phản hồi → lặp lại ───────────────┘
+    ↓ tất cả Confirmed + APPROVED
+Gate 3: Thiết kế UI Prototype HTML/CSS     → spec/design/
+    ↓ APPROVED
+Gate 4: Viết đặc tả Use Case Spec          → spec/UC/
+    ↓ APPROVED
+Bàn giao Dev/Test
+```
+
+---
+
+### GATE 1 — Phân tích yêu cầu ban đầu & Tạo Q&A (auto-start)
+
+**Mục tiêu:** Tiếp nhận đầu vào, hiểu nghiệp vụ, phát hiện khoảng trống (Gaps), lập bản phân tích sơ bộ và danh sách Q&A.
+
+**Đầu ra (Outputs):**
+- `docs/ak-{project}/spec/phan-tich/[functionId]_phan-tich(1).md`
+- `docs/ak-{project}/spec/QA/[functionId]_QA(1).md`
+
+**Bước thực hiện:**
+
+#### Bước 0: Pre-flight — Xác định functionId và thư mục đầu ra
+
+**Xác định `functionId`:**
+
+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-10` → `AD10`)
+3. Nếu không tìm thấy → **hỏi BA 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ụ: AD10, UC-LOGIN, PM-003):
+```
+
+→ Đợi BA trả lời, ghi nhận giá trị, dùng cho toàn bộ workflow.
+
+**Xác định `{project}` và thư mục đầu ra:**
+
+1. Lấy `{project}` theo thứ tự ưu tiên:
+   - Trường `project` trong `.aiflow/context/current.json`
+   - Tên thư mục gốc workspace (chuyển lowercase, thay space bằng `-`)
+
+2. Kiểm tra tồn tại thư mục `docs/ak-{project}/spec/` trong root dự án:
+   - **Tìm thấy** → thông báo xác nhận:
+     ```
+     ✓ Thư mục đầu ra: docs/ak-{project}/spec/
+     ✓ functionId: [functionId]
+     → Bắt đầu Gate 1...
+     ```
+   - **Không tìm thấy** → **hỏi BA**:
+     ```
+     Không tìm thấy thư mục docs/ak-{project}/spec/.
+     Tên project là gì? (ví dụ: coinbook, crm-app)
+     ```
+     → Nhận tên project từ BA → chuyển lowercase → tạo toàn bộ cây thư mục:
+     ```
+     docs/ak-{project}/spec/phan-tich/
+     docs/ak-{project}/spec/QA/
+     docs/ak-{project}/spec/design/
+     docs/ak-{project}/spec/UC/
+     ```
+     → Thông báo:
+     ```
+     ✓ Đã tạo thư mục: docs/ak-{project}/spec/
+     ✓ functionId: [functionId]
+     → Bắt đầu Gate 1...
+     ```
+
+#### 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
+- Nếu description có URL → chạy `ak fetch-links <url>` để tải nội dung
+- Nếu có `supplementaryContext[]` → đọc từng item (file đính kèm, ticket liên quan, comment PM)
+- Nếu có file yêu cầu thô được chỉ định → đọc file đó
+
+#### Bước 1b: Đọc Source Code
+
+Chạy ngay sau Bước 1, trước khi bắt đầu phân tích.
+
+Nếu workspace mở dạng parent folder chứa cả `ak docs` lẫn source code repos:
+
+1. Xác định repo liên quan: đọc field `repo` trong `.aiflow/context/current.json`, hoặc suy từ tên module/màn hình. Nếu không rõ → hỏi BA 1 câu: "Feature này thuộc repo nào?"
+2. **Nếu GitNexus MCP có sẵn** (`.mcp.json` có entry `gitnexus`): dùng GitNexus thay vì đọc file trực tiếp:
+   - `gitnexus: query("tên màn hình hoặc chức năng")` → tìm code liên quan
+   - `gitnexus: context("ClassName")` → xem toàn bộ class/service/entity
+3. **Nếu không có GitNexus**: đọc trực tiếp các file liên quan trong repo:
+   - Data models / Entity / DB schema — hiểu cấu trúc dữ liệu hiện tại
+   - API endpoints / Routes — hiểu những gì đã tồn tại
+   - Service / Business Logic — hiểu behavior hiện tại
+   - Config / Constants — ràng buộc kỹ thuật, giới hạn hệ thống
+4. Tích hợp vào phân tích:
+   - Constraints kỹ thuật từ DB schema (kiểu dữ liệu, độ dài, nullable)
+   - Behavior hiện tại của hệ thống (để xác định delta — cái gì cần thêm/sửa/xóa)
+   - Pattern kiến trúc đang dùng (để đề xuất solution phù hợp)
+   - Các API hiện có (tránh đề xuất trùng lặp hoặc mâu thuẫn)
+
+> ⚠️ Source code dùng để **hiểu hệ thống hiện tại** và phát hiện constraints kỹ thuật — giúp BA đặt câu hỏi chuẩn xác hơn và tránh đề xuất giải pháp mâu thuẫn với architecture. Business requirement vẫn đến từ stakeholder, không từ code.
+
+#### Bước 2: Phân tích yêu cầu và xác định Gaps
+- **READ skill:** `.claude/skills/ba-skills/skill-ba-phan-tich-ban-dau-v1.md` và làm theo
+- Phân biệt Facts (thông tin đã chốt) vs Assumptions (tự suy luận cần kiểm chứng)
+- Xem xét các khía cạnh: validate dữ liệu, định dạng nhập liệu, phân quyền, xử lý ngoại lệ, thông báo lỗi
+- Nếu có điểm mơ hồ cốt yếu → hỏi ONE câu làm rõ, đợi BA trả lời trước khi tiếp tục
+
+#### Bước 3: Soạn thảo Kết quả phân tích sơ bộ
+- **READ template:** `.claude/skills/ba-skills/skill-ba-template-phan-tich-ban-dau-v1.md`
+- Điền đầy đủ các mục theo template: Actors, Facts, Assumptions, Gap Analysis table
+- Lưu: `docs/ak-{project}/spec/phan-tich/[functionId]_phan-tich(1).md`
+
+#### Bước 4: Soạn thảo danh sách Q&A
+- **READ skill:** `.claude/skills/ba-skills/skill-ba-qa-v1.md`
+- **READ template:** `.claude/skills/ba-skills/skill-ba-qa-template-v1.md`
+- Chuyển từng Gap thành câu hỏi cụ thể, khách quan, không định hướng
+- Mỗi câu hỏi tương ứng với ít nhất một Gap. Trạng thái ban đầu: **Open**
+- Lưu: `docs/ak-{project}/spec/QA/[functionId]_QA(1).md`
+
+#### Bước 5: Gate Review & Pause
+- **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-1-[functionId].md`
+- **Kiểm tra Q&A bắt buộc:** Đọc `QA(1).md` — đếm số câu có trạng thái **Open**
+- Hiển thị gate pause message — chờ phản hồi từ BA
+
+**Nếu nhận được APPROVED mà QA(1).md còn câu hỏi Open → từ chối ngay, hiển thị:**
+
+```
+⛔ GATE 1 BLOCKED — Còn [N] câu hỏi chưa được trả lời trong QA(1).md.
+
+| ID | Câu hỏi còn Open |
+|----|-----------------|
+| [Q_ID] | [nội dung câu hỏi] |
+
+Vui lòng cung cấp câu trả lời theo một trong 3 cách:
+→ Option A: nhập trực tiếp — `Q1: [trả lời], Q2: [trả lời]`
+→ Option B: paste nội dung bảng Q&A đã điền vào chat
+→ Option C: đặt file `[functionId]_QA(1)_response.md` vào thư mục QA/ rồi gõ NEXT
+
+❌ APPROVED không được chấp nhận cho đến khi 100% câu hỏi đã Confirmed.
+```
+
+**Khi APPROVED (chỉ sau khi tất cả câu hỏi trong QA(1).md đã Confirmed):**
+→ **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` và `{project}` đã được xác định và thư mục đầu ra đã sẵn sàng
+- [ ] File `phan-tich(1).md` tạo đúng vị trí, cấu trúc đúng template, có bảng Gap Analysis
+- [ ] File `QA(1).md` có ít nhất 1 câu hỏi cho mỗi Gap, tất cả trạng thái **Open**
+- [ ] Không có giả định nào được tự ý chốt thành Spec mà không đưa vào Q&A
+
+> **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 — Cập nhật phản hồi Q&A (lặp đến khi tất cả Confirmed)
+
+**Mục tiêu:** Tiếp nhận câu trả lời từ BA/khách hàng, cập nhật trạng thái Q&A, tích hợp thông tin vào tài liệu phân tích, và quyết định vòng Q&A tiếp theo hay chốt để tiến Gate 3.
+
+**Đầu vào (Inputs):**
+- Phản hồi Q&A từ BA (xem 3 option bên dưới)
+- `docs/ak-{project}/spec/phan-tich/[functionId]_phan-tich(n).md` — phiên bản hiện tại
+- `docs/ak-{project}/spec/QA/[functionId]_QA(m).md` — danh sách câu hỏi hiện tại
+
+**Cách BA cung cấp phản hồi (BA chọn một trong 3):**
+- **Option A** — Nhập trực tiếp vào chat: `Q&A: Q1: [trả lời], Q2: [trả lời]`
+- **Option B** — Paste nội dung bảng Q&A đã điền vào chat
+- **Option C** — Đặt file tại: `docs/ak-{project}/spec/QA/[functionId]_QA(m)_response.md`
+
+**Bước thực hiện:**
+
+#### Bước 1: Tiếp nhận và đánh giá câu trả lời
+- **READ skill:** `.claude/skills/ba-skills/skill-ba-qa-v1.md` và làm theo
+- Đối chiếu từng câu trả lời với câu hỏi trong `QA(m).md`
+- Phân loại:
+  - Đủ thông tin → cập nhật trạng thái: **Confirmed**
+  - Chưa rõ hoặc phát sinh nghiệp vụ mới → giữ trạng thái **Open**, bổ sung ghi chú
+
+#### Bước 2: Tích hợp thông tin vào tài liệu phân tích
+- Lấy thông tin từ các câu Confirmed → cập nhật vào `phan-tich(n).md`
+- Xóa các Gap đã được giải quyết khỏi bảng Gap Analysis
+- Tạo phiên bản mới: `docs/ak-{project}/spec/phan-tich/[functionId]_phan-tich(n+1).md`
+
+#### Bước 3: Rẽ nhánh theo trạng thái Q&A
+
+**Kịch bản A — Vẫn còn câu hỏi Open:**
+1. Dùng `skill-ba-phan-tich-ban-dau` kiểm tra `phan-tich(n+1).md` có phát sinh Gap mới không
+2. Tạo: `docs/ak-{project}/spec/QA/[functionId]_QA(m+1).md` theo `skill-ba-qa` — chỉ giữ câu Open và câu mới phát sinh
+3. **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-2-[functionId]-round-[m+1].md`
+4. Hiển thị:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️  GATE 2 — VÒNG Q&A [m+1]
+
+Câu hỏi còn Open: [N]
+File Q&A mới:     [docs/ak-{project}/spec/QA/[functionId]_QA(m+1).md](docs/ak-{project}/spec/QA/[functionId]_QA(m+1).md)
+File phân tích:   [docs/ak-{project}/spec/phan-tich/[functionId]_phan-tich(n+1).md](docs/ak-{project}/spec/phan-tich/[functionId]_phan-tich(n+1).md)
+
+→ BA điền câu trả lời và cung cấp theo một trong 3 option (A/B/C)
+→ Sau khi cung cấp phản hồi, type NEXT để AI xử lý vòng tiếp theo
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+5. Lặp lại Bước 1 khi nhận phản hồi mới
+
+**Nếu BA gõ APPROVED khi đang ở Kịch bản A (còn câu hỏi Open) → từ chối ngay:**
+
+```
+⛔ GATE 2 BLOCKED — Còn [N] câu hỏi chưa Confirmed.
+
+| ID | Câu hỏi còn Open |
+|----|-----------------|
+| [Q_ID] | [nội dung câu hỏi] |
+
+→ Cung cấp câu trả lời (Option A/B/C) rồi gõ NEXT để AI xử lý tiếp.
+❌ APPROVED chỉ được chấp nhận khi 100% câu hỏi đã Confirmed.
+```
+
+**Kịch bản B — Tất cả đã Confirmed:**
+1. Chốt tài liệu phân tích (phiên bản cuối cùng là đầu vào Gate 3)
+2. **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-2-[functionId].md`
+3. Hiển thị gate pause message — đợi **APPROVED**
+
+**Khi APPROVED (chỉ áp dụng Kịch bản B):**
+→ **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:**
+- [ ] Mọi câu trả lời đều được phân tích và phân loại trạng thái
+- [ ] Tài liệu phân tích phiên bản mới tích hợp đầy đủ thông tin nghiệp vụ mới nhất
+- [ ] Không còn câu hỏi nào ở trạng thái **Open** trước khi tiến Gate 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 — Thiết kế giao diện Prototype HTML/CSS
+
+**Mục tiêu:** Dựa trên tài liệu phân tích đã chốt, thiết kế bản mẫu giao diện (Prototype) độc lập bằng HTML/CSS để trực quan hóa các thành phần và luồng tương tác.
+
+**Điều kiện vào Gate 3:** Tất cả Q&A đã **Confirmed** và Gate 2 đã **APPROVED**.
+
+**Đầu vào (Inputs):**
+- `docs/ak-{project}/spec/phan-tich/[functionId]_phan-tich(n).md` — phiên bản cuối
+
+**Đầu ra (Outputs):**
+- `docs/ak-{project}/spec/design/[functionId]_design.html`
+
+**Bước thực hiện:**
+
+#### Bước 1: Liệt kê thành phần giao diện
+- Đọc tài liệu phân tích đã chốt
+- Xác định: ô nhập liệu, nút bấm, liên kết, vùng hiển thị lỗi, vùng hiển thị dữ liệu
+
+#### Bước 2: Thiết kế và viết code HTML/CSS
+- **READ skill:** `.claude/skills/ba-skills/skill-ba-prototype-v1.md` và làm theo
+- Viết HTML ngữ nghĩa cao (semantic HTML)
+- Đặt `id` và `name` **duy nhất** cho MỌI thẻ tương tác (`input`, `button`, `a`, `select`, `textarea`) — phục vụ automation test
+- Nhúng CSS trong thẻ `<style>` ở `<head>` — không gọi external link (offline-friendly)
+- Mã hóa hiệu ứng hover, focus bằng CSS
+
+#### Bước 3: Dựng sẵn Error UI Placeholders
+- Thẻ lỗi tại vị trí tương ứng (dưới ô nhập liệu hoặc banner trên)
+- CSS nổi bật lỗi (chữ đỏ, viền đỏ), mặc định ẩn (`display: none`)
+
+#### Bước 4: Lưu file
+- `docs/ak-{project}/spec/design/[functionId]_design.html`
+
+#### Bước 5: 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:**
+- [ ] File `[functionId]_design.html` tạo đúng vị trí
+- [ ] Giao diện hiển thị đủ tất cả thành phần nghiệp vụ
+- [ ] 100% thẻ tương tác có `id` duy nhất
+- [ ] CSS tự chứa trong file HTML
+
+> **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 — Viết đặc tả Use Case Spec hoàn chỉnh
+
+**Mục tiêu:** Tổng hợp tất cả thông tin nghiệp vụ, giao diện HTML, sơ đồ Mermaid và Business Rules thành tài liệu UC Spec hoàn chỉnh để bàn giao Dev/Test.
+
+**Điều kiện vào Gate 4:** Gate 3 đã **APPROVED** và `design.html` đã hoàn chỉnh.
+
+**Đầu vào (Inputs):**
+- `docs/ak-{project}/spec/phan-tich/[functionId]_phan-tich(n).md` — phiên bản cuối
+- `docs/ak-{project}/spec/design/[functionId]_design.html`
+
+**Đầu ra (Outputs):**
+- `docs/ak-{project}/spec/UC/[functionId]_UC.md`
+
+**Bước thực hiện:**
+
+#### Bước 1: Khởi tạo Spec từ Template
+- **READ template:** `.claude/skills/ba-skills/skill-ba-template-uc-v1.md`
+- **READ skill:** `.claude/skills/ba-skills/skill-ba-viet-spec-uc-v1.md`
+- Tạo: `docs/ak-{project}/spec/UC/[functionId]_UC.md`
+- Điền General Information: Use Case ID, Title, Version, Actors, Preconditions, Postconditions
+
+#### Bước 2: Mô tả luồng sự kiện (Flow of Events)
+- **Main Flow** — happy path
+- **Alternative Flow** — các trường hợp hợp lệ khác
+- **Exception Flow** — lỗi, điều kiện thất bại
+- Viết rõ tương tác Actor ↔ System ở từng bước
+
+#### Bước 3: Tích hợp giao diện Prototype
+- Copy toàn bộ mã HTML/CSS từ `design.html` vào phần Screen Description
+
+#### Bước 4: Mô tả chi tiết UI Components
+- Lập bảng: Tên | Loại | Bắt buộc | Độ dài tối đa | Giá trị mặc định | Ràng buộc validation
+- `id` trong bảng phải khớp chính xác với `id` trong HTML
+
+#### Bước 5: Vẽ sơ đồ hoạt động Mermaid
+- **READ skill:** `.claude/skills/ba-skills/skill-ba-ve-luong-mermaid-v1.md` và làm theo
+- Vẽ Activity Diagram: Main Flow, điểm quyết định (hình thoi), Alternative Flow, Exception Flow
+- Nhúng mã Mermaid vào section Activity Flow của Spec
+
+#### Bước 6: Đặc tả Business Rules (BR)
+- **READ skill:** `.claude/skills/ba-skills/skill-ba-xay-dung-business-rules-v1.md` và làm theo
+- Đặc tả:
+  - **Validation BR**: định dạng, giá trị, bắt buộc
+  - **Processing BR**: logic xử lý khi lưu/cập nhật
+  - **Authorization BR**: phân quyền theo role
+- Mỗi BR có mã `[BR-NNN]`, liên kết với câu thông báo lỗi chính xác trên màn hình
+
+#### 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]` → UC Spec hoàn thành, sẵn sàng bàn giao Dev/Test
+→ Nếu blocked: làm theo gate-review skill response protocol
+
+**Phản hồi đặc biệt:**
+- BA gõ `REVISION: [nội dung]` → cập nhật section liên quan → re-generate review file → hiển thị lại gate pause
+
+**Definition of Done:**
+- [ ] File `[functionId]_UC.md` đúng vị trí và cấu trúc template
+- [ ] 100% element HTML được mô tả trong bảng UI Components (id, loại, ràng buộc)
+- [ ] Mã Mermaid hợp lệ, thể hiện đủ Main/Alternative/Exception Flow
+- [ ] Business Rules đầy đủ với mã `[BR-NNN]` và thông báo lỗi chính xác
+- [ ] Tài liệu không chứa ghi chú mơ hồ hoặc câu hỏi chưa giải quyết
+
+> **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ản đồ Skills theo Gate
+
+| Gate | Skills đọc | Output |
+|---|---|---|
+| Gate 1 | `skill-ba-phan-tich-ban-dau`, `template-phan-tich-ban-dau`, `skill-ba-qa`, `template-qa` | `phan-tich(1).md`, `QA(1).md` |
+| Gate 2 | `skill-ba-qa`, `skill-ba-phan-tich-ban-dau` | `phan-tich(n+1).md`, `QA(m+1).md` (nếu còn Open) |
+| Gate 3 | `skill-ba-prototype` | `design.html` |
+| Gate 4 | `skill-ba-viet-spec-uc`, `template-uc`, `skill-ba-ve-luong-mermaid`, `skill-ba-xay-dung-business-rules` | `_UC.md` |
+
+---
+
+### Quy tắc bắt buộc
+
+- ❌ **KHÔNG** bỏ qua thứ tự Gate — luôn đi từ Gate 1 → 2 → 3 → 4
+- ❌ **KHÔNG** tự chốt giả định nghiệp vụ mà không đưa vào Q&A
+- ❌ **KHÔNG** tiến Gate 3 khi vẫn còn câu hỏi Open
+- ❌ **KHÔNG chấp nhận APPROVED** ở Gate 1 hoặc Gate 2 khi còn bất kỳ câu hỏi nào trạng thái **Open** — từ chối và hiển thị danh sách câu hỏi cần trả lời
+- ✅ **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** đọc skill từ `.claude/skills/ba-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** mọi thẻ tương tác trong HTML có `id` duy nhất
+- ✅ **BẮT BUỘC** CSS tự chứa trong HTML (không external link)
+- ✅ **BẮT BUỘC** mỗi BR có mã `[BR-NNN]` và câu thông báo lỗi cụ thể