# Hướng dẫn sử dụng — `sa-4-evolution` (Giai đoạn 4)

## Giai đoạn này giải quyết gì

Hệ thống đã chạy thật. Câu hỏi bây giờ không còn là "thiết kế thế nào" mà là **"kiến trúc ta
thiết kế và kiến trúc đang chạy có phải một không"**.

Đầu vào là số liệu vận hành thật. Đầu ra là **bảng đối chiếu cam kết × thực tế**, và một
roadmap kỹ thuật PO duyệt được.

**Không làm ở giai đoạn này:** thiết kế lại hệ thống (đó là vòng mới, quay về `sa-1-context`),
post-mortem vận hành (thuộc SRE — ở đây chỉ làm phần kiến trúc).

## Khi nào gọi

| Tình huống | Có nên gọi |
|---|---|
| Một tháng sau go-live | ✅ `--focus conf` — lần đối chiếu đầu tiên |
| Định kỳ hàng tháng | ✅ `--focus conf` |
| Hoá đơn cloud tăng bất thường | ✅ `--focus conf`, đọc §b trước |
| Vừa có sự cố nghiêm trọng | ✅ `--focus review` sau khi SRE xong post-mortem vận hành |
| Lập kế hoạch quý | ✅ `--focus roadmap` |
| Đánh giá kiến trúc định kỳ | ✅ `--focus review` mỗi quý |
| Cần thiết kế một hệ thống mới | ❌ `/sa-1-context` |
| Chưa có telemetry gì | ⚠️ Chạy được, nhưng `CONF` sẽ toàn "chưa đo được" — đó cũng là một phát hiện |

## Cú pháp

```
/sa-4-evolution <PROJECT> [--focus conf|roadmap|review] [--period 2026-09] [--out <path>] [go]
```

| Tham số | Ý nghĩa |
|---|---|
| `--focus conf` | Đối chiếu `QAS`/`TCO`/sự cố/drift với thực tế |
| `--focus roadmap` | Lập `TRM` từ phát hiện của `CONF` |
| `--focus review` | Đánh giá kiến trúc định kỳ hoặc post-mortem sau sự cố |
| `--period <YYYY-MM>` | Kỳ đối chiếu, mặc định tháng gần nhất |
| `go` | Bỏ bước dừng xác nhận input |

```
/sa-4-evolution Settlement --focus conf --period 2026-09
/sa-4-evolution Settlement --focus review   "sự cố INC-2026-0912: batch đối soát chạy 3 giờ, chặn báo cáo sáng"
```

## Chuẩn bị gì trước khi gọi

🔴 **Đây là giai đoạn phụ thuộc dữ liệu nhiều nhất.** Không có số thì skill chỉ in ra bảng
trống — và đó là kết luận, không phải lỗi.

| Cần | Lấy ở đâu | Dùng cho |
|---|---|---|
| Số đo p50/p95/p99 các thao tác chính | APM / dashboard | `QAS` × thực tế |
| Uptime thật + tổng downtime trong kỳ | uptime monitor | `QAS` sẵn sàng |
| Thông lượng thật, đỉnh trong kỳ | metric | `QAS` thông lượng |
| **Hoá đơn cloud chi tiết theo dịch vụ** | cổng thanh toán cloud | `TCO` × thực tế |
| Danh sách sự cố trong kỳ + nguyên nhân | log sự cố / ticket | Sự cố × `ADR` |
| Lịch sử `FIT` trên CI | CI | Drift |
| Trace/log để biết interface thật đang gọi nhau thế nào | tracing | Drift |

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

```
sa-output/<PROJECT>/04-evolution/
├── CONF_<PROJECT>_<YYYY-MM>.md   ← mỗi kỳ một file, không ghi đè
├── TRM_<PROJECT>_v1.0.md         ← roadmap, lên version
└── PMR_<PROJECT>_<YYYY-Qn>.md    ← đánh giá định kỳ
    PMR_<PROJECT>_<INC-id>.md     ← post-mortem sau sự cố
```

## Đọc bảng đối chiếu thế nào

```
QAS × thực tế · kỳ 2026-09
┌──────────┬──────────────────┬──────────────┬──────────┬─────────────────────────┐
│ QAS-001  │ p95 ≤ 300ms      │ p95 = 240ms  │ ✅ đạt   │                         │
│ QAS-004  │ batch ≤ 45 phút  │ 52 phút      │ ❌       │ TD-05 · TRM mục 1       │
│ QAS-007  │ SLA 99.9%        │ 99.94%       │ ✅ đạt   │ downtime 26/43 phút     │
│ QAS-011  │ cảnh báo ≤ 3 phút│ chưa đo được │ ⚠️       │ thiếu bài đo — bài học  │
└──────────┴──────────────────┴──────────────┴──────────┴─────────────────────────┘
```

- ✅ đạt · ❌ không đạt ⇒ vào `TRM` · ⚠️ **chưa đo được** ⇒ AG2 định nghĩa cách đo không khả
  thi, hoặc observability thiếu

⚠️ **không xấu hơn ❌.** Nó xấu hơn: ❌ ta biết mình đang ở đâu, ⚠️ ta không biết gì cả.

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

```
Bạn:    /sa-4-evolution Settlement --focus conf --period 2026-09
        Đính kèm: hoá đơn AWS tháng 9, export dashboard Grafana, log sự cố

Claude: [Bước 0]
        Input: QAS v1.1 ✅, TCO v1.0 ✅, hoá đơn AWS 09/2026, Grafana export, 3 sự cố.
        Đủ để đối chiếu QAS (8/11 mục) và TCO (đầy đủ).
        Thiếu: bài đo cho QAS-009 và QAS-011 (observability) → sẽ ghi "chưa đo được".
        Xác nhận ghi vào CONF_Settlement_2026-09.md?

Bạn:    ok

Claude: ② QAS × thực tế: 6 đạt · 2 không đạt · 3 chưa đo được

        ③ TCO × hoá đơn:
        | Compute        | ước 4,2tr | thật 4,0tr | −5%   ✅ |
        | CSDL           | ước 3,5tr | thật 3,3tr | −6%   ✅ |
        | Observability  | ước 1,0tr | thật 3,8tr | +280% 🔴 |
        | Egress         | ước 0,5tr | thật 2,1tr | +320% 🔴 |
        | Tổng           | ước 11tr  | thật 15,4tr| +40%     |

        Truy nguyên hai khoản vượt:
        - Observability: đang giữ log 90 ngày, INF §8 thiết kế 30 ngày.
          → drift cấu hình. Giảm về 30 ngày tiết kiệm ~2,5tr/tháng.
        - Egress: báo cáo tải file PDF trực tiếp từ service, không qua CDN.
          → không có trong thiết kế. Không thuộc 4 loại lý do hợp lệ ⇒ có thứ
            chạy mà thiết kế không biết. Cần xác nhận với dev.

        ④ Sự cố:
        - INC-0912 (batch 3 giờ)     → truy về QAS-004 không đạt, đã biết trước
        - INC-0918 (5xx 12 phút)     → truy về ASM-04 "API POS luôn trả trong 2s" SAI
                                       thực tế có lúc 30s ⇒ FM-02 timeout đặt quá cao
        - INC-0925 (sai số báo cáo)  → 🔴 ĐIỂM MÙ MỚI: cache không invalidate khi
                                       sửa đơn hàng cũ. DAT §7 không nói tới trường hợp này.

        Điểm mù mới là phát hiện giá trị nhất kỳ này → đề xuất QAS mới + FIT mới.

        ▶ Ba mục đầu cho TRM (PO xếp thứ tự):
        1. Giảm retention log về 30 ngày   · 0,5 ngày công · −2,5tr/tháng
        2. Đưa tải file qua CDN            · 3 ngày công   · −1,8tr/tháng
        3. Sửa chiến lược cache            · 5 ngày công   · ngăn tái diễn INC-0925
```

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

**"Không có dashboard, không đo được gì."**
Vậy kết luận của kỳ này là *"hệ thống đang chạy mà không ai biết nó chạy thế nào"* — một phát
hiện nghiêm trọng và đáng trình. Mục đầu tiên của `TRM` là dựng observability.

**"Chi phí vẫn trong ngân sách nên không cần xem."**
Trong ngân sách nhưng gấp 3 lần ước lượng nghĩa là mô hình chi phí sai — và nó sẽ sai tiếp,
lớn hơn, khi tải tăng. Truy nguyên chênh lệch kể cả khi chưa vượt.

**"Sự cố do dev quên đặt timeout, không phải lỗi kiến trúc."**
Câu hỏi kiến trúc không phải "ai quên" mà "vì sao hệ thống cho phép một lời gọi không timeout
tồn tại". Câu trả lời thường là một `FIT` mới — và nó ngăn cả lớp lỗi đó, không chỉ một lần.

**"PO không duyệt mục nào trong roadmap kỹ thuật."**
Roadmap đang viết bằng ngôn ngữ kỹ thuật. Đổi "tái cấu trúc module Order" thành "giảm 2 ngày
cho mỗi tính năng chạm Order; quý tới có 6 tính năng như vậy ⇒ tiết kiệm 12 ngày". PO duyệt
con số, không duyệt danh từ kỹ thuật.

**"ADR-005 hoá ra sai, tôi sửa lại nội dung cho đúng."**
Đừng. Viết `ADR` mới có `Supersedes: ADR-005`, đổi trạng thái bản cũ thành `Superseded by`.
Giá trị lớn nhất của ADR là ghi lại điều ta *đã tin* lúc đó — sửa đi là xoá mất bài học.

## Ra khỏi giai đoạn này khi nào

Đủ cả bốn:

1. Bảng tự chấm AG4 toàn ✅
2. **PO + SRE + EA** đã ký
3. Mọi sự cố trong kỳ đã truy về `ADR`, `ASM`, hoặc được ghi nhận là điểm mù mới
4. `TRM` đã được PO xếp thứ tự và các mục đầu đã vào backlog

Sau đó: quay lại `--focus conf` ở kỳ tiếp theo, hoặc mở vòng kiến trúc mới bằng
`/sa-1-context` nếu driver kinh doanh đã đổi.

## Liên quan

- Tiêu chí gate AG4: `../sa-lifecycle/references/workflow.md` §2
- Nhịp chạy đề xuất: `../sa-lifecycle/references/workflow.md` §7
- Vòng đời ADR: `../sa-lifecycle/references/artifact-map.md` §4
- Template: `templates/conformance-report.md` · `templates/technical-roadmap.md` ·
  `templates/architecture-review.md`