init git

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