## [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. Số lượng câu hỏi KHÔNG cố định — phải phản ánh đúng độ phức tạp thực tế của yêu cầu (xem chi tiết ở Gate 1 Bước 2).

---

### Quy ước Blocking / Non-blocking & đánh dấu PENDING

> Áp dụng cho **cả 4 Gate** — dùng để quyết định câu hỏi nào bắt buộc phải Confirmed trước khi tiến gate tiếp theo, và câu nào được phép defer mà vẫn cho qua.

Mỗi Gap/Assumption/câu hỏi Q&A phải được gắn nhãn mức độ ảnh hưởng ngay khi phát hiện:

- **🔴 Blocking** — chưa trả lời thì KHÔNG thể tiến gate tiếp theo một cách đáng tin cậy. Gồm: ảnh hưởng cấu trúc dữ liệu (thêm/sửa field, quan hệ), luồng chính (happy path) của use case, phân quyền/bảo mật, hoặc quyết định kiến trúc khó đảo ngược sau khi đã code.
- **🟡 Non-blocking** — có thể tạm ghi Open (deferred) và vẫn đi tiếp. Gồm: chi tiết UI/text hiển thị, giá trị mặc định có thể chỉnh sau, alternative/exception flow hiếm gặp, câu hỏi cần chờ khách hàng xác nhận nhưng không chặn thiết kế các phần khác.

**Khi BA/khách hàng defer (chưa trả lời ngay) một câu hỏi:**

- 🟡 Non-blocking → đánh dấu **Open**, tiếp tục ngay sang câu hỏi kế tiếp hoặc gate kế tiếp — KHÔNG chặn.
- 🔴 Blocking → AI phải hiển thị cảnh báo rõ lý do đây là blocking + hệ quả nếu bỏ qua, rồi hỏi xác nhận BA có chắc muốn tiếp tục không. Nếu BA xác nhận đồng ý tiếp tục dù chưa trả lời → vẫn đánh dấu Open nhưng giữ nhãn 🔴 Blocking (không được hạ xuống Non-blocking) — mục "Điều kiện dừng chặn APPROVED" ở mỗi Gate dựa vào nhãn này.

**Đánh dấu PENDING trong tài liệu output:** bất kỳ nội dung nào phụ thuộc vào một câu hỏi còn Open (Blocking hoặc Non-blocking) phải ghi rõ marker tại đúng vị trí liên quan trong `Analysis_v(n).md` / `UI-Prototype` / `UC-Spec_v{N}.md`, thay vì tự suy diễn nội dung để lấp đầy:

```
⚠️ [PENDING - QA-0N] <mô tả ngắn nội dung còn thiếu>
```

---

### Quy tắc phụ thuộc câu hỏi & chống hỏi thừa

> Áp dụng cho **cả 4 Gate**. Mục tiêu: BA/khách hàng chỉ nhận đúng những câu hỏi mà câu trả lời **hiện tại** là khả thi và có giá trị — không bị hỏi tiếp các câu đã bị chặn bởi một câu còn Open.

**1. Dựng bản đồ phụ thuộc TRƯỚC khi hỏi.** Sau khi liệt kê xong danh sách Gap và trước khi hỏi câu đầu tiên, với mỗi câu hỏi phải điền trường `Phụ thuộc`:

- `Phụ thuộc: —` — câu hỏi độc lập, hỏi được ngay.
- `Phụ thuộc: QA-xx` — câu trả lời chỉ có nghĩa (hoặc chỉ xác định được tập lựa chọn) sau khi QA-xx đã Confirmed. Dấu hiệu nhận biết: câu hỏi chi tiết hoá một quyết định phạm vi/rule của QA-xx; các Option của nó thay đổi tuỳ theo QA-xx chọn gì; hoặc câu hỏi trở nên vô nghĩa với ít nhất một đáp án khả dĩ của QA-xx.

**2. Cascade defer — KHÔNG hỏi câu con khi câu cha còn Open.** Câu cha ở trạng thái Open (Blocking hay Non-blocking đều vậy) → 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 câu con được gắn 🔴 Blocking.
- Ghi trạng thái **`Blocked-by QA-xx`** trong `QnA-Log`, không phải `Open` độc lập và không phải câu hỏi mới.
- Dùng lại marker của câu cha `⚠️ [PENDING - QA-xx]` trong tài liệu output — không sinh thêm marker riêng cho câu con.
- Chỉ mở khoá (chuyển sang hỏi được) khi câu cha chuyển sang **Confirmed** — xem Gate 2 Bước 1.

**3. Thứ tự hỏi.** Hỏi theo topo của bản đồ phụ thuộc: câu cha trước câu con. Trong cùng một mức, hỏi 🔴 Blocking trước 🟡 Non-blocking.

**4. Kiểm tra trước mỗi câu hỏi (3 điều kiện, đủ cả 3 mới được hỏi).** Trước khi phát ra bất kỳ câu hỏi nào — Gate 1 Bước 2 hoặc vòng Q&A mới ở Gate 2:

- (a) **Chưa được trả lời ở đâu khác và không suy ra được** — không có câu trả lời Confirmed nào trong `QnA-Log` các version trước, trong `Analysis_v(n).md`, hoặc trong chính câu trả lời BA vừa đưa ở câu trước đã bao phủ nội dung này; và không suy ra được từ bảng "Quyết định đã chốt + hệ quả suy ra" (xem [Quy tắc chống hỏi trùng](#quy-tắc-chống-hỏi-trùng--suy-ra-từ-quyết-định-đã-chốt)).
- (b) **Không bị chặn** — trường `Phụ thuộc` trống, hoặc mọi câu cha đã Confirmed.
- (c) **Câu trả lời làm thay đổi output** — biết đáp án thì nội dung Analysis / UI Prototype / UC Spec / test case thay đổi. Nếu đáp án chỉ đổi câu chữ hiển thị hoặc một giá trị mặc định có thể chỉnh sau khi code mà không đổi cấu trúc → **không hỏi**, ghi thành Assumption kèm marker `[PENDING]` và để BA phản hồi sau.

Câu nào trượt một trong ba điều kiện → bỏ qua, ghi lý do vào `QnA-Log` (`Đã trả lời tại QA-xx` / `Suy ra từ QA-xx` / `Blocked-by QA-xx` / `Assumption — không hỏi`), chuyển sang câu tiếp theo.

Câu nào qua đủ ba điều kiện → soạn theo [Quy tắc chất lượng câu hỏi](#quy-tắc-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, vì sao hỏi, một ý, options kèm hệ quả, giải nghĩa viết tắt, ví dụ minh hoạ nếu phức tạp) trước khi gửi.

**5. Điểm dừng kiểm tra tải câu hỏi.** Sau mỗi **10 câu hỏi** đã phát ra trong một vòng, dừng lại và hiển thị:

```
Đã hỏi [N] câu, còn [M] câu trong danh sách ([X] 🔴 Blocking, [Y] 🟡 Non-blocking).
→ Tiếp tục: gõ NEXT
→ Defer toàn bộ câu 🟡 Non-blocking còn lại (đánh Open + marker PENDING, đi tiếp): gõ DEFER-NB
```

Tôn trọng lựa chọn của BA — `DEFER-NB` không áp dụng cho câu 🔴 Blocking (những câu này vẫn phải hỏi, hoặc Open kèm cảnh báo theo quy ước trên).

**6. Không lách luật.** Không được tách một câu bị chặn thành nhiều câu nhỏ để "hỏi lách" quanh câu cha còn Open. Không hạ nhãn 🔴 Blocking của câu con để né quy tắc cascade.

**7. Tự tìm hiểu trước khi hỏi — chỉ hỏi thứ không quan sát được.** Trước khi đưa một Gap thành câu hỏi, phải quét repo/config/tài liệu `AK-Docs/`/ticket để xem câu trả lời có sẵn không. Thứ **quan sát được** (quy ước dự án, môi trường, ngôn ngữ giao diện, thư viện/kiểu triển khai hiện tại, dữ liệu mẫu đang có) → **tự điền kèm nguồn, không hỏi**; không tìm thấy thì dùng mặc định hợp lý và ghi `[mặc định]` vào Assumption. Chỉ hỏi khi đó là **chính sách/đánh đổi** của dự án hoặc **mâu thuẫn/thiếu trong nghiệp vụ**. Muốn chắc về giá trị đã suy ra → viết khẳng định `Tôi dùng <giá trị> (nguồn: <bằng chứng>) — sai thì báo tôi sửa.` rồi đi tiếp, không dừng chờ. Nhiều mục thiết lập cùng loại → gộp vào **một** bảng xác nhận trả lời một lần, không rải thành chuỗi câu hỏi.

---

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

> Áp dụng cho **mọi câu hỏi** phát ra ở cả 4 Gate. Người đọc mặc định là khách hàng/PO **không** đọc code, không biết tên bảng/field/API của hệ thống.

**1. Mỗi câu hỏi là một khối tự đứng một mình được.** Người đọc chỉ nhìn đúng khối đó (không đọc lại tài liệu, không nhớ 20 câu trước) vẫn hiểu và trả lời được.

**Cấm trình bày danh sách câu hỏi dưới dạng bảng.** Bảng nhiều cột buộc người đọc quét ngang mới ghép được nghĩa một câu hỏi, và cột nào cũng hẹp nên chữ xuống dòng vụn.

Khối gồm tiêu đề, hai dòng thông tin, rồi các mục có tên in đậm (không đánh số):

```text
## Q{n}. [Màn hình/Chức năng] Về {chủ đề}
QA-0N ・ 🔴 Blocking ・ Đang chờ trả lời (Open)
Cần PM / Khách hàng trả lời. Chưa đặt hạn, không phụ thuộc câu hỏi nào khác.

**Hiện trạng:**
    <hệ thống hiện đang làm gì; tính năng mới thì ghi "Chưa có (tính năng mới)">

**Bối cảnh:**
    <yêu cầu nào dẫn tới câu hỏi. Chưa chốt thì ảnh hưởng gì.>

**Vấn đề:**                      ← bỏ hẳn mục nếu không có
    <điểm chưa rõ, mâu thuẫn, hoặc rủi ro>

**Câu hỏi:**
    <một câu, một chủ đề, ưu tiên câu hỏi đóng>

**Lựa chọn và đề xuất:**
    A: <option>
    B: <option>
    C: Khác (khách tự mô tả) / Chưa quyết định, cần thời gian.
    Đề xuất của Relipa: A. Lý do: <lý do>

**Ví dụ minh họa:**              ← bỏ hẳn mục nếu không có
    <tình huống bám dữ liệu/màn hình thật>
    Nếu chọn A: <kết quả>. Nếu chọn B: <kết quả>.

**Câu trả lời:**
    <nội dung trả lời; câu còn Open ghi "Chưa trả lời.", kèm lý do nếu có>

**Người trả lời:** —
**Ngày trả lời:** —
**Nguồn:** —
```

Quy tắc trình bày khi ghi file — mục tiêu là đọc như người viết tay, không như bản AI xuất ra:
- **Tên mục in đậm, kết thúc bằng dấu `:`, không đánh số.** Mỗi mục cách mục sau **đúng 1 dòng trống**. Không có dòng trống giữa tên mục và nội dung.
- **Nội dung mục thụt vào 4 dấu cách**, mọi dòng nội dung đều thụt. Không dùng bullet `・` hay `-`. Mỗi ý xuống dòng riêng.
- **Hai dòng thông tin ngay dưới tiêu đề, viết như người nói:**
  - Dòng 1: `<Mã> ・ <Mức độ> ・ <Trạng thái>`. Trạng thái ghi tiếng Việt, giữ từ khoá gốc trong ngoặc để tra cứu: `Đang chờ trả lời (Open)`, `Đã chốt (Confirmed)`, `Chờ QA-xx chốt trước (Blocked-by QA-xx)`.
  - Dòng 2: một câu nói ai cần trả lời, hạn, và phụ thuộc. Có hạn → `Cần PM / Khách hàng trả lời trước 15/10.`; chưa có hạn → `Chưa đặt hạn`. Không phụ thuộc → `không phụ thuộc câu hỏi nào khác`; có câu cha → `Chỉ trả lời được sau khi QA-xx được chốt.` Không viết dấu `—` cho trường trống.
- **Lựa chọn:** A, B… rồi chữ cái kế tiếp luôn là `Khác (khách tự mô tả) / Chưa quyết định, cần thời gian.` Dòng `Đề xuất của Relipa: <chữ cái>. Lý do: <lý do>` đặt **sau** dòng Khác, lý do viết thành câu, không để trong ngoặc. **Không ghi công số** (cao/thấp/số ngày) trong file. Hệ quả nghiệp vụ của option vẫn ghi (ví dụ `phát sinh chi phí tin nhắn`, `(chưa có, cần làm mới)`).
- **Ví dụ minh họa:** dòng tình huống, rồi kết quả theo từng option viết `Nếu chọn A: … Nếu chọn B: …`.
- **Câu trả lời:** chỉ chứa nội dung trả lời. `Người trả lời`, `Ngày trả lời`, `Nguồn` là ba dòng riêng **ngang cấp** với `Câu trả lời:` (tên in đậm, giá trị cùng dòng, không thụt, ba dòng liền nhau). Câu còn Open thì ba dòng này ghi `—`.
- **Ngắt dòng khi render markdown:** mọi dòng trong cùng một khối (hai dòng thông tin; tên mục và các dòng nội dung; ba dòng Người trả lời / Ngày / Nguồn), **trừ dòng cuối của khối**, kết thúc bằng **2 dấu cách** (hard line break). Thiếu 2 dấu cách thì khi xem dạng render (GitLab, Backlog, VS Code preview) các dòng bị gộp thành một đoạn. Không chèn dòng trống giữa tên mục và nội dung thụt lề: dòng thụt 4 dấu cách đứng sau dòng trống bị render thành code block.

- **Tiêu đề là cụm danh từ, không phải câu hỏi.** Viết `Về phạm vi sản phẩm hiển thị cho buyer chưa thuộc group nào`, không viết `Buyer chưa thuộc group thì thấy gì?`. Câu hỏi nằm ở mục `Câu hỏi`; tiêu đề để người đọc lướt qua là biết câu này nói về việc gì.
- **Hiện trạng và Bối cảnh tách riêng.** Hiện trạng là sự thật hệ thống đang có; Bối cảnh là lý do bây giờ phải hỏi. Viết lẫn thì khách nhầm giữa cái đang có với cái sắp làm.
- **Mốc sự kiện trong Bối cảnh phải cụ thể.** Cấm nói tắt kiểu "khi bật `group`", "sau khi có tính năng X" — không tương ứng với thao tác hay mốc nào có thật, người đọc không phân biệt được lúc phát hành mã nguồn, lúc dữ liệu được gán xong, hay lúc có công tắc cấu hình. Viết thẳng: "sau khi phát hành chức năng quản lý `group`", "khi `admin` tạo `group` đầu tiên".
- **Câu hỏi** đúng **một ý**. Có 2 ý → tách thành 2 câu hỏi.
- **Options** nói rõ mỗi option dẫn tới kết quả gì cho người dùng, không chỉ đặt tên option. Thêm dòng `Đề xuất của Relipa` kèm lý do — nội dung Relipa tự đề xuất phải ghi rõ là đề xuất, không viết như yêu cầu đã có. Luôn có dòng `Khác (khách tự mô tả) / Chưa quyết định, cần thời gian`.
- **Mục `Vấn đề` và `Ví dụ minh họa` bỏ hẳn khi không có nội dung** — không để tên mục rỗng hay dấu `—`.

**1b. Hai dạng trình bày: dạng gọn khi hỏi trong chat, dạng đầy đủ khi ghi file.** Khối đầy đủ ở trên là dạng ghi vào `QnA-Log_v(m).md` — người đọc là khách hàng, đọc lại sau nhiều ngày, nên mỗi khối phải tự đứng được. Khi hỏi BA **trực tiếp trong hội thoại** (Gate 1 Bước 2), BA đang có sẵn ngữ cảnh ticket và trả lời ngay, nên dùng dạng **gọn** dưới đây. Phản hồi thật khi thấy khối đầy đủ trong chat: một câu hỏi chiếm khoảng 25 dòng, cần trình bày ngắn gọn hơn mà vẫn đủ ý.

```text
**Q{n}/{tổng} · 🔴 Blocking · QA-0N** — [Màn hình/Chức năng] {chủ đề}
Phụ thuộc: QA-xx đã chốt "<quyết định>"          ← chỉ in khi có câu cha

**Hiện tại:** <sự thật hệ thống đang có; tính năng mới thì ghi "Chưa có (tính năng mới)">
**Thay đổi:** <yêu cầu dẫn tới câu hỏi, nêu mốc sự kiện cụ thể>

❓ <một câu hỏi, một ý>

- **A.** <option>. <ảnh hưởng phạm vi/công số>. ⭐ Relipa đề xuất: <lý do một vế>
- **B.** <option>. <ảnh hưởng phạm vi/công số>.
- **Khác / chưa quyết** → ghi Open vào QnA-Log.

VD: <tình huống thật> → A: <kết quả người dùng thấy> · B: <kết quả>   ← chỉ câu phức tạp

↳ Trả lời: `A` / `B` / `Khác: …` / `Open` · gõ `chi tiết` để xem bản đầy đủ
```

Quy tắc rút gọn — **gọn về cách trình bày, không bớt nội dung cần để ra quyết định**:
- **Dòng đầu** gộp tiêu đề và dòng thông tin: chỉ giữ số thứ tự / tổng số câu hiện tại (được phép tăng khi phát sinh Gap mới), `Mức độ`, `Mã`, chủ đề. `Hạn trả lời`, `Người cần trả lời`, `Trạng thái` mang giá trị mặc định nên không in trong chat — vẫn ghi đủ vào file. `Phụ thuộc` chỉ in khi có câu cha, kèm quyết định đã chốt của câu cha.
- **`Hiện tại:` / `Thay đổi:`** thay cho mục `Hiện trạng` và `Bối cảnh`, mỗi dòng **tối đa 2 câu**. Vẫn giữ tách biệt cái đang có với cái sắp làm, vẫn áp dụng quy tắc mốc sự kiện cụ thể. Ý "chưa chốt thì ảnh hưởng gì" chỉ viết vào `Thay đổi:` khi các option chưa thể hiện được ảnh hưởng đó.
- **Mục `Vấn đề`** không thành dòng riêng — gộp vào `Thay đổi:` hoặc vào câu hỏi.
- **Options** mỗi option **một dòng**, kèm ảnh hưởng phạm vi/công số. Đề xuất của Relipa đánh dấu `⭐` ngay trên dòng option được đề xuất, lý do một vế — không tách dòng riêng. Option chưa có trong hệ thống vẫn ghi `(chưa có, cần làm mới)`. Dòng cuối luôn là `Khác / chưa quyết`.
- **Ví dụ** một dòng, chỉ cho câu phức tạp (xem mục 3), nêu kết quả theo từng option.
- **Bỏ** các câu dẫn kiểu "hệ quả này sẽ hỏi riêng ở câu sau" — thứ tự câu hỏi đã do bản đồ phụ thuộc quyết định.
- Độ dài mục tiêu: **khoảng 12 dòng** một câu. Vượt nhiều → câu hỏi đang gộp nhiều ý, tách theo mục 4.
- Mọi quy tắc khác giữ nguyên ở dạng gọn: thuật ngữ theo Glossary, giải nghĩa viết tắt, nguồn thật cho option/ví dụ (mục 3bis), self-check (mục 5).
- BA gõ **`chi tiết`** → in lại khối đầy đủ của câu đang hỏi, đúng format ghi file ở mục 1 (ví dụ để chụp gửi khách), rồi chờ trả lời như bình thường.
- Khi ghi `QnA-Log` (Gate 1 Bước 4), mỗi câu đã hỏi ở dạng gọn được **mở rộng về khối đầy đủ** theo quy tắc trình bày ở mục 1: cùng câu hỏi, cùng options, cùng đề xuất — chỉ triển khai câu chữ, không thêm option hay sự thật mới so với lúc hỏi BA. Ghi chú công số của dạng gọn **không** chép sang file.

> ❌ **KHÔNG** viết mục "Vì sao cần hỏi" thành một mục riêng — không trong câu hỏi gửi ra, không trong câu hỏi hỏi trực tiếp trong hội thoại, không trong `QnA-Log`. Phần đó **gộp vào mục `Bối cảnh`** dưới dạng một ý "chưa chốt thì ảnh hưởng gì". Khách hàng cần biết mình phải quyết điều gì và mỗi lựa chọn dẫn tới đâu — một mục riêng kể lại lý do BA cần thông tin chỉ làm câu hỏi dài gấp đôi. Phản hồi thật từ PM khi đọc câu hỏi có mục này trong chat: "nội dung khá rườm rà". (Self-check "đáp án đổi mục nào trong output" ở §5 vẫn chạy — chỉ là **không viết vào tài liệu**.)

**2. Ngôn ngữ.**
- Viết cho người không technical: không dùng tên bảng, tên cột, tên API, tên biến, tên file trong phần Bối cảnh/Câu hỏi/Options. Cần thiết lắm thì để trong ngoặc phụ chú ở cuối, sau phần diễn đạt nghiệp vụ.
- **Thuật ngữ nghiệp vụ dùng nguyên từ dự án đang dùng, cấm tự dịch.** Dự án eccore gọi là `group` thì viết `group`, không viết "nhóm"; `buyer` không viết "cửa hàng"; `import` không viết "nhập". Nguồn từ vựng bắt buộc là `AK-Docs/00.Project-Overview/Glossary.md` (xem [Bước 0.6](#bước-06-glossary-dự-án--đọc-trước-khi-soạn-câu-hỏi-đầu-tiên) và `custom/rules/domain-terminology.md`). Không tìm được từ dự án dùng cho một khái niệm → **hỏi user**, không tự đặt từ, rồi ghi câu trả lời ngược vào `Glossary.md` ngay.
- **Thuật ngữ tiếng Nhật không đứng một mình trong câu tiếng Việt/tiếng Anh.** Viết tên gọi theo cột `Viết trong tài liệu` của Glossary, kèm chữ gốc trong ngoặc ở lần đầu trong mỗi khối câu hỏi: "nhà cung cấp (サプライヤー)", "danh sách `buyer` (得意先一覧)". Glossary chưa có tên gọi → đề xuất một tên để BA xác nhận rồi ghi vào Glossary, không tự dịch rồi dùng luôn. Chi tiết: `custom/rules/domain-terminology.md`, mục "Thuật ngữ tiếng Nhật".
- **Mọi từ viết tắt và thuật ngữ nội bộ phải được giải nghĩa ngay lần xuất hiện đầu tiên trong câu hỏi**, dạng `<viết tắt> (<nghĩa đầy đủ, 3–10 từ>)`. Không giả định người đọc biết từ viết tắt chỉ vì nó có trong ticket.
- Không dùng ký hiệu nội bộ của AI/quy trình trong nội dung câu hỏi (ID nội bộ, tên pattern đánh số) mà chưa nói pattern đó là gì.

**3. Câu hỏi phức tạp phải có ví dụ minh hoạ.** Câu hỏi được coi là phức tạp khi: có từ 2 điều kiện trở lên, ảnh hưởng nhiều màn hình/nhiều luồng, hoặc nói về thứ tự/ưu tiên/thời điểm. Khi đó bắt buộc thêm khối:

```
Ví dụ minh hoạ: <một tình huống cụ thể, dùng màn hình/trường có thật, số liệu/ngày giờ cụ thể>
→ 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>
```

**3bis. Ví dụ và Options phải bám sát hệ thống thực tế — cấm giả định ngoài mô tả.** Một option hay ví dụ mô tả chức năng hệ thống không có làm khách hàng tưởng thứ đó đã sẵn sàng rồi chốt theo nó; sai lầm này chỉ lộ ra ở Gate 4 hoặc khi Dev code. Với **từng** option và **từng** ví dụ, phải chỉ ra được nguồn thì mới giữ lại:

| Nguồn hợp lệ | Ví dụ |
| :--- | :--- |
| Mô tả yêu cầu / ticket / acceptance criteria | "ticket nói nút import nhận file CSV" |
| Tài liệu trong `AK-Docs/` — UC Spec, QnA-Log version trước, biên bản họp | "UC Spec v2 mục 4.3 đã mô tả màn hình xác nhận" |
| Màn hình, nhãn nút, thông báo thật trong mã nguồn frontend | "màn hình quản lý group có nút `import`" |
| Hành vi thật trong mã nguồn backend (validate, trạng thái, quyền) | "hệ thống đang khoá tài khoản sau 5 lần sai" |

- Không chỉ ra được nguồn → **bỏ option/ví dụ đó**. Cần nêu một hướng xử lý chưa có trong hệ thống → gộp vào option `Khác — mô tả ngắn`, không dựng nó thành một option nghe như đã có sẵn.
- Option mô tả hành vi hệ thống **chưa có** nhưng cần đưa ra để khách hàng chọn → ghi `(chưa có, cần làm mới)` ngay trong option.
- Tên màn hình, vai trò, trạng thái, nút trong ví dụ phải **đúng như hệ thống đang gọi** (theo Glossary), không đặt tên mới cho dễ đọc.
- Số liệu, ngày giờ, tên người trong ví dụ được phép là dữ liệu minh hoạ. **Trường, màn hình, bước chứa chúng thì không** — không bịa thêm một trường "Ghi chú" hay một màn hình "Xác nhận" chỉ để ví dụ chạy trôi.

**4. Độ dài và tách câu.** Bối cảnh không quá 3 câu. Nế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 nhỏ (và điền `Phụ thuộc` giữa các câu vừa tách).

**5. Self-check bắt buộc trước khi gửi mỗi câu hỏi.** Trả lời được cả 3 ý sau thì mới gửi:
- Đáp án sẽ làm thay đổi **cụ thể mục nào** trong tài liệu output? (không nêu được → không hỏi). Đây là kiểm tra nội bộ — **không** viết câu trả lời này vào tài liệu.
- Người không technical đọc câu này có hiểu ngay không? (không → viết lại, không gửi kèm lời xin lỗi "câu này hơi kỹ thuật")
- Mỗi option và mỗi ví dụ trong câu này chỉ ra được nguồn thật chưa? (xem mục 3bis — không có nguồn → bỏ hoặc gộp vào "Khác")
- Mọi thuật ngữ nghiệp vụ trong câu đã lấy từ `Glossary.md` chưa, có từ nào bị tự dịch không? Còn chữ tiếng Nhật nào đứng một mình, chưa có tên gọi đi kèm không?
- Câu này đã được trả lời hoặc suy ra được từ quyết định đã chốt chưa? (xem [Quy tắc chống hỏi trùng](#quy-tắc-chống-hỏi-trùng--suy-ra-từ-quyết-định-đã-chốt))

---

### Quy tắc chống hỏi trùng — suy ra từ quyết định đã chốt

> Số lượng câu hỏi **không phải** thước đo chất lượng phân tích. Hỏi thừa làm người trả lời mất thời gian và giảm niềm tin vào cả bộ câu hỏi. Chủ động 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".** Sau **mỗi** câu trả lời Confirmed, ghi ngay vào bản nháp phân tích:

| Quyết định (từ QA-xx) | Hệ quả suy ra trực tiếp (không cần hỏi lại) |
|---|---|
| Không retry khi gửi thất bại | Không có số lần retry; không có khoảng cách giữa các lần retry; không retry cho các kênh khác trong cùng luồng gửi (email, push, SMS); không có màn hình/log theo dõi retry; lỗi gửi chỉ ghi nhận 1 lần |

Hệ quả suy ra là **một phần của câu trả lời**, không phải câu hỏi mới.

**2. So khớp theo ý định nghiệp vụ, không theo chữ.** Trước khi gửi bất kỳ câu hỏi nào, đối chiếu ý định của nó với bảng trên. Cấm hỏi lại cùng một quyết định bằng cách diễn đạt khác hoặc từ đồng nghĩa — ví dụ `retry` = `gửi lại` = `thử lại` = `re-send` = `chạy lại`; `khoá tài khoản` = `tạm ngưng đăng nhập`. Trùng ý định → **không hỏi**, ghi vào QnA-Log dòng `Suy ra từ QA-xx: <nội dung suy ra>` với trạng thái **Confirmed**.

**3. Khi không chắc đáp án cũ có bao phủ hay không.** Không soạn một câu hỏi mới đầy đủ. Hỏi **đúng một câu xác nhận yes/no**, nêu rõ suy luận:

```
Xác nhận nhanh: theo QA-xx đã chốt "<quyết định>", suy ra "<hệ quả áp dụng cho trường hợp đang xét>". Đúng không? (Có / Không — nếu Không, mô tả điểm khác biệt)
```

Chỉ hỏi xác nhận **một lần** cho mỗi suy luận. Người trả lời xác nhận "Có" → đóng luôn, không mở câu hỏi chi tiết tiếp theo về cùng quyết định đó.

**4. Cấm hỏi lấy số lượng.** Không thêm câu hỏi chỉ để danh sách trông đầy đủ, để "phòng hờ", hoặc để chứng minh đã phân tích kỹ. Câu hỏi không làm đổi nội dung output → ghi thành Assumption kèm marker `[PENDING]`, không hỏi.

**5. Khi người trả lời hỏi ngược "câu này có cần thiết không?".** Đây là tín hiệu quy tắc trên đã bị vi phạm. Xử lý: trả lời thẳng câu đó có cần hay không kèm lý do; nếu không cần → rút câu hỏi, ghi `Rút — suy ra từ QA-xx` vào QnA-Log; và **rà lại toàn bộ các câu chưa hỏi còn lại** bằng mục 2 trước khi hỏi tiếp câu kế.

---

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

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

---

### 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-initial-analysis-v1.md` |
| `skill-ba-qa` | `.claude/skills/ba-skills/skill-ba-qna-v1.md` |
| `skill-ba-prototype` | `.claude/skills/ba-skills/skill-ba-ui-prototype-v1.md` |
| `skill-ba-ve-luong-mermaid` | `.claude/skills/ba-skills/skill-ba-mermaid-flowchart-v1.md` |
| `skill-ba-xay-dung-business-rules` | `.claude/skills/ba-skills/skill-ba-build-business-rules-v1.md` |
| `skill-ba-viet-spec-uc` | `.claude/skills/ba-skills/skill-ba-write-uc-spec-v1.md` |
| `template-phan-tich-ban-dau` | `.claude/skills/ba-skills/skill-ba-initial-analysis-template-v1.md` |
| `template-qa` | `.claude/skills/ba-skills/skill-ba-qna-template-v1.md` |
| `template-uc` | `.claude/skills/ba-skills/skill-ba-uc-template-v1.md` |

---

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

```
AK-Docs/02.BA-Specs/
├── 01.Analysis/
│   ├── [functionId]/Analysis_v1.md      ← Gate 1 tạo
│   └── [functionId]/Analysis_vn.md      ← Gate 2 cập nhật (tăng version)
├── 02.QnA/
│   ├── [functionId]/QnA-Log_v1.md       ← Gate 1 tạo
│   └── [functionId]/QnA-Log_vm.md       ← Gate 2 tạo thêm nếu còn Open
├── 03.UI-Prototypes/
│   └── [functionId]/UI-Prototype_v1.html← Gate 3 tạo
└── 04.UC-Specs/
    └── [functionId]/UC-Spec_v{N}.md       ← Gate 4 tạo (N=1 nếu CREATE, N=version mới nếu UPDATE)
```

Ví dụ: `functionId = AD10` → thư mục gốc là `AK-Docs/02.BA-Specs/`

> ⚠️ **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/02.BA-Specs/...`. **CẤM** tạo thư mục `02.BA-Specs/` ở workspace root hoặc bên trong source repo.

---

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

```
(BA-Specs/ = AK-Docs/02.BA-Specs/ — viết tắt cho ngắn gọn)

[Input: Jira / Backlog / file] → Pre-flight: BẮT BUỘC xác định functionId
    ↓
Gate 1: Phân tích yêu cầu & Tạo Q&A       → BA-Specs/01.Analysis/ + BA-Specs/02.QnA/
    ↓ APPROVED
Gate 2: Cập nhật phản hồi Q&A ←─────────────────────────────────────────┐
    ↓ còn Open → tạo QnA-Log_v(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     → BA-Specs/03.UI-Prototypes/
    ↓ APPROVED
Gate 4: Viết đặc tả Use Case Spec          → BA-Specs/04.UC-Specs/
    ↓ 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):**
- `AK-Docs/02.BA-Specs/01.Analysis/[functionId]/Analysis_v1.md`
- `AK-Docs/02.BA-Specs/02.QnA/[functionId]/QnA-Log_v1.md`

**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-10` → `AD10`)
3. Nếu không tìm thấy → **BẮT BUỘC 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. KHÔNG ĐƯỢC TIẾP TỤC NẾU CHƯA CÓ functionId.

**Xác định Mode (CREATE / UPDATE) — BẮT BUỘC, chạy ngay sau khi có `functionId`:**

> Đây là cơ chế trả lời Vấn đề A ở `docs/internal/Token Problems.md` (§2.1/§3.1) — trước bản này, mọi lần chạy `create-spec` đều mặc định CREATE (`_v1`), kể cả khi UC Spec cho `functionId` đó đã tồn tại và được PM merge — khiến BA phải điều tra/hỏi lại từ đầu mỗi khi cần sửa 1 UC Spec đã duyệt.

1. Tìm `04.UC-Specs/[functionId]/UC-Spec_v{N_prev}.md` (version cao nhất, không phải bản archive) — gọi version tìm được là `N_prev`.
2. **Không tìm thấy** → Mode = **CREATE**. Version output của toàn bộ Gate 1–4 (`N`, dùng xuyên suốt các bước bên dưới và trong `UC-Spec_v{N}.md`) = `1` (hành vi giữ nguyên như trước — không đổi gì với BA đang tạo UC Spec lần đầu).
3. **Tìm thấy, đã PM merge (`UC-Spec_v{N_prev}.md` tồn tại trong `main` — không phải bản đang ở branch task khác)** → Mode = **UPDATE**. Version output `N = N_prev + 1`. Đọc `UC-Spec_v{N_prev}.md` và `Analysis_v(n).md` (bản mới nhất trong `01.Analysis/[functionId]/`) làm baseline — dùng ở Bước 1/1b/2 bên dưới.
4. **Tìm thấy nhưng chưa PM merge** (task trước của cùng `functionId` đang dở, chưa qua Gate 4 hoặc chưa submit MR) → hỏi BA: "`functionId` này đang có UC Spec v{N_prev} chưa merge (task [taskId cũ nếu biết]) — bạn muốn tiếp tục task đó (resume) hay đây là task/thay đổi mới sau khi task đó merge xong (chờ)?" Không tự đoán.

⚠️ **Chưa "triệt để" 100%** (xem `docs/internal/Token Problems.md` §4): Mode UPDATE đặt cược vào việc input mới mô tả đúng phạm vi thay đổi — Bước 2 bên dưới có 1 bước bắt buộc "quét side-effect" để giảm rủi ro bỏ sót, nhưng không loại bỏ hoàn toàn. Nếu BA nghi ngờ thay đổi lần này lớn tới mức ảnh hưởng gần như toàn bộ UC (đổi luồng chính, đổi actor, đổi mô hình dữ liệu cốt lõi) → cân nhắc chạy Mode CREATE thủ công (bỏ qua Mode UPDATE, coi như viết lại UC Spec từ đầu) thay vì ép vào UPDATE.

**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 BA:
     ```
     ✗ 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/02.BA-Specs/`:
   - **Tìm thấy** → thông báo xác nhận:
     ```
     ✓ Thư mục đầu ra: AK-Docs/02.BA-Specs/
     ✓ functionId: [functionId]
     ✓ Mode: [CREATE | UPDATE] (version mới: v{N})
     → 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 `02.BA-Specs/` ở workspace root):
     ```
     AK-Docs/02.BA-Specs/01.Analysis/
     AK-Docs/02.BA-Specs/02.QnA/
     AK-Docs/02.BA-Specs/03.UI-Prototypes/
     AK-Docs/02.BA-Specs/04.UC-Specs/
     ```
     → Thông báo:
     ```
     ✓ Đã tạo thư mục: AK-Docs/02.BA-Specs/
     ✓ functionId: [functionId]
     ✓ Mode: [CREATE | UPDATE] (version mới: v{N})
     → 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/02.BA-Specs/`, đả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 BA: "Chưa có branch riêng cho task này trong AK-Docs. Tạo branch `feature/[taskId]` từ `main` — đồng ý không?" → BA đồng ý thì chạy `ak docs branch [taskId] --yes`.
   - **Đã có branch cho task này** → hỏi BA 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`).
   - **BA từ chối** → tiếp tục Gate 1 trên nhánh hiện tại của AK-Docs (BA 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 BA gõ xác nhận rõ ràng trong hội thoại.

#### Bước 0.6: Glossary dự án — đọc trước khi soạn câu hỏi đầu tiên

> Quy tắc đầy đủ: `custom/rules/domain-terminology.md`. Chạy **một lần** mỗi lần vào Gate 1, trước Bước 2.

Glossary là **một file dùng chung cho toàn dự án**, không phải bảng riêng của từng functionId:

```
AK-Docs/00.Project-Overview/Glossary.md
```

1. **File đã có** → đọc hết, nạp làm từ điển bắt buộc cho cả phiên. Mọi thuật ngữ nghiệp vụ trong `Analysis`, `QnA-Log`, `UI-Prototype`, `UC-Spec` lấy từ đây; cấm tự dịch (`group` ≠ "nhóm", `buyer` ≠ "cửa hàng", `import` ≠ "nhập").
2. **File chưa có** → **hỏi BA xác nhận, không tự tạo im lặng**:

```
Dự án chưa có AK-Docs/00.Project-Overview/Glossary.md.
Tôi tạo file này và điền các thuật ngữ quét được từ ticket / màn hình / mã nguồn — đồng ý không? (Có / Không)
```

   - BA đồng ý → tạo file, điền bảng `Thuật ngữ | Viết trong tài liệu | Nghĩa | Nguồn` từ 4 nguồn theo thứ tự ưu tiên: (1) tiêu đề/mô tả ticket, kể cả bản gốc tiếng Nhật/Anh; (2) tài liệu `AK-Docs/` đã có (UC Spec, QnA-Log cũ, biên bản); (3) nhãn hiển thị trên màn hình trong mã nguồn frontend (i18n, text nút/tiêu đề); (4) tên khái niệm trong mã nguồn backend — chỉ khi ba nguồn trên không có. Cột `Nguồn` viết bằng ngôn ngữ nghiệp vụ (tên màn hình, số hiệu ticket), **không** `file:line`.
   - BA từ chối → đặt bảng Glossary trong `Analysis_v(n).md` của functionId này, không hỏi lại trong cùng phiên.
3. **Gặp khái niệm nghiệp vụ không có trong Glossary và không tìm được ở 4 nguồn trên** (ở Bước 2, Bước 4, hoặc bất kỳ gate sau) → **hỏi BA ngay, không tự đặt từ và không tự dịch**:

```
Tôi chưa tìm được thuật ngữ dự án đang dùng cho "<mô tả khái niệm bằng một cụm ngắn>"
(thấy ở: <màn hình / ticket / mã nguồn>). Dự án gọi nó là gì?
```

   BA trả lời → dùng đúng từ đó trong tài liệu **và** thêm ngay một dòng vào `Glossary.md` (Nguồn = `BA xác nhận <dd/mm/yyyy>; <màn hình/ticket>`). Không để dồn tới cuối gate.

4. Glossary nằm trong `AK-Docs/` nên mọi thay đổi đi theo branch task đã lập ở Bước 0.5, qua Merge Request như các file khác.

#### 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 đó

**Mode UPDATE:** input ở bước này (ticket/CR mới) thường mô tả **phần thay đổi**, không phải toàn bộ feature — coi đó là "yêu cầu thay đổi" cần đối chiếu với `UC-Spec_v{N}.md`/`Analysis_v(n).md` đã đọc ở Bước 0, không phải điều tra lại từ trắng. Nếu input không đủ rõ phạm vi ảnh hưởng (chỉ nói chung chung, không chỉ rõ field/luồng/BR nào đổi) → hỏi BA 1 câu để khoanh vùng trước khi sang Bước 1b/2.

> ❌ **KHÔNG** dùng `superpowers:brainstorming` ở gate này. Skill đó thiết kế cho thiết kế giải pháp kỹ thuật và có terminal state bắt buộc là invoke `writing-plans` (implementation plan) — sai bối cảnh cho BA workflow, vốn kết thúc Gate 1 bằng `Analysis_v1.md` + `QnA-Log_v1.md`, không phải code plan. Kỹ thuật "hỏi từng câu, đề xuất phương án" cần thiết đã có sẵn trong `skill-ba-qna` ở Bước 2/4 bên dưới.

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

Áp dụng `custom/rules/investigation-cost-control.md` cho bước đọc source code này (GitNexus-first → `Explore` sub-agent delegation → điều tra theo module một lần, không mở lại file cho từng aspect ở Bước 2 → Investigation Notes table). Ở Mode UPDATE (xem Gate 1 Bước 0 ở trên), phạm vi điều tra chỉ giới hạn trong phần bị ảnh hưởng bởi thay đổi — không quét lại toàn bộ module như Mode CREATE.

#### Bước 2: Phân tích yêu cầu, xác định Gaps và hỏi làm rõ ngay (vòng lặp đồng bộ)

- **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
- Liệt kê **toàn bộ** Gap/Assumption tìm được — không chỉ những điểm "cốt yếu"

**Mode UPDATE — chỉ phân tích trên phần delta, cộng 1 bước quét side-effect bắt buộc:**

1. Đọc `Analysis_v(n).md`/`UC-Spec_v{N}.md` hiện tại (đã đọc ở Bước 0) làm baseline — mọi Fact/Decision đã Confirmed ở version trước **giữ nguyên, không hỏi lại** (tương tự cách `create-testcase` cấm hỏi lại điều đã có câu trả lời trong artifact gate trước).
2. Chỉ liệt kê Gap/Assumption cho nội dung **mới hoặc bị ảnh hưởng trực tiếp** bởi thay đổi mô tả ở Bước 1.
3. **Bắt buộc, không được bỏ qua:** quét nhanh xem thay đổi có chạm Business Rule/Flow/UI Component nào khác không nằm trong mô tả ban đầu của BA/khách hàng không — cách làm rẻ nhất: tìm mọi chỗ khác trong `UC-Spec_v{N}.md` nhắc tới cùng field/entity/actor với phần vừa đổi (grep theo tên field/entity, không cần LLM suy luận lại toàn bộ). Tìm thấy chỗ nhắc tới khác → thêm vào phạm vi Gap/Assumption của vòng này, không bỏ qua chỉ vì BA/khách hàng không nhắc tới.
4. ⚠️ Bước quét này **không triệt để 100%** — chỉ bắt được phụ thuộc hiển lộ qua từ khoá/tên field trùng nhau, không bắt được phụ thuộc ngầm/semantic. Đây là đánh đổi có chủ đích giữa tốc độ và độ đầy đủ (xem `docs/internal/Token Problems.md` §4) — nếu nghi ngờ có phụ thuộc ngầm, hỏi BA/Dev liên quan thay vì tự suy diễn "chắc không ảnh hưởng gì".

> ❌ **KHÔNG** tự giới hạn số câu hỏi theo một số cố định (ví dụ luôn dừng ở 5-6 câu) bất kể độ phức tạp của input. Số câu hỏi phải phản ánh đúng số Gap/Assumption thực sự tồn tại: yêu cầu đơn giản (1 field, 1 luồng) có thể chỉ cần 2-3 câu; yêu cầu phức tạp (nhiều actor, nhiều luồng, tích hợp hệ thống khác) có thể cần 15-20+ câu. Nếu trong lúc hỏi/nghe trả lời phát hiện thêm Gap mới, bổ sung ngay câu hỏi mới vào cuối vòng lặp — không đóng vòng lặp sớm chỉ vì đã hỏi "đủ nhiều".

**Phân loại mức ảnh hưởng:** trước khi hỏi, gắn nhãn mỗi Gap là 🔴 Blocking hoặc 🟡 Non-blocking theo [Quy ước Blocking / Non-blocking](#quy-ước-blocking--non-blocking--đánh-dấu-pending) ở đầu file.

**Dựng bản đồ phụ thuộc:** sau khi gắn nhãn và **trước khi hỏi câu đầu tiên**, điền trường `Phụ thuộc` cho mọi câu hỏi và sắp thứ tự hỏi theo [Quy tắc phụ thuộc câu hỏi & chống hỏi thừa](#quy-tắc-phụ-thuộc-câu-hỏi--chống-hỏi-thừa). Câu cha trước, câu con sau; 🔴 Blocking trước 🟡 Non-blocking trong cùng mức.

**Vòng lặp hỏi-đáp:** Với từng Gap/Assumption trong danh sách, hỏi **ONE câu một lúc** theo **dạng gọn** (mục 1b của Quy tắc chất lượng câu hỏi), đợi BA trả lời trước khi hỏi câu tiếp theo. BA gõ `chi tiết` → in khối đầy đủ của câu đó (đúng format ghi file). Trước mỗi câu, chạy kiểm tra 3 điều kiện (a/b/c) ở mục Quy tắc phụ thuộc — trượt điều kiện nào thì bỏ qua câu đó kèm lý do, không hỏi:

- BA trả lời đủ rõ → đánh dấu **Confirmed**, tích hợp ngay vào bản phân tích đang xây dựng, ghi quyết định + hệ quả suy ra vào bảng "Quyết định đã chốt", rà nhanh các câu chưa hỏi còn lại xem có câu nào đã được bao phủ không (bao phủ → đóng `Suy ra từ QA-xx`, không hỏi), rồi chuyển sang câu hỏi tiếp theo
- BA trả lời "chưa biết" / "để hỏi lại [stakeholder]" / "chưa chốt được ngay":
  - 🟡 Non-blocking → đánh dấu **Open** (deferred), ghi chú lý do, chuyển ngay sang câu hỏi tiếp theo — KHÔNG chặn
  - 🔴 Blocking → hiển thị cảnh báo lý do đây là blocking + hệ quả nếu bỏ qua, hỏi BA xác nhận có chắc muốn tiếp tục không; BA xác nhận → đánh dấu **Open** nhưng giữ nhãn 🔴 Blocking, vẫn chuyển sang câu tiếp theo
- Sau khi một câu chuyển sang **Open** (defer): mọi câu phụ thuộc nó chuyển ngay sang trạng thái **`Blocked-by QA-xx`** và **bị loại khỏi vòng hỏi này** — không hỏi, không tách nhỏ để hỏi lách. Chúng dùng chung marker `[PENDING - QA-xx]` của câu cha.
- Sau mỗi 10 câu đã phát ra, dừng ở điểm kiểm tra tải câu hỏi (mục 5 của Quy tắc phụ thuộc) để BA chọn NEXT hoặc DEFER-NB.
- Lặp lại cho tới khi **mọi** Gap/Assumption trong danh sách đã được xử lý — mỗi câu ở đúng một trạng thái tường minh: Confirmed, Open (kèm nhãn Blocking/Non-blocking), hoặc `Blocked-by QA-xx`

Chỉ sau khi vòng lặp này hoàn tất (không còn Gap nào **chưa được hỏi**) mới chuyển sang Bước 3. Số lượng câu hỏi Open còn lại (và nhãn Blocking/Non-blocking của chúng) chính là input cho Gate 2.

#### Bước 3: Soạn thảo Kết quả phân tích sơ bộ
- **READ template:** `.claude/skills/ba-skills/skill-ba-initial-analysis-template-v1.md`
- **READ rule:** `custom/rules/domain-terminology.md` + `AK-Docs/00.Project-Overview/Glossary.md` — dùng đúng từ Glossary và từ đã thống nhất trong vòng Q&A; không tự dịch từ dự án, không tự đặt tên phân hệ / menu / màn hình; tiếng Nhật viết tên gọi kèm chữ gốc trong ngoặc ở lần đầu mỗi mục cấp 2
- **READ rule:** `custom/rules/ui-action-wording.md` — câu mô tả thao tác / kết quả UI dùng động từ và trạng thái chuẩn (`Click button`, `Enter … into field`, `Displayed`, `Disabled`…), thuật ngữ IT giữ tiếng Anh (field, modal, toast, server, cache, redirect…)
- Điền đầy đủ các mục theo template: Actors, Facts, Assumptions, Gap Analysis table — dùng câu trả lời **Confirmed** từ vòng lặp Bước 2 làm nội dung chính, không phải giả định của AI
- Gap Analysis table chỉ còn liệt kê các Gap **Open** (deferred) từ vòng lặp Bước 2, kèm nhãn 🔴 Blocking / 🟡 Non-blocking
- Với mỗi Gap Open, chèn marker `⚠️ [PENDING - QA-0N]` tại đúng vị trí nội dung liên quan (mục 3/4 của template) thay vì bỏ trống hoặc tự suy diễn
- Nếu tài liệu còn ít nhất 1 Gap Open → thêm banner đầu tài liệu: `⚠️ TÀI LIỆU CHƯA ĐẦY ĐỦ — còn [N] câu hỏi Open ([X] Blocking, [Y] Non-blocking), xem QnA-Log_v1.md`
- **Mode UPDATE:** mọi mục **không** nằm trong phạm vi delta (đã xác định ở Bước 2) giữ nguyên nội dung từ `Analysis_v(n).md` cũ — không viết lại. Thêm 1 dòng đầu tài liệu: `Mode: UPDATE — hướng tới UC-Spec v{N+1} (hiện tại: v{N})`. Đặt tên file tiếp nối đúng counter hiện có của `functionId` này (không phải `_v1`) — nếu `Analysis_v(n).md` cao nhất hiện có là ví dụ `Analysis_v3.md` (từ vòng đàm phán của UC Spec v{N} trước đó), file mới của vòng UPDATE này là `Analysis_v4.md`, không phải reset lại `_v1` (tránh ghi đè/nhầm lẫn với bản cũ).
- Lưu: `AK-Docs/02.BA-Specs/01.Analysis/[functionId]/Analysis_v1.md` (Mode CREATE) hoặc `Analysis_v(n+1).md` tiếp nối counter hiện có (Mode UPDATE, xem trên)

#### Bước 4: Soạn thảo danh sách Q&A
- **READ rule:** `custom/rules/ui-action-wording.md` — câu mô tả thao tác / kết quả UI dùng động từ và trạng thái chuẩn (`Click button`, `Enter … into field`, `Displayed`, `Disabled`…), thuật ngữ IT giữ tiếng Anh (field, modal, toast, server, cache, redirect…)

- **READ skill:** `.claude/skills/ba-skills/skill-ba-qna-v1.md`
- **READ template:** `.claude/skills/ba-skills/skill-ba-qna-template-v1.md`
- Ghi lại **toàn bộ** câu hỏi đã hỏi ở vòng lặp Bước 2 dưới dạng log: mỗi câu kèm câu trả lời, nhãn Blocking/Non-blocking, và trạng thái cuối cùng
  - **Confirmed** — BA đã trả lời trong Bước 2, ghi kèm câu trả lời
  - **Open** — BA đã xác nhận chưa trả lời được ngay (cần hỏi lại stakeholder khác), ghi kèm lý do deferred + nhãn 🔴 Blocking hoặc 🟡 Non-blocking
  - **`Blocked-by QA-xx`** — chưa được hỏi vì câu cha QA-xx còn Open; ghi rõ ID câu cha, giữ nhãn gốc, không ghi câu trả lời
- Không tạo câu hỏi mới ở bước này — đây là bản ghi (log) của vòng lặp đã chạy ở Bước 2, không phải một vòng hỏi mới
- Câu hỏi ở Bước 2 được hỏi theo dạng gọn → khi ghi file, **mở rộng mỗi câu về khối đầy đủ** theo quy tắc trình bày ở mục 1 của Quy tắc chất lượng câu hỏi: tên mục in đậm không đánh số, nội dung thụt 4 dấu cách, hai dòng thông tin viết thành câu, không ghi công số, `Người trả lời` / `Ngày trả lời` / `Nguồn` ngang cấp với `Câu trả lời:`. Cùng câu hỏi, cùng options, cùng đề xuất như lúc hỏi BA. Không ghi dạng gọn vào file.
- **Phân nhóm bảng câu hỏi theo role** — bắt buộc, không xuất danh sách phẳng:
  - Mỗi role actor của hệ thống một bảng con: `### Role: Admin`, `### Role: Buyer`, `### Role: Guest`... Tên role lấy đúng tên hệ thống đang dùng (theo Glossary ở Bước 0.6), không tự dịch.
  - Nguồn xác định role: danh sách Actors trong `Analysis_v(n).md`, phân quyền trong mã nguồn, màn hình quản trị vs màn hình người dùng cuối.
  - Câu áp dụng cho mọi role hoặc không gắn role nào (cấu hình hệ thống, batch, tích hợp ngoài) → nhóm cuối cùng `### Chung / Cross-role`. Một câu chỉ nằm ở **một** nhóm — không nhân bản.
  - Câu chạm 2 role → xếp vào role ra quyết định/chịu ảnh hưởng chính, nhắc role còn lại trong phần Bối cảnh.
  - Hệ thống chỉ có một role → bỏ cấp nhóm role, chia theo màn hình/module. Không dựng nhóm giả cho đủ cấu trúc.
  - Nhóm không có câu hỏi nào thì **không in heading** — ghi một dòng ở phần Tóm tắt đầu tài liệu kèm lý do một mệnh đề.
  - **Mã** (`QA-01`, `QA-02`...) đánh số **liên tục toàn file**, không reset theo nhóm, và **không đổi giữa các version** — `Phụ thuộc` và marker `[PENDING - QA-xx]` trỏ theo Mã. Số thứ tự `Q1`, `Q2`… chỉ chạy theo thứ tự đọc và được phép đổi khi câu chuyển nhóm.
  - Thứ tự nhóm: role nhiều câu 🔴 Blocking nhất lên trước; trong mỗi nhóm giữ thứ tự topo của bản đồ phụ thuộc.
- Kiểm tra trước khi lưu: danh sách câu hỏi ở dạng khối `Q{n}`, không phải bảng; không còn mục "Vì sao cần hỏi" ở đâu; mục `Vấn đề` và `Ví dụ minh họa` rỗng đã bỏ hẳn; trình bày đúng mục 1 (không đánh số mục, không bullet `・`, nội dung thụt 4 dấu cách, không ghi công số); mọi option/ví dụ đều chỉ ra được nguồn thật (xem mục 3bis của Quy tắc chất lượng câu hỏi); không có thuật ngữ nghiệp vụ nào bị tự dịch
- Lưu: `AK-Docs/02.BA-Specs/02.QnA/[functionId]/QnA-Log_v1.md`

#### Bước 5: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — dừng gate chờ BA đọc output (không tạo checklist để tick)
- **Kiểm tra Q&A bắt buộc:** Đọc `QnA-Log_v1.md` — đếm số câu **Open**, tách riêng theo nhãn 🔴 Blocking và 🟡 Non-blocking. Câu ở trạng thái `Blocked-by QA-xx` **không** đếm riêng và **không** tự nó chặn gate — nó đi theo trạng thái câu cha QA-xx (liệt kê dưới câu cha để BA thấy hệ quả dây chuyền)
- Hiển thị gate pause message — chờ phản hồi từ BA

**Nếu còn câu Open 🔴 Blocking → từ chối APPROVED ngay, hiển thị:**

⛔ GATE 1 BLOCKED — Còn [N] câu hỏi Blocking chưa được trả lời trong QnA-Log_v1.md.

| ID | Câu hỏi còn Open (Blocking) |
|----|-----------------|
| [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 `QnA-Log_v1_response.md` vào thư mục `02.QnA/[functionId]/` rồi gõ NEXT

❌ APPROVED không được chấp nhận cho đến khi mọi câu hỏi **Blocking** đã Confirmed.

**Nếu chỉ còn câu Open 🟡 Non-blocking (không còn Blocking) → cho phép APPROVED, nhưng hiển thị cảnh báo ngay trong gate pause message trước khi BA gõ APPROVED:**

⚠️ Còn [N] câu hỏi Non-blocking chưa Confirmed — có thể APPROVED để tiếp tục, tài liệu sẽ giữ marker `[PENDING - QA-0N]` tại các phần liên quan cho tới khi được bổ sung ở Gate 2.

| ID | Câu hỏi còn Open (Non-blocking) |
|----|-----------------|
| [Q_ID] | [nội dung câu hỏi] |

**Khi APPROVED (không còn câu Blocking Open — câu Non-blocking Open được phép tồn tại):**
→ **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 `BA 🔵` (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 — BA không phải tick, không đưa danh sách này cho BA):
- [ ] `functionId` đã được xác định và thư mục đầu ra đã sẵn sàng
- [ ] File `Analysis_v1.md` tạo đúng vị trí, cấu trúc đúng template, có bảng Gap Analysis, số Gap phản ánh đúng độ phức tạp thực tế (không bị gò về một số cố định)
- [ ] File `QnA-Log_v1.md` có ít nhất 1 câu hỏi cho mỗi Gap, mỗi câu có nhãn Blocking/Non-blocking rõ ràng
- [ ] `QnA-Log_v1.md` đã chia nhóm theo role (hoặc theo màn hình/module nếu hệ thống chỉ có một role), ID liên tục toàn file
- [ ] Không còn mục "Vì sao cần hỏi" ở bất kỳ đâu; phần đó đã gộp vào mục `Bối cảnh`
- [ ] Danh sách câu hỏi ở dạng khối `Q{n}` có tiêu đề `[Màn hình/Chức năng] Về {chủ đề}`, không phải bảng
- [ ] Tiêu đề viết thành cụm danh từ, không phải câu hỏi
- [ ] Mục `Vấn đề` và `Ví dụ minh họa` không có nội dung thì đã bỏ hẳn, không để tên mục rỗng
- [ ] `QnA-Log` trình bày đúng mục 1 của Quy tắc chất lượng câu hỏi: tên mục in đậm có `:`, không đánh số; nội dung thụt 4 dấu cách; không bullet `・`; hai dòng thông tin viết thành câu; không ghi công số; `Người trả lời` / `Ngày trả lời` / `Nguồn` ngang cấp với `Câu trả lời:`
- [ ] Mọi option và ví dụ minh hoạ đều truy được về yêu cầu / `AK-Docs/` / mã nguồn; option mô tả chức năng chưa có đã ghi `(chưa có, cần làm mới)`
- [ ] `AK-Docs/00.Project-Overview/Glossary.md` đã được đọc (hoặc đã hỏi BA xác nhận tạo mới), và mọi thuật ngữ BA cung cấp trong gate này đã ghi ngược vào file đó
- [ ] Thuật ngữ khớp Glossary (`custom/rules/domain-terminology.md`): không từ tự dịch / tự đặt (grep `cửa hàng|khách hàng|người mua|nhà cung cấp|trang quản trị|cổng|nhóm|sản phẩm|giỏ hàng` — mỗi hit phải có trong cột `Viết trong tài liệu`), không chữ tiếng Nhật đứng một mình trong câu
- [ ] Độ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` trên Analysis và QnA-Log — 0 hit ngoài chữ gốc trích nguyên văn
- [ ] Không còn câu hỏi 🔴 Blocking ở 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)
- `AK-Docs/02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n).md` — phiên bản hiện tại
- `AK-Docs/02.BA-Specs/02.QnA/[functionId]/QnA-Log_v(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: `AK-Docs/02.BA-Specs/02.QnA/[functionId]/QnA-Log_v(m)_response.md`

**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: Tiếp nhận và đánh giá câu trả lời
- Đối chiếu từng câu trả lời với câu hỏi trong `QnA-Log_v(m).md`
- Phân loại:
  - Đủ thông tin → cập nhật trạng thái: **Confirmed**, xóa marker `[PENDING - QA-ID]` liên quan
  - Chưa rõ hoặc phát sinh nghiệp vụ mới → giữ trạng thái **Open**, bổ sung ghi chú, giữ nguyên nhãn 🔴 Blocking / 🟡 Non-blocking đã gắn từ Gate 1 (hoặc gắn mới nếu là Gap phát sinh)
- **Cập nhật bảng "Quyết định đã chốt + hệ quả suy ra":** mỗi câu vừa Confirmed → ghi quyết định kèm các hệ quả suy ra trực tiếp, rồi rà lại danh sách câu chưa hỏi: câu nào đã được bao phủ → đóng `Suy ra từ QA-xx` (Confirmed), không đưa vào vòng sau.
- **Cập nhật khoá phụ thuộc:**
  - Câu cha QA-xx chuyển sang **Confirmed** → mọi câu `Blocked-by QA-xx` được **mở khoá**: soát lại xem câu trả lời của QA-xx đã bao phủ luôn nội dung câu con chưa (điều kiện (a) của Quy tắc phụ thuộc). Đã bao phủ → đóng luôn thành **Confirmed**, không hỏi lại. Chưa bao phủ → chuyển sang **Open** và đưa vào vòng Q&A tiếp theo.
  - Câu cha vẫn **Open** → câu con giữ nguyên `Blocked-by QA-xx`, **không** đưa vào vòng Q&A tiếp theo dưới bất kỳ dạng nào (kể cả diễn đạt lại hoặc tách nhỏ).
  - Gap mới phát sinh từ câu trả lời vừa nhận → gắn nhãn + điền trường `Phụ thuộc` ngay, rồi áp dụng đúng quy tắc trên trước khi quyết định có hỏi ở vòng sau hay không.

#### Bước 1b: Cập nhật Glossary từ câu trả lời vừa nhận
- Câu trả lời của BA/khách hàng thường mang theo tên nghiệp vụ thật ("bên mình gọi là `buyer`, không phải cửa hàng"). Mỗi từ như vậy chưa có trong `AK-Docs/00.Project-Overview/Glossary.md` → thêm ngay một dòng (Nguồn = `BA xác nhận <dd/mm/yyyy>; QA-xx`), và dùng đúng từ đó từ vòng này trở đi.
- Từ đã có trong Glossary nhưng BA đính chính nghĩa → sửa dòng cũ, **không** tạo dòng thứ hai cho cùng khái niệm.
- Chưa có file Glossary và BA đã từ chối tạo ở Gate 1 → ghi vào bảng Glossary trong `Analysis_v(n+1).md`, không hỏi lại.

#### 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 `Analysis_v(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: `AK-Docs/02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md`
- Viết `Analysis_v(n+1).md` theo cùng quy tắc với Gate 1 Bước 3:
  - **READ rule:** `custom/rules/domain-terminology.md` + `AK-Docs/00.Project-Overview/Glossary.md` — dùng đúng từ Glossary và từ đã thống nhất trong vòng Q&A; không tự dịch từ dự án, không tự đặt tên phân hệ / menu / màn hình; tiếng Nhật viết tên gọi kèm chữ gốc trong ngoặc ở lần đầu mỗi mục cấp 2
  - **READ rule:** `custom/rules/ui-action-wording.md` — câu mô tả thao tác / kết quả UI dùng động từ và trạng thái chuẩn (`Click button`, `Enter … into field`, `Displayed`, `Disabled`…), thuật ngữ IT giữ tiếng Anh (field, modal, toast, server, cache, redirect…)
  - `Analysis_v(n)` cũ còn từ tự đặt, chữ tiếng Nhật đứng một mình hoặc động từ thao tác chưa chuẩn → sửa luôn trong `Analysis_v(n+1)`, ghi 1 dòng vào lịch sử thay đổi của tài liệu

#### Bước 3: Rẽ nhánh theo trạng thái Q&A

**Kịch bản A — Còn câu hỏi Open 🔴 Blocking:**
1. Kiểm tra `Analysis_v(n+1).md` có phát sinh Gap mới không
2. Tạo: `AK-Docs/02.BA-Specs/02.QnA/[functionId]/QnA-Log_v(m+1).md` — chỉ giữ câu Open, câu vừa được mở khoá, và câu mới phát sinh. Câu còn `Blocked-by QA-xx` vẫn ghi trong log để truy vết nhưng **không** nằm trong danh sách hỏi vòng này. Giữ nguyên cách phân nhóm theo role và ID liên tục toàn file như Gate 1 Bước 4 — nhóm nào không còn câu nào thì bỏ hẳn tiêu đề nhóm, không để bảng rỗng; câu mới phát sinh đánh số tiếp theo ID lớn nhất đã dùng, không chèn vào giữa. Trình bày từng câu theo format ghi file ở mục 1 của Quy tắc chất lượng câu hỏi; câu đổi trạng thái thì sửa luôn dòng thông tin 1 (`Đã chốt (Confirmed)`…) và điền ba dòng `Người trả lời` / `Ngày trả lời` / `Nguồn`
3. **INVOKE** `gate-review` skill (generate mode) — dừng gate chờ BA đọc output (không tạo checklist để tick)
4. Hiển thị:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏸️  GATE 2 — VÒNG Q&A [m+1]

Câu hỏi còn Open (🔴 Blocking): [N]
Câu hỏi còn Open (🟡 Non-blocking): [M]
File Q&A mới:     [AK-Docs/02.BA-Specs/02.QnA/[functionId]/QnA-Log_v(m+1).md](AK-Docs/02.BA-Specs/02.QnA/[functionId]/QnA-Log_v(m+1).md)
File phân tích:   [AK-Docs/02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](AK-Docs/02.BA-Specs/01.Analysis/[functionId]/Analysis_v(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 🔴 Blocking) → từ chối ngay:**

⛔ GATE 2 BLOCKED — Còn [N] câu hỏi Blocking chưa Confirmed.

| ID | Câu hỏi còn Open (Blocking) |
|----|-----------------|
| [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 mọi câu hỏi **Blocking** đã Confirmed.

**Kịch bản B — Chỉ còn câu hỏi Open 🟡 Non-blocking (không còn Blocking):**

1. Tạo `QnA-Log_v(m+1).md` như Kịch bản A (giữ câu Non-blocking Open + câu mới phát sinh)
2. Hiển thị cho BA 2 lựa chọn, không tự chọn thay:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏸️  GATE 2 — CÒN [M] CÂU HỎI NON-BLOCKING CHƯA CONFIRMED

Các câu hỏi này không chặn thiết kế Gate 3/4, nhưng output sẽ giữ marker `[PENDING - QA-ID]` tại các phần liên quan cho tới khi được bổ sung.

→ Cách 1: cung cấp câu trả lời (Option A/B/C) rồi gõ NEXT để xử lý tiếp
→ Cách 2: gõ APPROVED để chấp nhận tiếp tục dù output chưa đầy đủ ở các mục này
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. BA gõ NEXT với phản hồi mới → lặp lại Bước 1
2. BA gõ APPROVED → coi là đã xác nhận chấp nhận output chưa đầy đủ, chuyển sang xử lý APPROVED bên dưới

**Kịch bản C — 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) — dừng gate chờ BA đọc output (không tạo checklist để tick)
3. Hiển thị gate pause message — đợi **APPROVED**

**Khi APPROVED (Kịch bản B hoặc C — không còn câu Blocking Open):**
→ **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 — BA không phải tick, không đưa danh sách này cho BA):
- [ ] Mọi câu trả lời đều được phân tích và phân loại trạng thái
- [ ] Không có câu hỏi nào được phát ra khi câu cha của nó còn Open (mọi câu con đúng trạng thái `Blocked-by QA-xx`)
- [ ] Mọi câu `Blocked-by` có câu cha vừa Confirmed đã được soát lại: đóng thành Confirmed nếu đã được bao phủ, hoặc mở sang Open
- [ ] 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 🔴 Blocking ở trạng thái Open trước khi tiến Gate 3
- [ ] Nếu còn câu 🟡 Non-blocking Open, BA đã xác nhận rõ ràng (gõ APPROVED sau khi thấy cảnh báo) và các mục liên quan trong Analysis đã có marker `[PENDING - QA-ID]`
- [ ] `QnA-Log_v(m+1).md` giữ đúng cấu trúc nhóm theo role, ID liên tục toàn file, không có mục "Vì sao cần hỏi", trình bày đúng format ghi file ở mục 1 của Quy tắc chất lượng câu hỏi
- [ ] Thuật ngữ nghiệp vụ mới xuất hiện trong câu trả lời vòng này đã được ghi vào `Glossary.md`
- [ ] Thuật ngữ khớp Glossary (`custom/rules/domain-terminology.md`): không từ tự dịch / tự đặt (grep `cửa hàng|khách hàng|người mua|nhà cung cấp|trang quản trị|cổng|nhóm|sản phẩm|giỏ hàng` — mỗi hit phải có trong cột `Viết trong tài liệu`), không chữ tiếng Nhật đứng một mình trong câu
- [ ] Độ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` trên `Analysis_v(n+1)` và `QnA-Log_v(m+1)` — 0 hit ngoài chữ gốc trích nguyên văn

> **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:** Không còn câu hỏi 🔴 Blocking Open và Gate 2 đã **APPROVED** (câu 🟡 Non-blocking Open, nếu còn, mang marker `[PENDING - QA-ID]` sang cùng Analysis).

**Đầu vào (Inputs):**
- `AK-Docs/02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n).md` — phiên bản cuối

**Đầu ra (Outputs):**
- `AK-Docs/02.BA-Specs/03.UI-Prototypes/[functionId]/UI-Prototype_v1.html`

**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: 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
- Nếu Analysis còn marker `[PENDING - QA-ID]` liên quan đến thành phần giao diện nào → giữ nguyên placeholder trực quan cho thành phần đó (không tự bịa nội dung/behavior để lấp đầy) và ghi chú `<!-- PENDING - QA-ID -->` cạnh phần tử HTML tương ứng

#### 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
- Ghi chú / chú thích trong prototype dùng đúng thuật ngữ `QnA-Log` / `Analysis` và Glossary (`custom/rules/domain-terminology.md`), động từ thao tác và thuật ngữ IT theo `custom/rules/ui-action-wording.md`; nhãn giao diện chép nguyên văn ngôn ngữ của hệ thống
- 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
- `AK-Docs/02.BA-Specs/03.UI-Prototypes/[functionId]/UI-Prototype_v1.html`

#### Bước 5: Gate Review & Pause
- **INVOKE** `gate-review` skill (generate mode) — dừng gate chờ BA đọ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 — BA không phải tick, không đưa danh sách này cho BA):
- [ ] File `UI-Prototype_v1.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):**
- `AK-Docs/02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n).md` — phiên bản cuối
- `AK-Docs/02.BA-Specs/03.UI-Prototypes/[functionId]/UI-Prototype_v1.html`

**Đầu ra (Outputs):**
- `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (`N` = 1 nếu Mode CREATE; `N` = version xác định ở Gate 1 Bước 0 nếu Mode UPDATE)

**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: Khởi tạo Spec từ Template
- **READ template:** `.claude/skills/ba-skills/skill-ba-uc-template-v1.md`
- **READ skill:** `.claude/skills/ba-skills/skill-ba-write-uc-spec-v1.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", câu chủ động) + mỗi mục tự chứa đủ nội dung (mã `BR-NNN` dùng để liên kết vẫn phải kèm mô tả nội dung tại chỗ, không để mã trần)
- **READ rule:** `custom/rules/domain-terminology.md` + `AK-Docs/00.Project-Overview/Glossary.md` — trước khi viết, lập danh sách danh từ nghiệp vụ (actor, phân hệ, menu, màn hình, trạng thái, nút) mà `QnA-Log` / `Analysis` đã dùng; UC Spec dùng đúng danh sách đó. Không tự dịch từ dự án, không tự đặt tên phân hệ / menu ("cửa hàng", "cổng"), tiếng Nhật viết tên gọi theo Glossary kèm chữ gốc. Gặp từ chưa có → hỏi BA, ghi vào Glossary
- **READ rule:** `custom/rules/ui-action-wording.md` — câu mô tả thao tác / kết quả UI trong Flow, Business Rule, Mermaid dùng động từ và trạng thái chuẩn (`Click button`, `Enter ... into field`, `Displayed`, `Disabled`…), thuật ngữ IT giữ tiếng Anh; cột "Loại Component" dùng tên Element của bảng
- Tạo: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md`
- Điền General Information: Use Case ID, Title, Version, Actors, Preconditions, Postconditions
- **Header bắt buộc** (mọi Mode — template `skill-ba-uc-template-v1.md` đã có sẵn khối này ở đầu tài liệu): `UC-Spec-Version: v{N}` + `Date` + `Status`.
- Nếu Analysis/Prototype đầu vào còn marker `[PENDING - QA-ID]` (câu Non-blocking chưa Confirmed) → giữ nguyên marker tại đúng vị trí liên quan (Business Rule, UI Component, Flow step) trong UC Spec, không tự bịa nội dung để lấp đầy; thêm banner đầu tài liệu: `⚠️ UC SPEC CHƯA ĐẦY ĐỦ — còn [N] mục PENDING, xem QnA-Log_v(m).md`
- **Mode UPDATE:** khởi tạo `UC-Spec_v{N}.md` bằng cách copy `UC-Spec_v{N-1}.md` làm nền, rồi chỉ sửa đúng phần đã đổi (theo delta đã xác định ở Gate 1 Bước 2) — không viết lại từ template trắng. Mỗi thay đổi phải thêm 1 dòng vào section **"Change Log"** ở cuối tài liệu (thêm section này nếu UC Spec chưa có — xem `skill-ba-uc-template-v1.md`): `| v{N} | [ngày] | [Flow/BR nào đổi] | [tóm tắt thay đổi] | [ticket/CR nguồn] |`. Không được âm thầm bỏ 1 mục mà không ghi lý do vào Change Log.

#### 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 (ảnh chụp + link, không chép mã HTML)
- ❌ **KHÔNG** chép mã HTML/CSS của prototype vào UC Spec. Khối code dài hiển thị dạng code trong mọi Markdown preview, không hiện giao diện.
- **Chụp prototype ra PNG** (ảnh nằm cạnh file HTML, cùng tên):
  ```bash
  ak proto shot AK-Docs/02.BA-Specs/03.UI-Prototypes/[functionId]/UI-Prototype_v1.html
  ```
  Đọc exit code:
  - `0` → đã tạo `UI-Prototype_v1.png`, sang bước chèn ảnh.
  - `2` (chưa có Playwright) hoặc `3` (chưa có Chromium) → **hỏi BA**, không tự cài:
    `Máy chưa có Playwright/Chromium để chụp prototype. Tôi cài bằng "ak proto install" (khoảng 150 MB, vào ~/.aiflow/tools/playwright, không đổi package.json của dự án) — đồng ý không? (Có / Không)`
    - BA **Có** → chạy `ak proto install`, rồi chạy lại `ak proto shot`. Vẫn lỗi → làm như BA trả lời Không, và báo BA dòng lỗi.
    - BA **Không** → không chụp. Chỉ chèn link tới file HTML, kèm ghi chú để BA tự chụp (mẫu bên dưới).
  - `1` → báo BA dòng lỗi, làm như BA trả lời Không.
- **Chèn vào section "Mô tả màn hình (Screen Description)"** theo mẫu dưới. Đường dẫn trong ảnh và link là **đường dẫn tương đối tính từ file UC Spec** (`AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/`), nên luôn bắt đầu bằng `../../03.UI-Prototypes/`. Viết link dạng Markdown `[text](path)` để click được trong preview. **Không** ghi đường dẫn trong code span (`` `AK-Docs/...html` ``), vì code span không click được.
  - Có ảnh:
    ```markdown
    ![Prototype [functionId] v1](../../03.UI-Prototypes/[functionId]/UI-Prototype_v1.png)

    Mở prototype gốc (HTML, có thể tương tác): [UI-Prototype_v1.html](../../03.UI-Prototypes/[functionId]/UI-Prototype_v1.html)
    ```
  - Không có ảnh:
    ```markdown
    Mở prototype gốc (HTML, có thể tương tác): [UI-Prototype_v1.html](../../03.UI-Prototypes/[functionId]/UI-Prototype_v1.html)

    > 📷 **Chưa có ảnh chụp màn hình.** BA mở file HTML trên trình duyệt, chụp toàn trang, lưu thành `UI-Prototype_v1.png` cùng thư mục với file HTML, rồi thêm dòng này vào ngay trên link:
    > `![Prototype [functionId] v1](../../03.UI-Prototypes/[functionId]/UI-Prototype_v1.png)`
    ```
- Tên file theo đúng version prototype đang dùng (`UI-Prototype_v{k}.html` → `UI-Prototype_v{k}.png`).
- Prototype bị sửa sau bước này (ví dụ khi BA gõ `REVISION`) → chạy lại `ak proto shot` để ảnh khớp HTML.

#### 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) — dừng gate chờ BA đọ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]` → cập nhật dòng `[functionId]` trong `AK-Docs/00.Project-Overview/Function-List.md`: `BA ✅`, cột `Link Spec` trỏ tới `UC-Spec_v{N}.md` vừa duyệt (theo `custom/rules/function-list-status.md`) → 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]` → **trước khi sửa**, tạo ngay 1 memory draft ghi lại chính xác điều BA vừa chỉnh (`ak memory draft --category 01.Lessons/ba --function-id <[functionId] | global> --slug <slug> --content "<điều BA sửa + vì sao>" --workflows create-spec --source "[functionId] / Gate 4 BA feedback"` — scope và `--supersedes` theo quy tắc ở Bước 7.5) — đây là tín hiệu giá trị nhất, đừng chờ Bước 7.5 mới bắt lại theo trí nhớ → cập nhật section liên quan → re-generate review file → hiển thị lại gate pause

**Definition of Done** (AI tự kiểm trước khi dừng gate — BA không phải tick, không đưa danh sách này cho BA):
- [ ] File `UC-Spec_v{N}.md` đúng vị trí và cấu trúc template, có `UC-Spec-Version` header đúng `N`
- [ ] Section "Mô tả màn hình" có link Markdown click được tới file HTML prototype (đường dẫn tương đối `../../03.UI-Prototypes/...`), kèm ảnh PNG đã chụp hoặc ghi chú để BA tự chụp; không chứa mã HTML/CSS của prototype
- [ ] 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
- [ ] Không còn giả định ngầm chưa Confirm bị viết như thể đã chốt; mọi nội dung Non-blocking Open còn lại đã có marker `[PENDING - QA-ID]` rõ ràng tại đúng vị trí (không phải ghi chú mơ hồ chung)
- [ ] Hành văn tự nhiên — chạy `grep -nE "Cố |Cố gắng|Thử (mở|nhập|bấm|click)|Tiến hành|thực hiện việc"` trên UC Spec, 0 hit (`custom/rules/document-wording.md` mục 1)
- [ ] Thuật ngữ khớp `QnA-Log` / `Analysis` và Glossary (`custom/rules/domain-terminology.md`): grep `cửa hàng|khách hàng|người mua|nhà cung cấp|trang quản trị|cổng|nhóm|sản phẩm|giỏ hàng` trên UC Spec — mỗi hit phải có trong cột `Viết trong tài liệu` của Glossary; không còn chữ tiếng Nhật đứng một mình trong câu
- [ ] Độ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` trên UC Spec — 0 hit ngoài chữ gốc trích nguyên văn
- [ ] Mỗi Flow step / Business Rule đọc độc lập là hiểu — không có tham chiếu trần kiểu "như mục trên", "theo BR2.10" không kèm mô tả nội dung (`custom/rules/document-wording.md` mục 2)

> **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 feedback của BA trước:** nếu có vòng `REVISION` nào đã xảy ra, đảm bảo điều BA sửa đã có draft (thường đã tạo ngay lúc REVISION ở trên — kiểm tra lại, đừng bỏ sót). Sau đó mới thêm những gì mới khác: business rule mới confirm, thuật ngữ cần làm rõ, quyết định đặc tả và lý do. 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 00.Shared/domain --function-id <[functionId] | global> \
  --slug <slug-ngắn> --content "<≤150 từ, 1 fact>" \
  --tags <tag1,tag2> --workflows create-spec --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 BA đổ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 BA đổ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 BA 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 BA (bắt buộc khi có draft):** sau khi tạo draft (gồm cả draft tạo lúc `REVISION`), 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`.
```

BA 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`). BA muốn thu hẹp một draft global → `ak memory rescope <path draft> --function-id [functionId]`. Chờ BA trả lời rồi mới sang Bước 8.

Category khác hữu ích ở đây: `00.Shared/glossary` (thuật ngữ JP↔VN↔EN mới xác nhận — flat, không cần `--function-id`), `01.Lessons/ba` (bài học khi làm spec), `00.Shared/decisions` (quyết định đặc tả). 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 BA để 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 (UC Spec hoàn thành):

1. Soạn title + description cho Merge Request (tóm tắt UC Spec vừa hoàn thành, link ticket gốc), hiển thị cho BA xem trước.
2. Hỏi BA: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?"
   - BA đồng ý → chạy `ak docs submit --title "..." --description "..." --yes`
   - BA từ chối → dừng, để BA tự commit/tạo MR khi sẵn sàng
3. Thông báo BA: 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 BA tự merge.

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

---

### Bản đồ Skills theo Gate

| Gate | Skills đọc | Output |
|---|---|---|
| Gate 1 | `skill-ba-initial-analysis`, `skill-ba-initial-analysis-template`, `skill-ba-qna`, `skill-ba-qna-template` | `Analysis_v1.md`, `QnA-Log_v1.md` |
| Gate 2 | `skill-ba-qna`, `skill-ba-initial-analysis` | `Analysis_v(n+1).md`, `QnA-Log_v(m+1).md` (nếu còn Open) |
| Gate 3 | `skill-ba-ui-prototype` | `UI-Prototype_v1.html` |
| Gate 4 | `skill-ba-write-uc-spec`, `skill-ba-uc-template`, `skill-ba-mermaid-flowchart`, `skill-ba-build-business-rules` | `UC-Spec_v{N}.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** dùng `superpowers:brainstorming` ở Gate 1 — terminal state của skill đó invoke `writing-plans`, bypass cấu trúc BA workflow
- ✅ **BẮT BUỘC** ở Gate 1 Bước 2: hỏi hết **toàn bộ** Gap/Assumption xác định được, từng câu một, ngay trong hội thoại — không giới hạn ở "điểm mơ hồ cốt yếu" và **không giới hạn theo một số câu hỏi cố định** bất kể độ phức tạp input. Chỉ được ghi Open (deferred sang QnA-Log) khi BA xác nhận rõ ràng là chưa trả lời được ngay
- ✅ **BẮT BUỘC** gắn nhãn 🔴 Blocking / 🟡 Non-blocking cho mỗi Gap/câu hỏi ngay khi phát hiện (xem [Quy ước Blocking / Non-blocking](#quy-ước-blocking--non-blocking--đánh-dấu-pending))
- ✅ **BẮT BUỘC** điền trường `Phụ thuộc` cho mọi câu hỏi trước khi hỏi câu đầu tiên (xem [Quy tắc phụ thuộc câu hỏi & chống hỏi thừa](#quy-tắc-phụ-thuộc-câu-hỏi--chống-hỏi-thừa))
- ❌ **KHÔNG** hỏi một câu khi câu cha của nó còn **Open** — đánh `Blocked-by QA-xx` và chờ câu cha Confirmed. Cấm tách nhỏ hoặc diễn đạt lại để hỏi lách qua khoá này
- ❌ **KHÔNG** hỏi câu mà đáp án chỉ đổi câu chữ hiển thị hoặc giá trị mặc định chỉnh được sau khi code — ghi thành Assumption kèm marker `[PENDING]`
- ✅ **BẮT BUỘC** mỗi câu hỏi có đủ 3 phần Bối cảnh / Câu hỏi (một ý) / Options kèm hệ quả, giải nghĩa mọi từ viết tắt ngay lần đầu xuất hiện, và có khối "Ví dụ minh hoạ" nếu câu hỏi phức tạp (xem [Quy tắc chất lượng câu hỏi](#quy-tắc-chất-lượng-câu-hỏi--dễ-hiểu-cho-người-không-chuyên-kỹ-thuật))
- ❌ **KHÔNG** viết mục "Vì sao cần hỏi" thành mục riêng ở bất kỳ đâu — gộp vào mục `Bối cảnh`
- ❌ **KHÔNG** trình bày danh sách câu hỏi dưới dạng bảng — mỗi câu hỏi là một khối `Q{n}` theo cấu trúc khối đầy đủ của `skill-ba-qna-template-v1.md` — hệ quả của mỗi lựa chọn đã nằm trong Options
- ✅ **BẮT BUỘC** hỏi trong hội thoại theo **dạng gọn** (mục 1b của Quy tắc chất lượng câu hỏi), ghi `QnA-Log` theo **dạng đầy đủ** (mục 1). ❌ **KHÔNG** in khối đầy đủ vào chat trừ khi BA gõ `chi tiết`; ❌ **KHÔNG** ghi dạng gọn vào file
- ❌ **KHÔNG** đưa vào option hay ví dụ minh hoạ một màn hình, trường, vai trò, trạng thái hay hành vi **không có** trong yêu cầu / `AK-Docs/` / mã nguồn. Hướng xử lý chưa tồn tại → gộp vào `Khác — mô tả ngắn`, hoặc ghi rõ `(chưa có, cần làm mới)` trong option (xem mục 3bis của Quy tắc chất lượng câu hỏi)
- ✅ **BẮT BUỘC** chạy Bước 0.6 ở Gate 1 — đọc `AK-Docs/00.Project-Overview/Glossary.md` trước khi soạn câu hỏi đầu tiên; chưa có file thì hỏi BA xác nhận tạo mới, không tự tạo
- ❌ **KHÔNG** tự dịch thuật ngữ nghiệp vụ của dự án (`group` → "nhóm", `buyer` → "cửa hàng", `import` → "nhập") và không tự đặt từ mới — không tìm thấy từ dự án đang dùng thì **hỏi BA**, rồi ghi câu trả lời vào `Glossary.md` ngay trong lượt đó (xem `custom/rules/domain-terminology.md`)
- ❌ **KHÔNG** để thuật ngữ, tên màn hình, nhãn tiếng Nhật đứng một mình trong câu tiếng Việt/tiếng Anh — viết tên gọi theo cột `Viết trong tài liệu` của Glossary, kèm chữ gốc trong ngoặc ở lần đầu của mỗi khối câu hỏi (xem `custom/rules/domain-terminology.md`, mục "Thuật ngữ tiếng Nhật")
- ✅ **BẮT BUỘC** chia bảng Q&A theo nhóm role (`### Role: Admin`, `### Role: Buyer`, ..., `### Chung / Cross-role`) với ID đánh số liên tục toàn file; hệ thống chỉ có một role → chia theo màn hình/module
- ❌ **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ừ khác/từ đồng nghĩa — ghi `Suy ra từ QA-xx` với trạng thái Confirmed; nghi ngờ thì hỏi **một** câu xác nhận yes/no, không mở câu hỏi mới
- ❌ **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
- ❌ **KHÔNG** tiến Gate 3 khi vẫn còn câu hỏi 🔴 Blocking ở trạng thá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 🔴 **Blocking** 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
- ✅ **ĐƯỢC PHÉP chấp nhận APPROVED** ở Gate 1/2/4 khi chỉ còn câu hỏi 🟡 **Non-blocking** Open, với điều kiện: đã hiển thị cảnh báo rõ ràng cho BA trước khi nhận APPROVED, và mọi nội dung phụ thuộc câu hỏi đó được đánh dấu `[PENDING - QA-ID]` tại đúng vị trí trong output — không được tự suy diễn nội dung để lấp đầy
- ✅ **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** đọ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ể
- ✅ **BẮT BUỘC** chạy bước "Xác định Mode (CREATE / UPDATE)" ở Gate 1 Bước 0 trước khi làm bất cứ điều gì khác — không mặc định CREATE nếu chưa kiểm tra UC Spec cũ đã tồn tại và PM merge chưa
- ❌ **KHÔNG** hỏi lại (Mode UPDATE) điều đã Confirmed ở version trước — chỉ hỏi cho phần delta + phần phát hiện qua bước quét side-effect bắt buộc (Gate 1 Bước 2)
- ✅ **BẮT BUỘC** (Mode UPDATE) ghi mọi thay đổi vào section "Change Log" của `UC-Spec_v{N}.md` — không âm thầm sửa/xoá nội dung mà không ghi lý do
