sys-analysis-design/.claude/skills/ba-lifecycle/references/workflow.md

# Workflow BA — 5 giai đoạn, 5 gate

## 1. Sơ đồ

<!-- archify: mermaid-only -->
```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 (+ Designer nếu screen) 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**.

`ba-design` (vai Design của bộ skill) chạy **song song GĐ3** khi `PRODUCT = screen`, sau activity `wf` của ba-3:
sinh `DS` (một lần/project), `HIFI`, `FIGMA`, `DSPEC` cho từng US. Artifact của nó **ký cùng G3**, không có gate riêng.

## 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%
- [ ] Sơ đồ `PROCESS` (workflow), `BR` §3 (lifecycle) có spec Archify validate pass; `diagram-check.mjs` không 🔴 trên `PROCESS`, `BACKLOG`, `BR`

**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** (+ **Designer** khi `PRODUCT = screen`)

- [ ] `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; khi SA đã có `CTR`, mỗi endpoint trỏ tới `operationId` trong file OpenAPI của `CTR` (file thắng bảng)
- [ ] Mọi sơ đồ trong `SRS` (điều hướng, sequence có nhánh lỗi, lineage, phụ thuộc job) có spec Archify validate pass; `diagram-check.mjs` không 🔴
- [ ] *(screen)* `UICONV_<PROJECT>` tồn tại, không còn ô "chọn một" chưa chọn, có chữ ký Designer (hoặc PO + `DEC-nn` khi dự án không có Designer)
- [ ] *(screen)* `WF_<US>` (md + html) phủ **mọi** `SCR` của SRS; tập `C-id` khớp **hai chiều** với bảng thành phần
- [ ] *(screen)* `WF` §5 (lệch prototype ↔ SRS) đã điền; không còn lệch **Tồn tại/Hành vi** chưa có người quyết
- [ ] *(screen)* `WF` chế độ ✏️ (BA tự dựng) có chữ ký Designer; chế độ 🎨 (prototype tham chiếu) có PO xác nhận §1 và §5
- [ ] *(screen · design)* `DS_<PROJECT>` tồn tại; `design-check` T1/T2 đạt (token ↔ `tokens.css` khớp, mọi cặp chữ/nền ≥ 4.5); §0 ghi độ tin cậy visual; có chữ ký Designer (hoặc PO + `DEC-nn`)
- [ ] *(screen · design)* `HIFI_<US>` phủ **mọi** `SCR` × trạng thái SRS §2.3.6 × (desktop + mobile); `design-check` H1–H5 đạt: `data-c`/`data-f` khớp **hai chiều** SRS, text `data-key` **nguyên văn** SRS §4.2, không mã màu thô
- [ ] *(screen · design)* `FIGMA_<US>/` có SVG desktop + mobile cho mọi `SCR`, màu ⊆ token (`design-check` S1); `DSPEC_<US>` §6 đã điền, không còn lệch Tồn tại/Hành vi/Text với SRS
- [ ] 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%, và *(screen)* SRS↔WF `C-id` lệch = 0

**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.
*(screen)* Còn lệch Tồn tại/Hành vi giữa prototype và SRS chưa quyết. *(screen · design)* `HIFI` có thành phần
không có trong SRS mà không bọc `hf-proto-only`, hoặc text `data-key` khác SRS §4.2.
**Đâ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", bốn dòng *(screen)*
> và ba dòng *(screen · design)* đượ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** |
| *(screen)* `WF` chỉ cần bảng vùng + bảng lệch, không cần HTML; `UICONV` chỉ cần §3–§6, §8 | *(screen)* `WF` phải có responsive đủ mọi breakpoint của `UICONV` §1 và thứ tự focus cho mọi form |
| *(screen · design)* `HIFI`/`FIGMA` không bắt buộc; `DS` chỉ cần §1 token + §3 ánh xạ; `DSPEC` bỏ | *(screen · design)* `HIFI` đủ cả tablet; tương phản AA cho **mọi** cặp kể cả badge/trạng thái; `DSPEC` §5 mọi dòng có bằng chứng; `FIGMA` có PNG mọi trạng thái |
| Không cần chữ ký QA; Designer không bắt buộc (PO ký `WF`) | Ký: PO + Tech Lead + QA + Designer + 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 |
| **Designer** *(khi `PRODUCT = screen`)* | Sở hữu prototype, design system, visual. Ký `UICONV`, `WF`, `DS`, `HIFI`, `DSPEC` ở G3. Trả lời lệch loại *Bố cục* ở `WF` §5 và `DSPEC` §6. Nhận từ BA: kho thành phần, text nguyên văn, trạng thái, phân quyền hiển thị — **không phải đi hỏi lại nghiệp vụ**. Nhận từ `ba-design`: `DS`/`HIFI`/`FIGMA` làm **đề xuất** để sửa trong Figma, không dựng lại từ đầu |
| **`ba-design`** *(vai Design của bộ skill, `screen`)* | Sinh `DS`, `HIFI`, `FIGMA`, `DSPEC` từ `SRS`+`WF`+`UICONV` (+ brand). **Đề xuất**, không duyệt: mọi artifact 🟡 Draft chờ Designer ký. Không quyết hành vi/text (chép từ SRS), không bịa brand (thiếu ⇒ token trung tính + `OQ`, độ tin cậy 🔴) |
| **Dev** | Tiêu thụ SRS + WF + UICONV. Đặ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 độ, **không** thay Designer quyết visual — nhưng phải cung cấp đủ thông tin để
cả bốn ra quyết định. Riêng visual: `ba-design` **đề xuất** (token, HIFI), Designer **quyết**. Riêng phần **bố cục và trạng thái**, BA làm được khi có prototype tham
chiếu (chế độ 🎨 của `WF`); không có thì BA đề xuất, Designer quyết (chế độ ✏️).

**Dự án không có Designer:** ghi `DEC-nn`, PO ký thay `UICONV`/`WF`/`DS`/`HIFI`/`DSPEC`, và mục §6 của `WF`
("Designer còn phải làm") là **việc của `ba-design`** (sinh `DS` + `HIFI` + `FIGMA` + `DSPEC`) — không đẩy sang
dev FE. Dev FE chỉ nhận phần `DSPEC` §7 "Bàn giao".

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