sys-analysis-design/.claude/skills/README-BA.md

Bộ skill BA — Business Analyst Toolkit

Bảy skill bao trọn năm giai đoạn công việc của một BA trong dự án, từ lúc nhận ý tưởng mơ hồ đến lúc đo hiệu quả sau release.

Mỗi skill làm đúng một giai đoạn, có đầu vào rõ, đầu ra rõ, và một gate phải qua trước khi sang giai đoạn sau. Không skill nào được lấn sân skill khác.

---

0. Project Profile — khai trước khi làm bất cứ việc gì

Bộ skill không phụ thuộc ngành nghiệp vụ (bán lẻ, y tế, logistics, ngân hàng, HR, giáo dục… dùng chung khung). Nhưng nó phụ thuộc ba trục khác, khai trong 00-index/PROFILE_<PROJECT>.md ngay lần chạy đầu:

PROFILE = PRODUCT × LIFECYCLE × RIGOR

Trục	Giá trị	Quyết định
PRODUCT	screen · api-service · data-pipeline · ml-model · batch-job · process-only	GĐ3 viết cái gì — nạp biến thể SRS PART 2 tương ứng
LIFECYCLE	greenfield · brownfield · enhancement	GĐ1 và GĐ2 nặng ở đâu — AS-IS, dữ liệu cũ, phân tích tác động
RIGOR	light · standard · strict	Gate chặt tới đâu và ai ký

Khai sai ⇒ skill đòi bạn điền mục không tồn tại trong loại sản phẩm của bạn, hoặc bỏ qua mục sống còn. Chi tiết và cách chọn khi lưỡng lự: ba-lifecycle/references/domain-profiles.md.

/ba-lifecycle <PROJECT> sẽ đề xuất profile và hỏi xác nhận nếu chưa có.

---

1. Bản đồ skill

#	Skill	Giai đoạn	Câu hỏi nó trả lời	Output chính	Gate
0	ba-lifecycle	Điều phối	"Tôi đang ở đâu, làm gì tiếp?"	Bảng trạng thái pipeline	—
1	ba-1-discovery	Khởi tạo	"Bài toán là gì, của ai, thành công là gì?"	BRIEF, STAKEHOLDER, ELICITATION	G1
2	ba-2-analysis	Phân tích	"Nghiệp vụ chạy thế nào, cần những gì?"	PROCESS, BACKLOG, BR, RBAC, IMPACT	G2
3	ba-3-specification	Đặc tả	"Dev code cái gì, QA test cái gì, màn hình bố cục ra sao?"	SRS, AC, API, NFR (+ UICONV, WF khi screen)	G3
4	ba-4-delivery-support	Đồng hành dev	"Câu hỏi/thay đổi/UAT xử lý ra sao?"	QLOG, CR, TCREVIEW, UAT	G4
5	ba-5-post-release	Sau release	"Có đạt mục tiêu không, cải tiến gì?"	RELNOTE, MANUAL, BENEFIT	G5
⊕	ba-traceability	Xuyên suốt	"Có sót yêu cầu nào không?"	RTM, báo cáo coverage	Chặn G2–G4

ba-lifecycle và ba-traceability không phải giai đoạn — chúng chạy ở mọi lúc.

flowchart LR
    ROUTER(["ba-lifecycle — router, gọi bất cứ lúc nào"])
    GD1["1 · Discovery"]
    GD2["2 · Analysis"]
    GD3["3 · Specification"]
    GD4["4 · Delivery"]
    GD5["5 · Post-release"]
    RTM(["ba-traceability — RTM cập nhật liên tục"])

    ROUTER -.-> GD1
    ROUTER -.-> GD5
    GD1 -->|G1| GD2
    GD2 -->|G2| GD3
    GD3 -->|G3| GD4
    GD4 -->|G4| GD5
    GD5 -->|G5| DONE(["Đóng / mở vòng mới"])

    GD2 -.-> RTM
    GD3 -.-> RTM
    GD4 -.-> RTM

---

2. Cấu trúc thư mục

D:\Kakao\Docs\.claude\skills\
├── README.md                      ← file này
├── ba-lifecycle/
│   ├── SKILL.md                   ← quy trình cho Claude
│   ├── GUIDE.md                   ← hướng dẫn sử dụng cho người
│   └── references/
│       ├── domain-profiles.md     ← 🔴 ba trục PRODUCT × LIFECYCLE × RIGOR
│       ├── workflow.md            ← 5 gate, tiêu chí pass theo từng mức, ai duyệt
│       ├── artifact-map.md        ← artifact nào ở đâu, tên file, version
│       ├── writing-rules.md       ← 13 quy tắc viết tài liệu BA (bắt buộc mọi skill)
│       └── diagram-rules.md       ← 🔴 mermaid: loại nào dùng khi nào, quy ước, mẫu chuẩn
├── ba-1-discovery/
│   ├── SKILL.md · GUIDE.md · examples.md
│   └── templates/
├── ba-2-analysis/          … (tương tự)
├── ba-3-specification/
│   ├── SKILL.md · GUIDE.md · examples.md
│   └── templates/
│       ├── srs.md                 ← PART 1,3–8 dùng chung mọi loại sản phẩm
│       ├── srs-part2/             ← 🔴 PART 2 cắm được theo PRODUCT
│       │   ├── screen.md · api-service.md · data-pipeline.md
│       │   └── ml-model.md · batch-job.md
│       ├── acceptance-criteria.md · nfr-checklist.md · api-contract.md
│       ├── ui-convention.md       ← (screen) quy ước UI cấp project, một lần
│       └── wireframe.md · wireframe.html  ← (screen) bố cục từng màn hình + render low-fi, đối chiếu prototype
├── ba-4-delivery-support/  …
├── ba-5-post-release/      …
└── ba-traceability/        …

SKILL.md = quy trình Claude thực thi, viết trung lập về ngành. GUIDE.md = tài liệu bạn đọc: khi nào dùng, cần chuẩn bị gì, ví dụ hội thoại, lỗi thường gặp. examples.md = ví dụ minh hoạ cùng một quy tắc ở nhiều ngành và nhiều loại sản phẩm. templates/ = khung tài liệu để điền.

---

3. Nơi ghi output

Mặc định mọi artifact ghi vào thư mục làm việc hiện tại:

ba-output/<PROJECT>/
├── 00-index/            PROFILE, RTM, glossary, decision log, open questions, UICONV (screen)
├── 01-discovery/        BRIEF, STAKEHOLDER, ELICITATION, RISK
├── 02-analysis/         PROCESS, BACKLOG, BR, RBAC, IMPACT
├── 03-specification/    SRS, AC, API, NFR, WF (.md + .html, screen)
├── 04-delivery/         QLOG, CR, TCREVIEW, UAT
└── 05-post-release/     RELNOTE, MANUAL, BENEFIT

Muốn nơi khác thì nói rõ khi gọi skill, ví dụ /ba-1-discovery Settlement --out .docs/output. Skill luôn hỏi xác nhận đường dẫn trước khi ghi file đầu tiên của một project mới.

Quy ước đặt tên file

<LOẠI>_<PHẠM_VI>_v<major>.<minor>.md

BRIEF_Settlement_v1.0.md · SRS_US059_v1.2.md · CR_US059-003_v1.0.md

Sửa nhỏ +0.1, tái cấu trúc +1.0. Mọi file có Change Log ở đầu. Không bao giờ ghi đè mất version cũ — bản cũ chuyển vào archive/.

---

4. Quy ước ID (dùng chung toàn bộ skill)

Tiền tố	Nghĩa	Sinh ở giai đoạn
STK-nn	Stakeholder	1
GOAL-nn	Mục tiêu kinh doanh + KPI	1
RQ-nnn	Yêu cầu mức nghiệp vụ	1
RISK-nn	Rủi ro	1
ASM-nn	Giả định	1
PRC-nn	Quy trình nghiệp vụ	2
US-nnn	User story	2
BR-nnn	Business rule	2
ROLE-nn	Vai trò trong RBAC	2
AC-<US>-nn	Acceptance criteria	3
FLD-<màn>-nn	Field spec	3
NFR-<nhóm>-nn	Yêu cầu phi chức năng	3
E-<DOMAIN>-nnnn	Mã lỗi	3
OQ-nnn	Open question	mọi giai đoạn
DEC-nn	Quyết định đã chốt	mọi giai đoạn
CR-nnn	Change request	4

ID không bao giờ tái sử dụng. Yêu cầu bị bỏ ⇒ đánh dấu [DROPPED], giữ nguyên số.

---

5. Cách gọi

/ba-lifecycle Settlement              # xem đang ở đâu, nên làm gì tiếp
/ba-1-discovery Settlement            # chạy giai đoạn 1
/ba-2-analysis US059                  # phân tích một US
/ba-3-specification US059             # viết SRS
/ba-4-delivery-support US059          # xử lý câu hỏi dev / CR / UAT
/ba-5-post-release Settlement 2026-09 # review sau release
/ba-traceability Settlement           # kiểm tra coverage, tìm yêu cầu bị sót

Không nhớ tên skill thì cứ mô tả việc cần làm — skill tự kích hoạt theo mô tả.

Mọi skill đều có Bước 0 "chốt input rồi dừng": liệt kê input tìm được, nêu input còn thiếu, tóm tắt cách hiểu, rồi chờ bạn xác nhận mới làm. Thêm chữ go vào lệnh để bỏ bước dừng — khi đó phần tự đánh giá input được ghi thẳng vào mục Open Questions.

---

6. Quan hệ với bộ ba:* của berriz-platform-docs

Hai bộ không thay thế nhau:

	Bộ này (ba-*)	Bộ ba:* trong berriz-platform-docs
Phạm vi	Chung cho mọi dự án	Riêng dự án Berriz, gắn với .agents/ba_rules.md
Trọng tâm	Toàn bộ nghề BA, kể cả elicitation/UAT/post-release	Pipeline tài liệu Berriz (brainstorm→blueprint→wbs→srs→deck)
Output	ba-output/	.docs/output/

Đang làm Berriz thì dùng ba:* cho pipeline tài liệu. Bộ này bổ khuyết những phần ba:* không có: khai thác yêu cầu, phân tích tác động, quản lý CR, UAT, đo hiệu quả. Ánh xạ chi tiết: ba-lifecycle/references/workflow.md §6.

---

6b. Sơ đồ trong tài liệu

Mọi sơ đồ vẽ bằng mermaid, không ASCII art — GitHub/GitLab/Confluence và Artifact của Claude Code render thẳng, git diff đọc được từng cạnh, và ký hiệu là chuẩn chứ không tự chế.

Sơ đồ	Loại mermaid	Sinh ở
Ranh giới hệ thống	flowchart LR + subgraph	BRIEF §5.3
Ma trận stakeholder	quadrantChart	STAKEHOLDER §2
5-Why đào pain point	flowchart TD	ELICITATION §A9
Quy trình AS-IS / TO-BE	flowchart TD	PROCESS A1, B1
Use case	flowchart LR + subgraph	BACKLOG §0
Cây phân rã RQ→US	flowchart LR	BACKLOG §1
Vòng đời trạng thái	stateDiagram-v2	BR §3
ERD khái niệm	erDiagram	BR §4
Điều hướng màn hình	flowchart LR	srs-part2/screen §2.2
Sequence (có nhánh lỗi)	sequenceDiagram	srs-part2/screen §2.3.4, api-service §2.3
Data lineage	flowchart LR	srs-part2/data-pipeline §2.2
Phụ thuộc job	flowchart LR	srs-part2/batch-job §2.2
Phân loại Defect/CR/Spec gap	flowchart TD	CR §0

🔴 Quy tắc W13: mỗi sơ đồ phải có bảng đi kèm. 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, ai chịu trách nhiệm. Chi tiết cú pháp và mẫu chuẩn: ba-lifecycle/references/diagram-rules.md.

Không thuộc phạm vi BA: C4, ADR, class diagram, threat model, schema vật lý — đó là việc của Solution Architect, làm bằng bộ sa-* (xem §6c).

---

6c. Quan hệ với bộ skill SA (sa-*)

Bộ sa-* (README-SA.md) làm phần kiến trúc kỹ thuật. Hai bộ chạy đan xen, không nối tiếp:

Mốc của bộ BA	Cần bộ SA đã qua	Vì sao
G2 Solution sign-off	AG1	Tech Lead ký "khả thi kỹ thuật" dựa trên OPT + ARISK của SA
G3 Ready for Dev	AG2	API trong SRS phải khớp ICD; NFR phải khớp QAS
G4 UAT pass	AG3	UAT không nên chạy trên kiến trúc chưa đo được NFR
G5 Benefit review	AG4	Đo hiệu quả nghiệp vụ đi cùng conformance kỹ thuật

Bốn chỗ hai bộ giao nhau, và bên nào thắng khi lệch:

Artifact BA	Artifact SA	Thắng khi lệch
NFR	QAS	QAS — BA ghi nhu cầu, SA chốt con số và cách đo
API (BA đề xuất, "chờ BE xác nhận")	ICD	ICD — SA chính là người xác nhận đó
RBAC	SEC §3.1	Bổ sung nhau — SEC map vai trò nghiệp vụ xuống cơ chế kỹ thuật
BR ép ràng buộc kiến trúc	ADR	BR là nguồn, ADR là quyết định

🔴 Không copy nội dung giữa hai bộ — tham chiếu bằng đường dẫn + ID. Copy là cách chắc chắn nhất để hai tài liệu lệch nhau sau ba lần sửa.

Ánh xạ chi tiết: sa-lifecycle/references/artifact-map.md §7.

6d. Bộ BA thay được bao nhiêu phần việc design?

Chỉ áp dụng khi PRODUCT = screen. Hai artifact UICONV (quy ước toàn project) và WF (bố cục từng màn hình, .md + .html low-fi) được thiết kế để nhận prototype làm đầu vào tham chiếu:

Đầu vào có sẵn	BA làm được	Design còn phải làm
Prototype đã duyệt + design system	Ghi lại bố cục, map thành phần, đối chiếu với SRS, liệt kê lệch (WF §5) — dev dựng UI từ SRS + WF + design system	Xử lý các dòng lệch ở WF §5
Prototype đã duyệt, chưa có design system	Như trên	Chọn/dựng design system, visual
Chỉ có mô tả UI dạng văn bản (SAD §7)	Bố cục mức vùng; thứ tự, kích thước là đề xuất	Duyệt WF, làm visual
Không có gì	WF chế độ ✏️ — đề xuất của BA, Designer bắt buộc ký	Thiết kế bố cục thật hoặc duyệt đề xuất, rồi visual

BA không bao giờ làm visual (màu, font, icon, motion). Designer là người ký UICONV và WF ở G3; dự án không có Designer ⇒ PO ký thay và ghi DEC-nn.

7. Phạm vi áp dụng — cái gì chuyển được, cái gì không

Ngành nghiệp vụ	✅ Chuyển được nguyên vẹn. Ví dụ trong examples.md cố tình trải trên nhiều ngành để chứng minh điều đó
Loại sản phẩm	✅ Sáu loại có sẵn qua PRODUCT. Loại khác cần viết thêm biến thể PART 2
Nhúng / IoT / firmware	🔴 Chưa hỗ trợ. GĐ1, GĐ2, GĐ4, GĐ5 dùng được; PART 2 của GĐ3 phải tự viết (NFR khác hẳn: điện năng, nhiệt độ, thời gian thực cứng). Skill sẽ nói rõ điều này thay vì nhét vào biến thể gần đúng
Không phải phần mềm	✅ Dùng PRODUCT = process-only — GĐ3 gần như bỏ, trọng tâm ở PROCESS và MANUAL

8. Nguyên tắc bất di bất dịch

Bốn quy tắc này ghi trong mọi SKILL.md và không skill nào được vi phạm:

1. Không bịa yêu cầu. Thông tin thiếu ⇒ ghi OQ-nnn, không tự điền giá trị hợp lý.
2. Không quyết định thay PO. Ưu tiên, scope, trade-off nghiệp vụ là việc của PO — BA trình phương án kèm khuyến nghị, không tự chốt.
3. Mọi phát biểu phải truy vết được. Mỗi dòng trong SRS chỉ về một RQ/BR/DEC hoặc một câu trả lời của stakeholder. Không nguồn ⇒ là giả định, phải ghi ASM-nn.
4. Không ghi đè tài liệu đã ký. Tài liệu qua gate chỉ được sửa qua CR-nnn có Change Log.