sys-analysis-design/.claude/skills/ba-traceability/GUIDE.md

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