init git

.claude/skills/ba-traceability/GUIDE.md

@@ -0,0 +1,151 @@
+# Hướng dẫn sử dụng — `ba-traceability` (xuyên suốt)
+
+## Skill này làm gì
+
+Trả lời đúng một câu hỏi: **"có cái gì bị rơi giữa các tài liệu không?"**
+
+Nó đọc toàn bộ artifact của một project, trích mọi ID (`RQ`, `US`, `BR`, `AC`, `NFR`…), rồi
+đối chiếu chéo để tìm bốn loại lỗ hổng:
+
+| Loại lỗ hổng | Nghĩa là |
+|---|---|
+| **Yêu cầu bị bỏ quên** | Khách yêu cầu, không ai làm |
+| **Scope creep** | Team làm, không ai yêu cầu |
+| **AC không được test** | Yêu cầu không được kiểm chứng |
+| **Tham chiếu gãy** | Spec nhắc `BR-021`, tìm không ra ⇒ dev tự quyết |
+
+Nó **có quyền chặn Gate G2, G3, G4**.
+
+## 🔴 Nó không sửa tài liệu
+
+Skill này chỉ phát hiện và báo cáo, kèm chỉ dẫn skill nào cần chạy để sửa. Tự sửa sẽ che
+mất vấn đề thay vì giải quyết nó.
+
+## Khi nào gọi
+
+| Tình huống | Có nên gọi |
+|---|---|
+| Vừa chạy xong một skill giai đoạn | ✅ **Nên thành thói quen** |
+| Chuẩn bị họp duyệt gate | ✅ Bắt buộc |
+| Vừa sửa một `BR` hoặc `AC` | ✅ Để biết chỗ nào phải sửa theo |
+| Nhận bàn giao dự án từ BA khác | ✅ Cách nhanh nhất để biết tài liệu thiếu gì |
+| Sếp hỏi "đã phủ hết yêu cầu chưa" | ✅ |
+| Lần đầu chạy vào hôm trước ngày họp duyệt | 🟠 Được, nhưng phát hiện lúc đó chỉ để hoãn họp |
+
+## Cú pháp
+
+```
+/ba-traceability <PROJECT|US-id> [--gate g2|g3|g4] [--out <path>] [go]
+```
+
+| Tham số | Ý nghĩa |
+|---|---|
+| `--gate` | Chỉ chạy các phép kiểm liên quan tới một gate cụ thể |
+| `go` | Bỏ bước dừng xác nhận input |
+
+## Bạn sẽ nhận được gì
+
+File `ba-output/<PROJECT>/00-index/RTM_<PROJECT>.md` + năm phần in ra màn hình:
+
+**① Bảng coverage** — sáu phép kiểm, mỗi cái một con số
+
+```
+| Phép kiểm            | Tổng | Đã phủ | Coverage | Ngưỡng | ☐/✅ |
+| RQ → US              | 12   | 11     | 91,7%    | 100%   | 🔴  |
+| US → RQ              | 18   | 16     | 88,9%    | 100%   | 🔴  |
+| US → AC (đủ 4 nhóm)  | 18   | 12     | 66,7%    | 100%   | 🔴  |
+```
+
+**② Chi tiết từng lỗ hổng** — kèm lệnh để sửa:
+
+```
+🔴 RQ-005 chưa có US nào phủ
+   Định nghĩa tại: BRIEF_Settlement_v1.0.md §6
+   Sửa bằng: /ba-2-analysis Settlement
+```
+
+**③ Bảng nhất quán** — version lệch, ràng buộc lệch, mã lỗi lệch, trạng thái lệch
+
+**④ `OQ`/`CR` tồn đọng** — sắp theo số ngày quá hạn
+
+**⑤ Kết luận gate** — gate nào bị chặn và vì sao
+
+## Hai chiều, hai loại lỗi
+
+Đây là điểm quan trọng nhất cần hiểu về skill này:
+
+```
+chiều xuôi   RQ → US → AC → test case      bắt: BỎ SÓT
+chiều ngược  test case → AC → US → RQ      bắt: LÀM THỪA
+```
+
+Hầu hết công cụ traceability chỉ chạy chiều xuôi. Chiều ngược mới trả lời được câu hỏi
+*"cái này ai yêu cầu?"* — và scope creep là thứ làm dự án trễ mà không ai giải thích được
+vì sao.
+
+## Ví dụ hội thoại
+
+```
+Bạn:    /ba-traceability Settlement --gate g3
+
+Claude: [Bước 0]
+        Quét được:
+        | BRIEF_Settlement_v1.0.md   | 12 RQ, 3 GOAL       | ✅ Baselined |
+        | BACKLOG_Settlement_v1.0.md | 18 US               | ✅ Baselined |
+        | BR_Settlement_v1.2.md      | 24 BR               | ✅ Baselined |
+        | SRS_US011_v1.2.md          | 8 AC, 12 field      | 🟠 In Review |
+        | SRS_US012..018             | Không tìm thấy       | — |
+
+        ⚠️ Chỉ có SRS cho 1/18 US. Phép kiểm "US → AC" sẽ báo coverage rất thấp —
+        đúng thực tế, không phải lỗi quét.
+
+        Test case: chưa tìm thấy ⇒ phép kiểm 5 (AC → test case) không chạy được.
+
+        Xác nhận giúp tôi trước khi chạy.
+
+Bạn:    Đúng rồi, mới viết SRS cho US011 thôi. Chạy đi.
+
+Claude: [báo cáo]
+
+        G3: 🔴 CHẶN
+        - 17/18 US chưa có SRS
+        - US-011: thiếu AC nhóm "lỗi hệ thống" và "phân quyền"
+        - 4 TBD trong bảng field US-011 (F01 độ dài, F04 nguồn dropdown…)
+        - BR-021 tham chiếu ở SRS_US011 §1.3 nhưng không có trong BR_v1.2
+          → có thể BR bị đổi số ở v1.1
+```
+
+## Lỗi thường gặp
+
+**"Coverage 99%, làm tròn lên 100% được không?"**
+Không. Cái 1% đó là một yêu cầu thật, của một người thật, và nó sẽ lọt ra sản phẩm mà không
+ai kiểm chứng.
+
+**"BR-021 được nhắc trong SRS rồi, tính là đã phủ chứ?"**
+Không. Nhắc tới không có nghĩa là đã hiện thực hoá. Phải xem nó được áp vào field/AC nào.
+Đếm số lần xuất hiện là phép đo sai.
+
+**"Tham chiếu gãy chắc do đánh nhầm số thôi, bỏ qua."**
+Tham chiếu gãy nghĩa là dev đọc spec, thấy "theo BR-021", đi tìm không ra, rồi tự quyết.
+Đó là cách một business rule bốc hơi khỏi sản phẩm mà không ai biết.
+
+**"US-013 đã có AC rồi mà sao báo chưa phủ?"**
+Phép kiểm 3 đòi **đủ bốn nhóm**: thành công · validation · lỗi hệ thống · phân quyền. US chỉ
+có AC nhóm 1 tính là chưa phủ, không phải "phủ một phần" — vì phần thiếu chính là phần dev
+sẽ tự bịa.
+
+**"Skill tự sửa giúp luôn được không?"**
+Không, và cố ý như vậy. Nó báo cáo kèm lệnh để sửa. Tự sửa sẽ che mất vấn đề, và nguyên
+nhân gốc (đặc tả thiếu chỗ nào) không bao giờ được ghi nhận để cải thiện.
+
+**"Chỉ cần chạy trước gate là đủ."**
+Chạy sau mỗi giai đoạn thì lỗ hổng được phát hiện lúc còn rẻ. Chạy lần đầu vào hôm trước
+ngày họp duyệt thì phát hiện cũng chỉ để hoãn họp.
+
+## Liên quan
+
+- Quy ước ID: `../README.md` §4
+- Tiêu chí gate: `../ba-lifecycle/references/workflow.md` §2
+- Quan hệ phụ thuộc giữa artifact (sửa cái này thì phải sửa tiếp cái nào):
+  `../ba-lifecycle/references/artifact-map.md` §5
+- Template: `templates/rtm.md`