init git

.claude/skills/ba-lifecycle/references/artifact-map.md

@@ -0,0 +1,141 @@
+# Bản đồ artifact
+
+## 1. Toàn bộ artifact, ai sinh, ai tiêu thụ
+
+| Mã | Tên đầy đủ | Thư mục | Sinh bởi | Tiêu thụ bởi |
+|---|---|---|---|---|
+| `BRIEF` | Project Brief | `01-discovery/` | ba-1 | PO, toàn team |
+| `STAKEHOLDER` | Stakeholder Map & Analysis | `01-discovery/` | ba-1 | BA, PM |
+| `ELICITATION` | Biên bản khai thác yêu cầu | `01-discovery/` | ba-1 | ba-2 |
+| `RISK` | Sổ rủi ro & giả định | `01-discovery/` | ba-1 | PM, ba-5 |
+| `PROCESS` | Quy trình AS-IS / TO-BE | `02-analysis/` | ba-2 | Dev, QA, ba-5 |
+| `BACKLOG` | Feature list & User story backlog | `02-analysis/` | ba-2 | PO, ba-3 |
+| `BR` | Business Rules | `02-analysis/` | ba-2 | ba-3, Dev, QA |
+| `RBAC` | Ma trận phân quyền | `02-analysis/` | ba-2 | ba-3, Dev, Security |
+| `IMPACT` | Phân tích tác động | `02-analysis/` | ba-2 | Tech Lead, QA |
+| `SRS` | Software Requirements Specification | `03-specification/` | ba-3 | Dev, QA |
+| `AC` | Acceptance Criteria (nếu tách khỏi SRS) | `03-specification/` | ba-3 | QA |
+| `API` | API contract đề xuất | `03-specification/` | ba-3 | Dev BE/FE |
+| `NFR` | Yêu cầu phi chức năng | `03-specification/` | ba-3 | Dev, Ops, QA |
+| `WF` | Wireframe / Prototype | `03-specification/` | ba-3 | Dev, PO |
+| `QLOG` | Clarification log | `04-delivery/` | ba-4 | Dev, QA |
+| `CR` | Change Request | `04-delivery/` | ba-4 | PO, PM, Dev |
+| `TCREVIEW` | Biên bản review test case | `04-delivery/` | ba-4 | QA |
+| `UAT` | Kế hoạch & kết quả UAT | `04-delivery/` | ba-4 | PO |
+| `RELNOTE` | Release note nghiệp vụ | `05-post-release/` | ba-5 | Người dùng |
+| `MANUAL` | Tài liệu hướng dẫn sử dụng | `05-post-release/` | ba-5 | Người dùng, CS |
+| `BENEFIT` | Benefit realization review | `05-post-release/` | ba-5 | PO, BA Lead |
+| `RTM` | Requirements Traceability Matrix | `00-index/` | ba-traceability | Mọi vai trò |
+| `GLOSSARY` | Từ điển thuật ngữ | `00-index/` | ba-1, bồi đắp dần | Mọi vai trò |
+| `DECISION` | Sổ quyết định (`DEC-nn`) | `00-index/` | mọi skill | Mọi vai trò |
+| `OQ` | Sổ open question | `00-index/` | mọi skill | Mọi vai trò |
+| `INDEX` | Mục lục dự án | `00-index/` | ba-lifecycle | Mọi vai trò |
+
+## 2. Header bắt buộc của mọi artifact
+
+Mọi file `.md` sinh ra phải mở đầu bằng khối này. Thiếu một dòng ⇒ gate không chấm được.
+
+```markdown
+# <LOẠI> — <Tên phạm vi>
+
+| | |
+|---|---|
+| **Version** | 1.0 |
+| **Date** | 2026-08-30 |
+| **Author** | <tên BA> (qua skill ba-3-specification) |
+| **Status** | 🟡 Draft / 🟠 In Review / 🔵 Approved / ✅ Baselined / 📦 Archived |
+| **Approved by** | — *(điền tên + ngày khi được ký)* |
+| **Source** | <danh sách file input đã dùng, mỗi cái một dòng> |
+| **Scope** | <module / US id> |
+
+## Change Log
+
+| Version | Date | Người sửa | Thay đổi | CR |
+|---|---|---|---|---|
+| 1.0 | 2026-08-30 | … | Bản đầu | — |
+```
+
+**Ý nghĩa `Status`** — đây là thứ gate đọc, không phải tên file:
+
+| Status | Nghĩa | Ai được sửa file |
+|---|---|---|
+| 🟡 Draft | BA đang viết | BA tự do |
+| 🟠 In Review | Đã gửi duyệt | BA sửa theo comment |
+| 🔵 Approved | Người duyệt đã đồng ý nội dung | BA sửa, ghi Change Log |
+| ✅ Baselined | Đã qua gate, là nguồn sự thật | **Chỉ sửa qua `CR-nnn`** |
+| 📦 Archived | Đã bị thay bằng version mới | Không sửa |
+
+## 3. Quy tắc version
+
+| Thay đổi | Tăng |
+|---|---|
+| Sửa lỗi chính tả, làm rõ câu chữ, không đổi nghĩa | `+0.1` |
+| Thêm/sửa nội dung nghiệp vụ, thêm AC, sửa rule | `+0.1` |
+| Tái cấu trúc tài liệu, đổi phạm vi, gộp/tách US | `+1.0` |
+| Qua gate lần đầu | đặt `1.0`, Status `✅ Baselined` |
+
+File đạt `✅ Baselined` mà cần sửa: tạo version mới, **chuyển bản cũ vào `archive/`** cùng
+thư mục, Status bản cũ đổi thành `📦 Archived`. Không xoá file.
+
+## 4. Mẫu `INDEX_<PROJECT>.md`
+
+```markdown
+# INDEX — <PROJECT>
+
+| | |
+|---|---|
+| **Cập nhật** | 2026-08-30 |
+| **Giai đoạn hiện tại** | GĐ2 · Analysis |
+| **Gate gần nhất đã qua** | G1 (2026-08-20, ký bởi …) |
+
+## Artifact
+
+| Loại | File mới nhất | Version | Status | Cập nhật |
+|---|---|---|---|---|
+| BRIEF | `01-discovery/BRIEF_<...>_v1.0.md` | 1.0 | ✅ | 2026-08-20 |
+
+## Open Question đang mở
+
+| ID | Nội dung | Hỏi ai | Từ ngày | Chặn gì |
+|---|---|---|---|---|
+
+## Quyết định đã chốt
+
+| ID | Quyết định | Người quyết | Ngày | Ảnh hưởng |
+|---|---|---|---|---|
+```
+
+`INDEX` do `ba-lifecycle` cập nhật mỗi lần chạy. Các skill giai đoạn **không sửa INDEX** —
+chúng chỉ ghi artifact của mình rồi báo cho người dùng chạy `/ba-lifecycle` để đồng bộ.
+
+## 5. Quan hệ phụ thuộc
+
+Mũi tên = "cần cái kia mới viết đúng được". Thiếu input ⇒ vẫn làm, nhưng phải ghi `OQ` và
+nêu rõ trong Source là đã dùng nguồn thay thế nào.
+
+```mermaid
+flowchart LR
+    STK["STAKEHOLDER"] --> BRIEF["BRIEF"]
+    ELI["ELICITATION"] --> BRIEF
+    BRIEF --> RISK["RISK"]
+    BRIEF --> BACKLOG["BACKLOG"]
+    PROCESS["PROCESS"] --> BACKLOG
+    BACKLOG --> BR["BR"]
+    BACKLOG --> RBAC["RBAC"]
+    IMPACT["IMPACT"] --> SRS["SRS"]
+    BR --> SRS
+    RBAC --> SRS
+    SRS --> AC["AC"]
+    SRS --> API["API"]
+    SRS --> NFR["NFR"]
+    SRS --> WF["WF"]
+    AC --> UAT["UAT"]
+    UAT --> BENEFIT["BENEFIT"]
+    UAT --> RELNOTE["RELNOTE"]
+    UAT --> MANUAL["MANUAL"]
+```
+
+**RTM đọc:** `BRIEF`(RQ) · `BACKLOG`(US) · `SRS`+`AC`(AC, field, mã lỗi) · `UAT`(test case) · `CR`
+
+Đọc xuôi mũi tên để biết **sửa cái này thì phải sửa tiếp cái nào**. Ví dụ sửa một `BR` ⇒
+phải rà lại `SRS`, `AC`, test case, và cập nhật `RTM`.

.claude/skills/ba-lifecycle/references/diagram-rules.md

@@ -0,0 +1,275 @@
+# Quy tắc vẽ sơ đồ trong tài liệu BA
+
+Mọi sơ đồ trong bộ skill này viết bằng **mermaid**, không dùng ASCII art.
+
+Lý do không phải thẩm mỹ:
+
+| ASCII art | mermaid |
+|---|---|
+| Dán vào Confluence/PowerPoint là vỡ, phải vẽ lại tay | GitHub · GitLab · Confluence · Artifact của Claude Code render thẳng |
+| `git diff` ra một khối rác | Diff theo dòng, review được từng cạnh |
+| Ký hiệu tự chế, khách quen UML/BPMN đọc lệch | Ký hiệu chuẩn của từng loại sơ đồ |
+| Sửa một node phải căn lại cả hình | Sửa một dòng |
+
+---
+
+## W13 — Mỗi sơ đồ phải có bảng đi kèm
+
+🔴 **Quy tắc quan trọng nhất của file này.**
+
+**Sơ đồ để nhìn, bảng để truy vết và test.** Sơ đồ không diễn đạt được: điều kiện chính xác,
+ai được làm, mã lỗi nào, quy tắc nào chi phối, ai chịu trách nhiệm. Một sơ đồ đứng một mình
+là một bức tranh đẹp mà QA không viết được test case từ đó.
+
+| Sơ đồ | Bảng bắt buộc đi kèm |
+|---|---|
+| Quy trình AS-IS/TO-BE | Bảng chi tiết từng bước: ai · input · output · công cụ · thời gian |
+| Vòng đời trạng thái | Bảng chuyển: nguồn · sự kiện · **điều kiện** · đích · ai được làm · BR · ghi vết |
+| Use case | Bảng US: id · vai trò · RQ · MoSCoW |
+| ERD | Bảng thực thể: trường · kiểu · khoá · ràng buộc |
+| Sequence | Bảng bước: mã lỗi mỗi nhánh · timeout · hành vi khi thất bại |
+| Lineage / phụ thuộc | Bảng luồng: tần suất · khối lượng · SLA · chủ sở hữu |
+
+Khi sơ đồ và bảng mâu thuẫn: **bảng thắng**. Ghi câu này vào tài liệu (quy tắc W11).
+
+---
+
+## Chọn loại sơ đồ
+
+| Cần thể hiện | Dùng | Ở đâu trong bộ skill |
+|---|---|---|
+| Quy trình có rẽ nhánh | `flowchart TD` | `PROCESS` A1/B1 |
+| Vòng đời trạng thái | `stateDiagram-v2` | `BR` §3 |
+| Actor × chức năng, toàn cảnh phạm vi | `flowchart LR` + `subgraph` | `BACKLOG` §0 |
+| Thực thể và quan hệ | `erDiagram` | `BR` §4 |
+| Luồng nhiều bên theo thời gian | `sequenceDiagram` | `srs-part2/*` |
+| Luồng dữ liệu, phụ thuộc job | `flowchart LR` | `srs-part2/data-pipeline`, `batch-job` |
+| Điều hướng màn hình | `flowchart LR` | `srs-part2/screen` |
+| Ma trận 2×2 | `quadrantChart` | `STAKEHOLDER` §2 |
+| Ma trận 3×3 trở lên | **bảng markdown** — mermaid không có loại này | `RISK` §2 |
+| Ranh giới hệ thống | `flowchart LR` + `subgraph` | `BRIEF` §5.3 |
+
+**Không dùng** `gantt` (tiến độ là việc của PM, không phải BA) và `pie` (một bảng luôn rõ hơn).
+
+---
+
+## Quy ước bắt buộc
+
+### 1. ID node không dấu, nhãn có dấu
+
+Ký tự tiếng Việt trong **ID** làm vỡ ở một số renderer. Luôn tách ID và nhãn:
+
+```
+✅  A1["Nhận file POS từ cửa hàng"]
+❌  Nhận file POS
+```
+
+Với `stateDiagram-v2` dùng dạng khai báo riêng:
+
+```
+state "Chờ duyệt" as ChoDuyet
+```
+
+### 2. ID mang mã truy vết
+
+Node ID chính là ID trong bảng — đó là thứ nối sơ đồ với bảng (W13):
+
+```
+A3["A3. Đối chiếu thủ công"]     ← khớp cột # của bảng chi tiết bước
+UC11(["US-011 Tải file POS"])     ← khớp id trong BACKLOG
+SCR01["SCR-01 Danh sách"]         ← khớp id trong bảng màn hình
+```
+
+### 3. Không tô màu, không style
+
+Renderer đổi theme sáng/tối; màu cứng làm chữ biến mất. Phân biệt bằng **hình dạng** và
+**nhãn**, không bằng màu:
+
+| Ý nghĩa | Hình dạng |
+|---|---|
+| Bước xử lý | `A["..."]` chữ nhật |
+| Điểm quyết định | `A{"..."}` thoi |
+| Bắt đầu / kết thúc | `A(["..."])` bo tròn |
+| Dữ liệu / tài liệu | `A[("...")]` trụ |
+| Hệ thống ngoài phạm vi | `A[["..."]]` khung đôi |
+
+Đánh dấu đặc biệt bằng **tiền tố trong nhãn**, không bằng màu:
+`"⚠️ P1 · Đối chiếu thủ công"` · `"🆕 B2 · ..."` · `"➖ A5 · (bỏ)"`
+
+### 4. Hướng vẽ
+
+`TD` (trên xuống) cho quy trình có nhiều rẽ nhánh · `LR` (trái sang phải) cho luồng tuyến
+tính, lineage, điều hướng, use case. Sơ đồ quá 20 node ⇒ **tách thành nhiều sơ đồ**, đừng
+thu nhỏ chữ.
+
+### 5. Nhãn cạnh là điều kiện, không phải mô tả
+
+```
+✅  ChoDuyet --> DaDuyet: duyệt (chênh lệch ≤ 10tr)
+❌  ChoDuyet --> DaDuyet: chuyển sang trạng thái đã duyệt
+```
+
+Điều kiện đầy đủ vẫn nằm ở bảng — nhãn cạnh chỉ là gợi nhớ.
+
+---
+
+## Mẫu chuẩn — sao chép rồi sửa
+
+### Quy trình
+
+````markdown
+```mermaid
+flowchart TD
+    START(["Đơn hàng phát sinh"]) --> A1["A1. Ghi nhận vào POS"]
+    A1 --> A2["A2. Xuất file cuối ca"]
+    A2 --> D1{"Có sai lệch?"}
+    D1 -->|Không| END(["Kết thúc"])
+    D1 -->|Có| A3["⚠️ P1 · A3. Đối chiếu thủ công"]
+    A3 --> EXT[["Gọi điện xác nhận với cửa hàng"]]
+    EXT --> A2
+```
+````
+
+### Vòng đời trạng thái
+
+````markdown
+```mermaid
+stateDiagram-v2
+    state "Nháp" as Nhap
+    state "Chờ duyệt" as ChoDuyet
+    state "Đã duyệt" as DaDuyet
+    state "Đã đóng" as DaDong
+
+    [*] --> Nhap
+    Nhap --> ChoDuyet: gửi duyệt (đủ trường bắt buộc)
+    ChoDuyet --> DaDuyet: duyệt
+    ChoDuyet --> Nhap: từ chối
+    DaDuyet --> DaDong: đóng (có ghi chú lý do)
+    DaDong --> [*]
+```
+````
+
+Kèm bảng chuyển trạng thái đầy đủ, **và bảng "chuyển trạng thái KHÔNG được phép"** — sơ đồ
+chỉ vẽ được cạnh có tồn tại, không vẽ được cạnh bị cấm.
+
+### Use case
+
+Mermaid không có use case diagram; dùng `flowchart LR` với `subgraph` làm ranh giới hệ thống:
+
+````markdown
+```mermaid
+flowchart LR
+    NV(["👤 Nhân viên đối soát"])
+    TN(["👤 Trưởng nhóm"])
+    KT(["👤 Kế toán"])
+
+    subgraph HT["Hệ thống đối soát"]
+        UC11(["US-011 Tải file POS"])
+        UC13(["US-013 Xem chênh lệch"])
+        UC14(["US-014 Đóng chênh lệch"])
+    end
+
+    NV --- UC11
+    NV --- UC13
+    TN --- UC13
+    TN --- UC14
+    KT --- UC13
+```
+````
+
+Dùng `---` (không mũi tên): quan hệ actor–use case là **liên kết**, không phải luồng.
+
+### ERD khái niệm
+
+Tên thực thể **không dấu, viết hoa**; tên tiếng Việt để ở bảng đi kèm.
+
+````markdown
+```mermaid
+erDiagram
+    CUA_HANG ||--o{ GIAO_DICH : "phát sinh"
+    GIAO_DICH ||--o| CHENH_LECH : "sinh ra khi lệch"
+    NGUOI_DUNG ||--o{ CHENH_LECH : "xử lý"
+
+    CUA_HANG {
+        string ma_cua_hang PK "3-20 ký tự"
+        string ten
+        enum   trang_thai
+    }
+    CHENH_LECH {
+        bigint id PK
+        bigint giao_dich_id FK
+        decimal so_tien "VND"
+        enum   trang_thai
+    }
+```
+````
+
+Ký hiệu lực lượng: `||--o{` một-nhiều · `||--||` một-một · `}o--o{` nhiều-nhiều ·
+`||--o|` một-không hoặc một.
+
+🔴 **ERD ở GĐ2 là mô hình khái niệm**, không phải schema. Nêu thực thể, quan hệ, khoá nghiệp
+vụ. Không nêu kiểu dữ liệu vật lý, index, bảng trung gian — đó là việc của SA/dev.
+
+### Sequence
+
+````markdown
+```mermaid
+sequenceDiagram
+    autonumber
+    actor U as Nhân viên
+    participant FE as Giao diện
+    participant BE as Hệ thống
+    participant POS as Hệ thống POS
+
+    U->>FE: Bấm Lưu
+    FE->>BE: POST /stores
+    BE->>POS: GET /verify (timeout 3s)
+    alt POS phản hồi kịp
+        POS-->>BE: 200 OK
+        BE-->>FE: 200 + id
+        FE-->>U: Toast "Đã lưu"
+    else POS timeout
+        POS--xBE: timeout
+        BE-->>FE: 503 · E-STR-0503
+        FE-->>U: Báo lỗi, GIỮ NGUYÊN dữ liệu đã nhập
+    end
+```
+````
+
+`autonumber` đánh số bước để bảng đi kèm tham chiếu được. **Bắt buộc vẽ cả nhánh lỗi** —
+sequence chỉ có luồng thành công là vi phạm quy tắc W4.
+
+### Ma trận 2×2
+
+````markdown
+```mermaid
+quadrantChart
+    title Stakeholder — Quan tâm × Ảnh hưởng
+    x-axis "Quan tâm thấp" --> "Quan tâm cao"
+    y-axis "Ảnh hưởng thấp" --> "Ảnh hưởng cao"
+    quadrant-1 "Quản lý sát"
+    quadrant-2 "Giữ hài lòng"
+    quadrant-3 "Theo dõi"
+    quadrant-4 "Giữ thông tin"
+    "STK-01 Trưởng phòng TC": [0.85, 0.90]
+    "STK-04 Pháp chế": [0.20, 0.85]
+```
+````
+
+⚠️ `quadrantChart` cần mermaid ≥ 10. Renderer cũ (một số bản Confluence) không hiểu ⇒ giữ
+bảng phân nhóm bên dưới làm phương án dự phòng.
+
+---
+
+## Khi mermaid không diễn đạt được
+
+Ba trường hợp, và cách xử lý:
+
+| Trường hợp | Làm gì |
+|---|---|
+| Bố cục màn hình | Wireframe ảnh — mermaid không phải công cụ vẽ UI |
+| Ma trận ≥ 3×3, bảng số liệu | Bảng markdown |
+| Sơ đồ > 20 node | Tách thành nhiều sơ đồ theo phân vùng, mỗi cái một mục con |
+
+**Không bao giờ** quay lại ASCII art vì "hình này mermaid vẽ xấu". Xấu thì tách nhỏ hoặc
+đổi loại sơ đồ.

.claude/skills/ba-lifecycle/references/domain-profiles.md

@@ -0,0 +1,192 @@
+# Project Profile — ba trục quyết định cách chạy pipeline
+
+Bộ skill này **không phụ thuộc ngành nghiệp vụ** (bán lẻ, y tế, logistics, ngân hàng, HR…
+đều dùng chung khung). Nhưng nó **phụ thuộc ba thứ khác**, và ba thứ đó phải được khai báo
+ngay ở Bước 0 của mọi skill:
+
+```
+PROFILE = PRODUCT × LIFECYCLE × RIGOR
+```
+
+Khai sai profile ⇒ skill đòi bạn điền những mục không tồn tại trong loại sản phẩm của bạn,
+hoặc bỏ qua những mục sống còn. Đây là thứ quyết định mọi guideline phía sau.
+
+---
+
+## 0. Cách khai báo
+
+Lần đầu chạy một project, `ba-lifecycle` tạo `00-index/PROFILE_<PROJECT>.md`:
+
+```markdown
+# PROFILE — <PROJECT>
+
+| | |
+|---|---|
+| **PRODUCT** | screen |
+| **LIFECYCLE** | brownfield |
+| **RIGOR** | standard |
+| **Ngành** | Bán lẻ / đối soát doanh thu |
+| **Người chốt profile** | <PO/BA Lead>, ngày… |
+| **Lý do chọn** | … |
+
+## Hệ quả đã áp dụng
+| Quyết định | Vì trục nào |
+|---|---|
+| Dùng biến thể SRS PART 2 = `screen` | PRODUCT |
+| Bắt buộc AS-IS đầy đủ + phân tích dữ liệu cũ | LIFECYCLE |
+| Gate ký bởi PO + Tech Lead + QA | RIGOR |
+```
+
+Mọi artifact khác thêm một dòng vào header: `| **Profile** | screen · brownfield · standard |`
+
+**Đổi profile giữa chừng** phải ghi `DEC-nn` và nêu artifact nào phải viết lại.
+
+---
+
+## 1. Trục PRODUCT — loại sản phẩm
+
+Trục quan trọng nhất. Nó quyết định **GĐ3 viết cái gì**.
+
+| Giá trị | Sản phẩm là gì | Biến thể SRS PART 2 |
+|---|---|---|
+| `screen` | Có giao diện người dùng — web admin, web app, app di động | `srs-part2/screen.md` |
+| `api-service` | Chỉ API/service, không giao diện; người tiêu thụ là hệ thống khác | `srs-part2/api-service.md` |
+| `data-pipeline` | Sản phẩm là **dữ liệu** — ETL, ingest, kho dữ liệu, báo cáo BI | `srs-part2/data-pipeline.md` |
+| `ml-model` | Sản phẩm là **mô hình dự đoán** — phân loại, xếp hạng, dự báo, sinh nội dung | `srs-part2/ml-model.md` |
+| `batch-job` | Job chạy theo lịch, không giao diện — đối soát đêm, sinh báo cáo, dọn dữ liệu | `srs-part2/batch-job.md` |
+| `process-only` | **Không phải phần mềm** — cải tiến quy trình, đổi cách làm việc | Không có PART 2 |
+
+### Hệ quả theo từng giai đoạn
+
+| | `screen` | `api-service` | `data-pipeline` | `ml-model` | `batch-job` | `process-only` |
+|---|---|---|---|---|---|---|
+| **GĐ1** Discovery | Đủ | Đủ; "người dùng" là **team tiêu thụ API** | Đủ; hỏi thêm về nguồn dữ liệu | Đủ; **bắt buộc** hỏi chi phí của dự đoán sai | Đủ | Đủ |
+| **GĐ2** `PROCESS` | Đủ | Đủ | Đủ | Đủ | Đủ | Đủ — **trọng tâm** |
+| **GĐ2** `RBAC` | Đủ | Theo client/scope thay vì vai trò người | Theo tập dữ liệu + độ nhạy cảm | Ai được xem điểm số/lý do | Ai được chạy tay | Đủ |
+| **GĐ3** PART 2 | Màn hình, field | Endpoint, schema | Luồng dữ liệu, data contract | Bài toán, metric, ngưỡng | Job, lịch, chạy lại | ❌ N/A |
+| **GĐ3** `AC` | 4 nhóm đầy đủ | 4 nhóm đầy đủ | 4 nhóm + **đối soát nguồn–đích** | 🔴 Chỉ áp cho hệ thống bao quanh; phần dự đoán dùng **ngưỡng metric** | 4 nhóm + **chạy lại** | Tiêu chí quy trình |
+| **GĐ3** text hiển thị | Bắt buộc | N/A | N/A | Chỉ phần hiển thị cho người | N/A | N/A |
+| **GĐ4** UAT | Người dùng thao tác | Team tiêu thụ tích hợp thử | Đối soát số liệu song song | 🔴 Đánh giá trên tập giữ lại + shadow mode | Chạy song song với cách cũ | Chạy thử quy trình |
+| **GĐ5** `MANUAL` | Cho người dùng cuối | **Tài liệu tích hợp** cho dev | Từ điển dữ liệu + hướng dẫn đọc số | Hướng dẫn diễn giải kết quả | Sổ tay vận hành | Quy trình mới |
+
+🔴 **`ml-model` là loại lệch nhiều nhất.** Yêu cầu mang tính xác suất, nên Given/When/Then
+không mô tả được — đọc kỹ phần đầu `srs-part2/ml-model.md` trước khi bắt đầu.
+
+### Loại chưa hỗ trợ
+
+`embedded` / IoT / firmware: NFR khác hẳn (điện năng, nhiệt độ, thời gian thực cứng, an
+toàn chức năng), và không có khái niệm "trạng thái rỗng". **Bộ skill này chưa có biến thể
+PART 2 cho nó.** Dùng khung GĐ1/GĐ2/GĐ4/GĐ5 vẫn được; PART 2 của GĐ3 phải tự viết. Nói rõ
+điều này với người dùng thay vì cố nhét vào biến thể gần đúng nhất.
+
+### Một project có nhiều loại
+
+Bình thường — một tính năng thường gồm `screen` + `api-service`, đôi khi + `batch-job`.
+Cách xử lý: **profile khai loại chính**, và GĐ3 nạp nhiều biến thể PART 2, mỗi biến thể một
+mục con. Không tách thành nhiều project.
+
+---
+
+## 2. Trục LIFECYCLE — nền cũ hay nền mới
+
+Quyết định **GĐ1 và GĐ2 nặng ở đâu**.
+
+| Giá trị | Nghĩa | AS-IS | Dữ liệu cũ | `IMPACT` |
+|---|---|---|---|---|
+| `greenfield` | Chưa có gì, không thay thế cái nào | Chỉ mô tả cách làm thủ công hiện tại (nếu có) | N/A — ghi rõ | Rút gọn: chỉ trục tích hợp |
+| `brownfield` | Thay thế/bổ sung hệ thống đang chạy | 🔴 **Bắt buộc đầy đủ** | 🔴 **Bắt buộc chọn 1 trong 3 phương án** | Đầy đủ 6 trục |
+| `enhancement` | Thêm/sửa trên module đã có | Chỉ phần bị đụng | Bắt buộc nếu đổi schema/rule | Đầy đủ 6 trục — **trọng tâm** |
+
+**Hệ quả cụ thể:**
+
+- `greenfield` ⇒ [process-model.md](../../ba-2-analysis/templates/process-model.md) PHẦN A rút
+  gọn còn A3 (điểm đau) + A4 (đường tắt) + A5 (ngoại lệ). Bỏ A1, A2, A6 và **ghi rõ lý do**,
+  đừng để trống.
+- `enhancement` ⇒ GĐ1 chạy chế độ rút gọn (`--mode enhancement`): chỉ `RQ` + rủi ro, bỏ
+  `BRIEF` đầy đủ. Nhưng `IMPACT` ở GĐ2 thì **nặng hơn** bình thường.
+- `brownfield` ⇒ mục "dữ liệu cũ xử lý thế nào" trong `IMPACT` §1.2 là blocker của G2.
+
+---
+
+## 3. Trục RIGOR — mức nghiêm ngặt
+
+Quyết định **gate chặt tới đâu và ai phải ký**. `standard` là baseline; `light` bớt đi,
+`strict` thêm vào.
+
+| Giá trị | Dùng khi | Ký gate |
+|---|---|---|
+| `light` | POC, thử nghiệm, công cụ nội bộ ≤ 2 tuần, không đụng tiền/dữ liệu cá nhân | Chỉ PO |
+| `standard` | Mặc định — sản phẩm thật, có người dùng thật | PO + Tech Lead + QA (theo từng gate) |
+| `strict` | Có tiền, dữ liệu cá nhân, yêu cầu pháp lý, chịu kiểm toán (tài chính, y tế, bảo hiểm) | Như standard **+ Bảo mật/Pháp chế ở G2 và G3** |
+
+Chi tiết tiêu chí bớt/thêm theo từng gate: [workflow.md §2.0](workflow.md).
+
+### Chọn `light` không phải là được phép làm ẩu
+
+`light` bỏ **thủ tục**, không bỏ **tư duy**. Bốn thứ không bao giờ được bỏ ở bất kỳ mức nào:
+
+1. Phát biểu bài toán (không có thì không biết đang giải gì)
+2. Ít nhất một `GOAL` có cách đo (không có thì không biết có thành công không)
+3. `OQ` cho mọi chỗ chưa rõ (bịa vẫn là bịa, kể cả trong POC)
+4. Ghi lại quyết định `DEC-nn` (POC hôm nay thành sản phẩm sáu tháng sau là chuyện thường)
+
+### Nâng mức giữa chừng
+
+POC `light` được duyệt thành sản phẩm ⇒ **nâng lên `standard` và chạy bù**: rà lại G1, G2,
+G3 theo checklist đầy đủ trước khi làm tiếp. Ghi `DEC-nn`. Không nâng bù là cách một POC
+mang theo mọi thiếu sót của nó vào sản phẩm thật.
+
+---
+
+## 4. Bảng tra nhanh — profile nào nạp gì
+
+| Profile | Template GĐ2 nạp | Biến thể PART 2 | Gate ký bởi |
+|---|---|---|---|
+| `screen · brownfield · standard` | Đủ 5 | `screen` | PO + TL + QA |
+| `screen · greenfield · light` | `BACKLOG`, `BR` | `screen` | PO |
+| `api-service · enhancement · standard` | `BACKLOG`, `BR`, `IMPACT` (nặng) | `api-service` | PO + TL + QA |
+| `data-pipeline · brownfield · strict` | Đủ 5 + đối soát | `data-pipeline` | PO + TL + QA + Bảo mật |
+| `ml-model · greenfield · standard` | `PROCESS`, `BACKLOG`, `BR` | `ml-model` | PO + TL + QA |
+| `batch-job · enhancement · strict` | `BACKLOG`, `BR`, `RBAC`, `IMPACT` | `batch-job` | PO + TL + QA + Bảo mật |
+| `process-only · brownfield · standard` | `PROCESS` (trọng tâm), `RBAC` | ❌ | PO |
+
+---
+
+## 5. Ba ví dụ profile thật
+
+**① Màn hình quản trị đối soát trong hệ thống bán lẻ đang chạy**
+```
+screen · brownfield · standard
+```
+Có giao diện, thay thế quy trình Excel đang dùng, đụng dữ liệu giao dịch có sẵn, không phải
+hệ thống chịu kiểm toán trực tiếp. → PART 2 `screen`, AS-IS bắt buộc, ký 3 bên.
+
+**② Luồng nạp dữ liệu POS hằng đêm vào kho dữ liệu, phục vụ báo cáo tài chính**
+```
+data-pipeline · greenfield · strict
+```
+Không giao diện, sản phẩm là dữ liệu, phục vụ báo cáo tài chính nên chịu kiểm toán. → PART 2
+`data-pipeline`, bắt buộc mục đối soát nguồn–đích và audit log, thêm chữ ký Bảo mật.
+
+**③ Thử nghiệm gợi ý sản phẩm cho app khách hàng, chạy 3 tuần xem có đáng đầu tư không**
+```
+ml-model · greenfield · light
+```
+POC, chưa có người dùng thật ngoài nhóm thử. → PART 2 `ml-model` nhưng chỉ mục 2.1–2.5,
+gate chỉ PO ký. Vẫn bắt buộc: bài toán, một metric có ngưỡng, `OQ`, `DEC`.
+
+---
+
+## 6. Chọn thế nào khi lưỡng lự
+
+| Lưỡng lự | Chọn | Vì |
+|---|---|---|
+| `screen` hay `api-service` | Theo **người tiêu thụ**: người → `screen`, hệ thống → `api-service` | Ai đọc AC quyết định AC viết thế nào |
+| `data-pipeline` hay `batch-job` | Sản phẩm là **dữ liệu để phân tích** → pipeline; là **việc được làm xong** → batch-job | Pipeline cần data contract, batch-job cần idempotency |
+| `ml-model` hay `screen` | Có thành phần dự đoán ⇒ **nạp cả hai biến thể** | Màn hình vẫn cần spec bình thường |
+| `brownfield` hay `enhancement` | Thay cả quy trình → brownfield; thêm một mẩu vào cái đang chạy → enhancement | Quyết AS-IS nặng hay nhẹ |
+| `standard` hay `strict` | Có tiền, dữ liệu cá nhân, hoặc ai đó có thể bị kiểm toán ⇒ `strict` | Nâng mức rẻ hơn nhiều so với sửa sau kiểm toán |
+| `light` hay `standard` | Kết quả sẽ được dùng thật bởi người ngoài nhóm ⇒ `standard` | "POC" mà có người dùng thật thì không còn là POC |
+
+**Không chắc ⇒ chọn mức cao hơn và hỏi người dùng.** Sai hướng "chặt quá" tốn thêm ít thủ
+tục; sai hướng "lỏng quá" mất thông tin không lấy lại được.

.claude/skills/ba-lifecycle/references/workflow.md

@@ -0,0 +1,211 @@
+# Workflow BA — 5 giai đoạn, 5 gate
+
+## 1. Sơ đồ
+
+```mermaid
+flowchart TD
+    START(["Ý tưởng / yêu cầu thô"])
+    GD1["GĐ1 · DISCOVERY<br/>ba-1-discovery<br/><br/>Hiểu bài toán, ai cần, thành công là gì"]
+    GD2["GĐ2 · ANALYSIS<br/>ba-2-analysis<br/><br/>Mô hình hoá nghiệp vụ, phân rã US, chốt rule"]
+    GD3["GĐ3 · SPECIFICATION<br/>ba-3-specification<br/><br/>Đặc tả tới mức code được, test được"]
+    GD4["GĐ4 · DELIVERY<br/>ba-4-delivery-support<br/><br/>Giải đáp, quản lý thay đổi, UAT"]
+    GD5["GĐ5 · POST-RELEASE<br/>ba-5-post-release<br/><br/>Bàn giao, đo hiệu quả, đề xuất vòng sau"]
+    END(["Đóng dự án hoặc mở vòng mới"])
+
+    START --> GD1
+    GD1 -->|"G1 — PO ký: bài toán & phạm vi đã đúng"| GD2
+    GD2 -->|"G2 — PO + Tech Lead ký: khả thi, backlog đủ"| GD3
+    GD3 -->|"G3 — PO + Tech Lead + QA ký: Ready for Dev"| GD4
+    GD4 -->|"G4 — PO ký UAT pass: Go-live"| GD5
+    GD5 -->|"G5 — Benefit review"| END
+
+    GD4 -.->|"spec sai/thiếu → CR"| GD3
+    GD4 -.->|"UAT lộ hiểu sai nghiệp vụ"| GD2
+    GD5 -.->|"KPI không đạt → vòng mới"| GD1
+```
+
+*Nét liền = đường đi xuôi qua gate. Nét đứt = ba đường quay lui hợp lệ (§5).*
+
+`ba-traceability` chạy song song, cập nhật RTM sau mỗi giai đoạn và **có quyền chặn G2, G3, G4**.
+
+## 2.0 Mức nghiêm ngặt — đọc trước §2
+
+Checklist ở §2 là **baseline của mức `standard`**. Hai mức còn lại là delta so với nó:
+
+| RIGOR | Cách đọc §2 |
+|---|---|
+| `light` | Áp checklist §2 **trừ đi** bảng "Bớt ở light" của từng gate |
+| `standard` | Áp đúng checklist §2 |
+| `strict` | Áp checklist §2 **cộng thêm** bảng "Thêm ở strict" của từng gate |
+
+Mức được khai trong `00-index/PROFILE_<PROJECT>.md` — xem [domain-profiles.md §3](domain-profiles.md).
+Chưa khai profile ⇒ **mặc định `standard`**, và skill phải nói rõ là đang dùng mặc định.
+
+🔴 **`light` bỏ thủ tục, không bỏ tư duy.** Bốn thứ không bao giờ được bỏ ở bất kỳ mức nào:
+phát biểu bài toán · ít nhất một `GOAL` có cách đo · `OQ` cho mọi chỗ chưa rõ · `DEC-nn` cho
+mọi quyết định.
+
+## 2. Tiêu chí pass từng gate
+
+Gate chỉ ✅ khi **đủ artifact** *và* **đủ nội dung** *và* **có chữ ký duyệt ghi trong header
+artifact** (dòng `Approved by: <tên> · <ngày>`).
+
+### G1 — Problem sign-off · duyệt bởi **PO**
+
+- [ ] `BRIEF` có: bối cảnh, phát biểu bài toán, phạm vi in/out, `GOAL-nn` kèm KPI đo được
+- [ ] `STAKEHOLDER` có đủ 4 nhóm: quyết định · sử dụng · bị ảnh hưởng · cung cấp thông tin;
+      mỗi người có tên thật, vai trò, mức quan tâm/ảnh hưởng
+- [ ] `ELICITATION` có biên bản ít nhất một buổi làm việc với nhóm "quyết định" và nhóm "sử dụng"
+- [ ] `RQ-nnn` được đánh MoSCoW, mỗi cái truy về được một stakeholder cụ thể
+- [ ] `RISK-nn` và `ASM-nn` đã ghi, rủi ro mức cao có người chịu trách nhiệm
+- [ ] KPI có **giá trị hiện tại (baseline)** — không có baseline thì sau này không đo được
+
+**Chặn:** phát biểu bài toán mô tả *giải pháp* thay vì *vấn đề* ("cần thêm nút export" là
+giải pháp; "mất 2 giờ/ngày tổng hợp số liệu thủ công" mới là vấn đề).
+
+| Bớt ở `light` | Thêm ở `strict` |
+|---|---|
+| Bỏ `ELICITATION` dạng biên bản chính thức — ghi tóm tắt vào `BRIEF` là đủ | Rà đích danh Bảo mật/Pháp chế trong `STAKEHOLDER`, có chữ ký của họ ở phần phạm vi dữ liệu |
+| `STAKEHOLDER` chỉ cần nhóm "quyết định" và "sử dụng" | Mọi `ASM` chạm dữ liệu cá nhân/tiền phải có **kế hoạch xác minh kèm hạn** ngay ở G1 |
+| Chỉ cần **1** `GOAL` có baseline, không cần đủ mọi GOAL | Ghi rõ căn cứ pháp lý áp dụng (điều khoản nào) |
+| Ký: chỉ PO | Ký: PO + Bảo mật/Pháp chế |
+
+### G2 — Solution sign-off · duyệt bởi **PO + Tech Lead**
+
+- [ ] `PROCESS` có AS-IS và TO-BE, mỗi bước ghi rõ ai làm, input/output, điều kiện rẽ nhánh
+- [ ] `BACKLOG` phân rã tới `US-nnn`, mỗi US có value statement và ước lượng sơ bộ
+- [ ] Mỗi `RQ-nnn` của G1 map được về ≥1 `US-nnn` — **RQ không có US là RQ bị bỏ quên**
+- [ ] `BR-nnn` đã chốt, không mâu thuẫn nhau
+- [ ] `RBAC` có ma trận vai trò × hành động; hành động phê duyệt/chốt sổ có bảng SoD
+- [ ] `IMPACT` nêu module/dữ liệu/tích hợp bị ảnh hưởng và cách xử lý dữ liệu cũ
+- [ ] Tech Lead xác nhận **khả thi kỹ thuật** và nêu ràng buộc (nếu có)
+- [ ] `ba-traceability` báo coverage RQ→US ≥ 100%
+
+**Chặn:** backlog có US nhưng không truy được về RQ nào (scope creep), hoặc TO-BE không
+giải quyết được pain point đã ghi ở G1.
+
+| Bớt ở `light` | Thêm ở `strict` |
+|---|---|
+| Bỏ `PROCESS` AS-IS nếu `LIFECYCLE = greenfield` | `RBAC` **bắt buộc** có bảng SoD, kể cả khi nghiệp vụ trông đơn giản |
+| Bỏ `RBAC` nếu chỉ có **1** vai trò — ghi rõ "1 vai trò" thay vì bỏ im lặng | `IMPACT` phải có kịch bản **rollback đã thử**, không chỉ mô tả |
+| `IMPACT` rút gọn: chỉ trục dữ liệu và tích hợp | Mọi `ASM` phải chuyển sang **đã xác minh** trước khi qua G2 (thay vì trước G3) |
+| Ký: chỉ PO | Ký: PO + Tech Lead + Bảo mật |
+
+### G3 — Ready for Dev · duyệt bởi **PO + Tech Lead + QA**
+
+- [ ] `SRS` đủ mọi mục bắt buộc (xem `ba-3-specification/templates/srs.md`)
+- [ ] Mỗi màn hình có bảng field: kiểu, bắt buộc, độ dài, default, validation, message lỗi
+- [ ] Mỗi `US` có `AC-<US>-nn` viết theo Given/When/Then, **có cả luồng lỗi**
+- [ ] Bảng mã lỗi `E-<DOMAIN>-nnnn` đầy đủ, mỗi mã có thông điệp hiển thị
+- [ ] `NFR` đã chốt cho các nhóm áp dụng, mỗi cái có cách verify
+- [ ] `API` contract có, hoặc ghi rõ là **giả định của BA** chờ BE xác nhận
+- [ ] Wireframe/prototype khớp với bảng component
+- [ ] QA xác nhận **mọi AC đều test được** — AC không test được là AC chưa viết xong
+- [ ] Không còn `OQ` mở nào ảnh hưởng tới hành vi hệ thống
+- [ ] `ba-traceability` báo coverage US→AC và AC→test case ≥ 100%
+
+**Chặn:** còn bất kỳ `TBD` nào trong bảng field hoặc bảng mã lỗi. Còn `OQ` mở về hành vi.
+**Đây là gate nghiêm nhất** — một chỗ mơ hồ lọt qua G3 sẽ thành một bug hoặc một CR.
+
+> Checklist trên viết theo `PRODUCT = screen`. Loại khác thì dòng "bảng field" và "wireframe"
+> được thay bằng tiêu chí tương ứng của biến thể PART 2 — xem đầu file
+> `ba-3-specification/templates/srs-part2/<loại>.md`.
+
+| Bớt ở `light` | Thêm ở `strict` |
+|---|---|
+| `AC` chỉ bắt buộc nhóm 1 (thành công) và 2 (validation). Nhóm 3–4 bắt buộc **nếu** có ghi/xoá dữ liệu hoặc có >1 vai trò | Bảng lưu vết (`NFR-AUD`) bắt buộc cho mọi hành động ghi |
+| `NFR` chỉ bắt buộc nhóm áp dụng rõ ràng; các nhóm khác ghi "N/A — POC" | Mọi mã lỗi phải có bản dịch đủ mọi ngôn ngữ hỗ trợ, không được để sau |
+| `API` được phép là phác thảo, không cần bảng đối chiếu mã lỗi | `API` phải do BE xác nhận, **không chấp nhận contract BA tự đề xuất** |
+| Không cần chữ ký QA | Ký: PO + Tech Lead + QA + Bảo mật/Pháp chế |
+
+### G4 — UAT pass · duyệt bởi **PO**
+
+- [ ] `UAT` có kịch bản phủ hết AC mức Must
+- [ ] Kết quả UAT ghi rõ pass/fail từng kịch bản, có bằng chứng
+- [ ] Mọi defect mức Critical/High đã đóng; Medium/Low có kế hoạch
+- [ ] Mọi `CR-nnn` phát sinh đã được quyết (chấp nhận / hoãn / từ chối), tài liệu đã cập nhật
+- [ ] `QLOG` không còn câu hỏi mở chặn dev
+- [ ] Dữ liệu migration (nếu có) đã đối chiếu và khớp
+
+**Chặn:** defect được "chấp nhận tạm" mà không có ticket theo dõi.
+
+| Bớt ở `light` | Thêm ở `strict` |
+|---|---|
+| Thay UAT chính thức bằng **demo + checklist** cho PO, vẫn phải có tiêu chí pass chốt trước | Bằng chứng UAT (ảnh, log, dữ liệu đầu vào/ra) phải **lưu trữ được** phục vụ kiểm toán |
+| Không cần kịch bản viết trước cho mức Should | Chạy song song với cách làm cũ tối thiểu 1 chu kỳ nghiệp vụ, đối chiếu kết quả |
+| Defect Low được đóng không cần ticket | Mọi defect, kể cả Low, phải có ticket |
+
+### G5 — Benefit review · duyệt bởi **PO + BA Lead**
+
+- [ ] `RELNOTE` nghiệp vụ đã phát hành cho người dùng
+- [ ] `MANUAL` / tài liệu đào tạo đã bàn giao
+- [ ] `BENEFIT` so sánh KPI thực tế với baseline và mục tiêu ở `GOAL-nn`
+- [ ] Feedback người dùng đã thu thập và phân loại
+- [ ] Đề xuất vòng sau đã lập, đưa vào backlog
+
+**Chặn:** không đo được KPI vì G1 không ghi baseline — ghi nhận đây là bài học, không lấp liếm.
+
+| Bớt ở `light` | Thêm ở `strict` |
+|---|---|
+| Bỏ `MANUAL` nếu người dùng là chính nhóm làm — vẫn phải có `RELNOTE` dù ngắn | Báo cáo `BENEFIT` phải nêu rõ **rủi ro tồn dư** và ai theo dõi tiếp |
+| Chỉ cần đo KPI + bài học; bỏ khảo sát người dùng chính thức | Lưu hồ sơ đào tạo: ai đã được đào tạo, ngày nào |
+
+🔴 **Nâng mức giữa chừng.** POC `light` được duyệt thành sản phẩm ⇒ nâng lên `standard` và
+**chạy bù** G1–G3 theo checklist đầy đủ trước khi làm tiếp, ghi `DEC-nn`. Không chạy bù là
+cách một POC mang theo mọi thiếu sót của nó vào sản phẩm thật.
+
+## 3. Ai làm gì
+
+| Vai trò | Trách nhiệm trong pipeline |
+|---|---|
+| **BA** | Sở hữu toàn bộ artifact ở đây. Khai thác, phân tích, đặc tả, giải đáp, hỗ trợ UAT |
+| **PO / Khách hàng** | Quyết ưu tiên và scope. Ký G1, G4, G5. Trả lời `OQ` nghiệp vụ |
+| **Tech Lead** | Ký G2, G3 về mặt khả thi. Quyết kiến trúc. Trả lời `OQ` kỹ thuật |
+| **QA** | Ký G3 về tính test được. Viết test case từ AC. Chủ trì thực thi UAT |
+| **Dev** | Tiêu thụ SRS. Đặt `OQ` qua `QLOG` |
+| **PM** | Tiến độ, nguồn lực. Không ký gate nội dung |
+
+BA **không** thay PO quyết ưu tiên, **không** thay Tech Lead chọn kiến trúc, **không** thay
+PM quản tiến độ — nhưng phải cung cấp đủ thông tin để cả ba ra quyết định.
+
+## 4. Khi nào được bỏ giai đoạn
+
+Bảng này là hệ quả của trục `LIFECYCLE` và `RIGOR` trong profile — xem
+[domain-profiles.md §2, §3](domain-profiles.md).
+
+| Tình huống | LIFECYCLE | Được bỏ | Bắt buộc giữ |
+|---|---|---|---|
+| Sửa lỗi nghiệp vụ nhỏ, không đổi hành vi | `enhancement` | GĐ1, GĐ2 | Cập nhật SRS + RTM |
+| Enhancement trên module đã có | `enhancement` | GĐ1 rút gọn (chỉ `RQ` + `IMPACT`) | GĐ2 `IMPACT` (nặng hơn bình thường), GĐ3 đầy đủ |
+| Module hoàn toàn mới, thay hệ thống đang chạy | `brownfield` | — | Đủ 5 giai đoạn, AS-IS bắt buộc |
+| Module mới, không thay thế gì | `greenfield` | `PROCESS` PHẦN A rút gọn còn A3–A5 | Đủ 5 giai đoạn |
+| POC / thử nghiệm | thường `greenfield` + `RIGOR=light` | GĐ5 | GĐ1 (để biết đo cái gì), GĐ3 rút gọn theo bảng "Bớt ở light" |
+
+Bỏ giai đoạn **phải ghi lý do vào `DEC-nn`** trong `00-index/`. Bỏ im lặng là nợ kỹ thuật
+tài liệu, sáu tháng sau không ai biết tại sao thiếu.
+
+## 5. Vòng lặp ngược
+
+Gate không phải một chiều. Ba đường quay lui hợp lệ:
+
+- **GĐ4 → GĐ3**: dev phát hiện spec sai/thiếu ⇒ `CR`, sửa SRS, cập nhật RTM, không cần ký lại G3
+  nếu thay đổi không đụng AC. Đụng AC ⇒ QA phải ký lại.
+- **GĐ4 → GĐ2**: UAT cho thấy nghiệp vụ hiểu sai ⇒ quay lại `PROCESS`/`BR`. Đây là tín hiệu
+  G1/G2 làm ẩu, ghi vào bài học ở GĐ5.
+- **GĐ5 → GĐ1**: KPI không đạt ⇒ mở vòng mới, `BRIEF` phiên bản mới, không sửa đè bản cũ.
+
+## 6. Ánh xạ sang bộ `ba:*` của berriz-platform-docs
+
+Đang làm dự án Berriz thì dùng bảng này để khỏi làm trùng:
+
+| Giai đoạn ở đây | Lệnh Berriz tương ứng | Phần bộ này bổ khuyết |
+|---|---|---|
+| GĐ1 Discovery | `/ba:brainstorm` (Gate 1) | Stakeholder map, biên bản elicitation, KPI baseline, risk |
+| GĐ2 Analysis | `/ba:blueprint` (Gate 2) + `/ba:wbs` (Gate 3) + `/ba:analyze` | Quy trình AS-IS/TO-BE, phân tích tác động |
+| GĐ3 Specification | `/ba:srs` (Gate 4) + `/ba:wireframe` + `/ba:prototype` | Bảng NFR verify, API contract, review AC theo QA |
+| GĐ4 Delivery | `/ba:feedback` + `/ba:pr` | Change request có quy trình, kế hoạch & kết quả UAT |
+| GĐ5 Post-release | — (không có) | Toàn bộ |
+| Traceability | `/ba:review` | Ma trận RTM hai chiều, báo cáo coverage định lượng |
+
+Nguyên tắc: **artifact do lệnh `ba:*` sinh ra là nguồn sự thật**, bộ này đọc chúng và bổ
+sung phần còn thiếu vào `ba-output/`, không sao chép lại nội dung.

.claude/skills/ba-lifecycle/references/writing-rules.md

@@ -0,0 +1,142 @@
+# 13 quy tắc viết tài liệu BA
+
+Mọi skill `ba-*` phải tuân thủ. Đây là thứ phân biệt một tài liệu dev đọc xong code được
+với một tài liệu dev đọc xong phải đi hỏi lại.
+
+## W1 — Một câu, một yêu cầu
+
+❌ "Hệ thống cho phép người dùng tìm kiếm, lọc theo trạng thái và xuất Excel."
+✅ Tách ba dòng, ba ID. Câu ghép làm test case không map được 1-1, và khi bỏ một vế thì
+   không biết ID nào bị ảnh hưởng.
+
+## W2 — Cấm từ mơ hồ
+
+Danh sách cấm, kèm cách thay:
+
+| Cấm | Thay bằng |
+|---|---|
+| nhanh, mượt, tối ưu | "phản hồi ≤ 2 giây ở p95 với 1.000 bản ghi" |
+| thân thiện, dễ dùng | mô tả hành vi cụ thể, hoặc đưa vào wireframe |
+| v.v., các trường hợp khác, tương tự | liệt kê hết. Không liệt kê hết được ⇒ `OQ` |
+| nên, có thể, thường thì | `phải` (Must) hoặc `được phép` (May) — chọn một |
+| xử lý phù hợp, xử lý tương ứng | nêu đích danh hành vi |
+| dữ liệu lớn, nhiều người dùng | con số + đơn vị |
+
+Quét trước khi nộp: `grep -niE "nhanh|mượt|thân thiện|v\.v|nên |có thể |phù hợp" <file>`
+
+## W3 — Mọi con số phải có đơn vị và nguồn
+
+"Tối đa 40" ⇒ 40 **ký tự** hay 40 **byte**? Tiếng Hàn/tiếng Việt có dấu khác nhau ở chỗ
+này. Ghi `40 ký tự (UTF-8, tính theo code point)` và nguồn: ai chốt, ngày nào.
+
+## W4 — Luồng lỗi là bắt buộc, không phải phần thêm
+
+Mỗi hành động phải có tối thiểu: luồng thành công · luồng validation fail · luồng hệ thống
+lỗi (timeout/5xx) · luồng không đủ quyền. Thiếu luồng lỗi ⇒ dev tự bịa ⇒ mỗi màn hình một
+kiểu.
+
+## W5 — Text hiển thị viết nguyên văn, trong bảng riêng
+
+Nhãn, placeholder, hint, thông điệp lỗi, text màn hình rỗng, nhãn trạng thái — **BA sở hữu
+những chuỗi này**. Viết đúng từng ký tự vào bảng, đủ mọi ngôn ngữ hỗ trợ. Không viết
+"hiển thị thông báo lỗi phù hợp".
+
+## W6 — Trạng thái phải có sơ đồ chuyển
+
+Thực thể có trạng thái ⇒ phải có bảng: `trạng thái nguồn | sự kiện | điều kiện | trạng thái
+đích | ai được làm`. Kèm câu trả lời cho: trạng thái khởi tạo là gì, trạng thái nào là cuối,
+từ trạng thái cuối có quay lại được không.
+
+## W7 — Phân biệt "ẩn" và "khoá"
+
+Ba trạng thái khác nhau, đừng gộp: **không hiển thị** · **hiển thị nhưng disable** ·
+**hiển thị và read-only**. Mỗi field/nút trong bảng component phải chỉ rõ cái nào, theo
+điều kiện gì.
+
+## W8 — Cấm quyết định thay PO trong tài liệu
+
+Gặp chỗ chưa rõ, viết:
+
+```markdown
+> **OQ-012** — Đơn hàng đã huỷ có được tính vào doanh thu tháng không?
+> **Hỏi:** PO (chị Lan) · **Từ:** 2026-08-28 · **Chặn:** AC-US059-04, BR-021
+> **Phương án BA đề xuất:** Không tính, vì … *(đề xuất, chưa phải quyết định)*
+```
+
+Không được im lặng chọn một phương án rồi viết như thể đã chốt. Đó là nguồn gốc của phần
+lớn CR ở giai đoạn UAT.
+
+## W9 — Truy vết trong chính câu văn
+
+Mỗi AC ghi kèm US nó phục vụ; mỗi BR ghi kèm RQ nó hiện thực hoá; mỗi field ghi kèm BR
+quy định nó. Truy vết nằm rải trong tài liệu, RTM chỉ tổng hợp lại — không phải ngược lại.
+
+## W10 — Viết cho ba người đọc cùng lúc
+
+| Người đọc | Họ tìm gì | Đáp ứng bằng |
+|---|---|---|
+| PO | Có đúng cái tôi cần không | Mục tóm tắt nghiệp vụ đầu tài liệu, ngôn ngữ nghiệp vụ |
+| Dev | Tôi code gì | Bảng field, bảng component, mã lỗi, API |
+| QA | Tôi test gì | AC Given/When/Then, bảng dữ liệu biên |
+
+Một tài liệu, ba mục tiêu. Đừng viết SRS chỉ cho dev đọc.
+
+## W11 — Ảnh không thay lời
+
+Wireframe minh hoạ bố cục. Hành vi luôn nằm ở bảng component và AC. Khi ảnh và bảng mâu
+thuẫn: **bảng thắng về việc "có tồn tại không"**, ảnh thắng về "nằm ở đâu, to bằng nào".
+Ghi rõ quy tắc này trong mỗi tài liệu có ảnh.
+
+## W12 — Ghi cả cái tài liệu KHÔNG nói
+
+Cuối mỗi tài liệu, mục **"Ngoài phạm vi"**: những thứ người đọc có thể tưởng là có nhưng
+không có. Ví dụ: *"Không xử lý đơn hàng đa tiền tệ trong phiên bản này"*. Nó ngăn dev làm
+thừa và ngăn PO tưởng đã có.
+
+## W13 — Sơ đồ vẽ bằng mermaid, và luôn có bảng đi kèm
+
+Hai vế, cả hai bắt buộc.
+
+**Vế 1 — mermaid, không ASCII art.** ASCII vỡ khi dán sang Confluence/PowerPoint, `git diff`
+ra một khối rác, và ký hiệu tự chế khiến khách quen UML/BPMN đọc lệch. Loại sơ đồ nào dùng
+cú pháp nào, quy ước ID/nhãn/hình dạng: [`diagram-rules.md`](diagram-rules.md).
+
+**Vế 2 — sơ đồ để nhìn, bảng để truy vết và test.** Sơ đồ không diễn đạt được điều kiện
+chính xác, ai được làm, mã lỗi nào, quy tắc nào chi phối. Sơ đồ đứng một mình là bức tranh
+đẹp mà QA không viết được test case từ đó.
+
+| Sơ đồ | Bảng bắt buộc đi kèm |
+|---|---|
+| Quy trình | Bảng bước: ai · input · output · công cụ · thời gian |
+| Vòng đời trạng thái | Bảng chuyển + **bảng chuyển bị cấm** *(sơ đồ không vẽ được cạnh cấm)* |
+| Use case | Bảng US: id · vai trò · RQ · MoSCoW |
+| ERD | Bảng thực thể: trường · kiểu · khoá · ràng buộc |
+| Sequence | Bảng bước: mã lỗi mỗi nhánh · timeout · hành vi khi thất bại |
+
+Sơ đồ mâu thuẫn bảng ⇒ **bảng thắng** (hệ quả của W11).
+
+---
+
+## Checklist tự chấm trước khi nộp bất kỳ tài liệu nào
+
+```
+[ ] W1  Không có câu chứa 2 yêu cầu trở lên
+[ ] W2  grep từ mơ hồ trả về rỗng
+[ ] W3  Mọi con số có đơn vị + nguồn
+[ ] W4  Mọi hành động có đủ 4 luồng
+[ ] W5  Có bảng text hiển thị nguyên văn
+[ ] W6  Thực thể có trạng thái đều có bảng chuyển trạng thái
+[ ] W7  Mọi field/nút có điều kiện ẩn/khoá/read-only rõ ràng
+[ ] W8  Mọi chỗ chưa rõ là OQ, không phải quyết định ngầm
+[ ] W9  Mọi AC/BR/field có tham chiếu ngược
+[ ] W10 Có tóm tắt nghiệp vụ cho PO ở đầu
+[ ] W11 Có câu quy định ảnh vs bảng
+[ ] W12 Có mục "Ngoài phạm vi"
+[ ] W13 Sơ đồ dùng mermaid (không ASCII), và mỗi sơ đồ có bảng đi kèm
+```
+
+Quét W13: `grep -n '```mermaid' <file>` phải khớp số sơ đồ; `grep -nE '^\s*[┌└├│─▼]' <file>`
+phải rỗng.
+
+In checklist này dạng bảng ☐/✅ ở cuối mỗi lần chạy skill. Mục chưa đạt ⇒ nói rõ thiếu gì,
+**không được đánh ✅ cho có**.