sys-analysis-design/.claude/skills/sa-conformance/GUIDE.md

# Hướng dẫn sử dụng — `sa-conformance` (xuyên suốt)

## Skill này giải quyết gì

Tài liệu kiến trúc luôn trông đầy đủ khi đọc riêng từng file. Chỗ đứt chỉ lộ ra khi nối chúng
lại: một yêu cầu định hình kiến trúc mà **không ai quyết định gì** về nó, một NFR mức Must
**chưa ai đo**, một component tồn tại mà **không phục vụ yêu cầu nào**.

Skill này nối và chỉ ra chỗ đứt. Nó **có quyền chặn AG2, AG3, AG4**.

**Không làm ở skill này:** thiết kế, viết ADR, sửa tài liệu của skill khác.

## Khi nào gọi

| Tình huống | Có nên gọi |
|---|---|
| **Trước mỗi lần trình gate** | ✅ `--mode full` — đỡ bị trả về |
| Sau mỗi sprint | ✅ `--mode dtm` |
| Vừa viết xong một `ADR` | ✅ `--mode adl` |
| Nhận bàn giao kiến trúc từ người khác | ✅ `--mode full` |
| Nghi ngờ có quyết định nào chưa được ghi | ✅ |
| Muốn biết làm gì tiếp | ❌ `/sa-lifecycle` |
| Muốn sửa chỗ đứt | ❌ Skill này chỉ báo — sửa bằng skill giai đoạn |

## Cú pháp

```
/sa-conformance <PROJECT> [--mode dtm|adl|full] [--gate AG2|AG3|AG4] [--out <path>] [go]
```

| Tham số | Ý nghĩa |
|---|---|
| `--mode dtm` | Chỉ ma trận truy vết quyết định |
| `--mode adl` | Chỉ mục lục ADR + 5 kiểm tra về ADR |
| `--mode full` | *(mặc định)* Cả hai + coverage + kết luận gate |
| `--gate AG2` | Chỉ chấm những kiểm tra chặn gate đó |

## Bạn sẽ nhận được gì

```
sa-output/<PROJECT>/00-index/
├── DTM_<PROJECT>.md    ← ma trận truy vết quyết định
└── ADL_<PROJECT>.md    ← mục lục ADR + cảnh báo
```

Cộng ba bảng in ra màn hình: coverage · danh sách phát hiện xếp theo mức · kết luận gate.

## Đọc báo cáo coverage thế nào

```
DRV → ASR/QAS          8/8    100%  ✅
ASR → ADR             11/13    85%  🔴 đứt: ASR-004, ASR-009           → chặn AG2
ADR → nguồn           14/16    88%  🟠 không nguồn: ADR-006, ADR-012
QAS(Must) → bài đo      6/9     67%  🔴 thiếu: QAS-009, QAS-011, QAS-012 → chặn AG3
Ràng buộc AGD → FIT    12/18    67%  🔴 thiếu và không có nhãn: §3.2-2, §3.4-3
CMP → ASR              9/11     82%  🟠 không phục vụ ASR nào: CMP-07, CMP-10
```

**Luôn có danh sách ID, không chỉ tỉ lệ.** "85%" không hành động được; "`ASR-004`, `ASR-009`"
thì hành động được ngay.

## Sáu chỗ đứt và ý nghĩa

| Chỗ đứt | Nghĩa là | Sửa bằng |
|---|---|---|
| `DRV` không có `ASR`/`QAS` | Áp lực kinh doanh không được kiến trúc phục vụ | `/sa-2-architecture --focus asr` |
| `ASR` không có `ADR` | Yêu cầu định hình kiến trúc mà không ai quyết gì | `/sa-2-architecture --focus adr` |
| `ADR` không có nguồn | Quyết định là sở thích cá nhân | Bổ sung §1 của ADR |
| `QAS` Must không có bài đo | Cam kết không kiểm chứng được | `/sa-3-enablement --focus fit` |
| Ràng buộc `AGD` không có `FIT`, không có nhãn | Sẽ bị vi phạm mà không ai biết | `/sa-3-enablement --focus fit` |
| `CMP` không phục vụ `ASR` nào | Thành phần có thể thừa | Rà lại `SAD` §4.1 |

## Năm kiểm tra riêng cho ADR

| Kiểm | Phát hiện gì | Hay gặp không |
|---|---|---|
| Chuỗi supersede | `ADR-A` nói bị `ADR-B` thay, nhưng `ADR-B` không nói thay `ADR-A` | Rất hay |
| `Proposed` quá 10 ngày | Quyết định treo, có người đang chờ mà không ai biết | Rất hay |
| Điểm radar ≥ 8 mà `Accepted` không POC | Cam kết dựa trên suy đoán | Hay |
| Nguồn đã đổi | ADR dựa trên một `QAS` đã bị sửa/bỏ | Hay, khó tự thấy |
| **Hai ADR mâu thuẫn** | Hai quyết định `Accepted` ngược nhau cùng chủ đề | Ít, nhưng đắt nhất |

🔴 Kiểm tra cuối chỉ tìm được khi rà **theo chủ đề** (dữ liệu, tích hợp, bảo mật, hạ tầng),
không phải theo số thứ tự. Đó là lý do skill này tồn tại thay vì đọc lướt sổ ADR.

## Ví dụ hội thoại

```
Bạn:    /sa-conformance Settlement --mode full --gate AG2

Claude: [Bước 0]
        Quét được: CTX v1.0 ✅ · OPT v1.0 ✅ · QAS v1.1 🟠 · ASR v1.0 🟠 ·
                   SAD v1.0 🟠 · ICD v1.0 🟡 · 13 ADR · DAT v1.0 🟡 · SEC ❌ chưa có
        ⚠️ ICD và DAT đang 🟡 Draft — sẽ quét nhưng tách riêng, không tính vào coverage chặn.
        Xác nhận?

Bạn:    go

Claude: ① Coverage (chỉ tính artifact 🟠 trở lên)

        DRV → ASR/QAS      8/8   100%  ✅
        ASR → ADR         11/13   85%  🔴 đứt: ASR-004, ASR-009
        ADR → nguồn       11/13   85%  🟠 không nguồn: ADR-006, ADR-012
        CMP → ASR          9/11   82%  🟠 thừa?: CMP-07, CMP-10

        ② Phát hiện

        🔴 CHẶN AG2
        1. ASR-004 "chịu được POS mất kết nối ≤ 4 giờ" (ASR_… §B2)
           → không có ADR nào. ASR này ép ra cơ chế hàng đợi bền, nhưng SAD §4.1
             không có component nào đảm nhận. Chạy /sa-2-architecture --focus adr.
        2. ASR-009 "dữ liệu cá nhân trong lãnh thổ HQ" (ASR_… §B2)
           → không có ADR. Đây là ràng buộc pháp lý (CON-05), không được bỏ qua.
        3. SEC chưa tồn tại → AG2 yêu cầu Security ký. Chạy /sa-2-architecture --focus sec.

        🟠 NỢ
        4. ADR-006 "dùng Redis làm cache" — §1 không tham chiếu QAS/CON nào.
           Bổ sung nguồn, hoặc hạ xuống DEC-nn nếu điểm radar < 5.
        5. CMP-07 "NotificationRelay" không phục vụ ASR nào và không có trong BACKLOG của BA.
           Rà lại: có ai cần nó không?

        🟡 CẢI THIỆN
        6. ADR-003 đang Proposed từ 2026-08-30 (18 ngày). Ai đang chờ quyết định này?

        ⚠️ TRONG BẢN NHÁP (chưa tính)
        7. ICD 🟡: 4/9 IF-nnn chưa có cột "ai sở hữu contract".

        ③ Kết luận
        AG2: 🔴 CHẶN — 3 mục. Việc gần nhất: /sa-2-architecture --focus adr
```

## Lỗi thường gặp

**"Coverage 100% nhưng vẫn có vấn đề."**
Kiểm tra chất lượng liên kết, không chỉ sự tồn tại. Một `ADR` gắn với `ASR-004` nhưng nội dung
không thực sự giải quyết `ASR-004` vẫn đếm là có liên kết. Skill báo được chỗ đứt, không thay
được việc đọc.

**"Nó chặn gate của tôi trong khi tôi đang gấp."**
Đó là mục đích. Nhưng bạn có thể **chấp nhận có ý thức**: ghi `DEC-nn` nêu rõ chấp nhận đứt
chỗ nào, ai chấp nhận, và hạn xử lý. Chấp nhận có ghi chép khác hoàn toàn với bỏ qua.

**"Ma trận trống nhiều quá, nhìn nản."**
Ma trận trống trung thực tốt hơn ma trận đầy do suy diễn. Ô trống là danh sách việc; ô điền
bừa là cảm giác an toàn giả.

**"CMP-07 không phục vụ ASR nào nhưng nó cần thật."**
Hợp lệ — không phải component nào cũng sinh từ `ASR`. Ghi vào `SAD` §4.1 nguồn của nó (một
`US` trong `BACKLOG` của BA chẳng hạn) và skill sẽ ngừng báo.

## Liên quan

- Quan hệ phụ thuộc giữa artifact: `../sa-lifecycle/references/artifact-map.md` §6
- Tiêu chí gate: `../sa-lifecycle/references/workflow.md` §2
- Chấm điểm ADR: `../sa-lifecycle/references/decision-radar.md` §2
- Bộ BA tương ứng: `../ba-traceability/GUIDE.md`
- Template: `templates/decision-traceability-matrix.md` · `templates/adr-ledger.md`