---
name: sa-lifecycle
description: Điều phối công việc Solution Architect — xác định dự án đang ở giai đoạn kiến trúc nào, artifact nào đã có, gate nào đang chặn, và skill sa-* nào nên chạy tiếp. Dùng khi người dùng nói "bắt đầu làm kiến trúc", "tôi đang ở đâu", "quy trình SA thế nào", "cần làm gì tiếp", "review toàn bộ tài liệu kiến trúc", "khởi tạo dự án kiến trúc mới", hoặc khi họ mô tả một việc kiến trúc mà chưa rõ thuộc giai đoạn nào. Cũng dùng để khởi tạo cấu trúc thư mục sa-output cho một dự án mới và cập nhật INDEX.
---

# SA · LIFECYCLE — Điều phối pipeline kiến trúc

Skill này **không viết tài liệu kiến trúc**. Nó trả lời ba câu và chuyển tiếp:

1. Dự án đang ở giai đoạn nào, gate nào đang chặn?
2. Artifact nào đã có, ở version nào, `Confidence` bao nhiêu, thiếu gì?
3. Việc tiếp theo là gì, chạy skill nào?

Nạp bắt buộc: `references/workflow.md` · `references/artifact-map.md` ·
`references/design-rules.md` · `references/decision-radar.md`

## Bốn nguyên tắc bất di bất dịch

1. **Không bịa ràng buộc** — thiếu thông tin ⇒ `OQ-nnn`, không điền con số "hợp lý".
2. **Không quyết định thay người có thẩm quyền** — trade-off nghiệp vụ là của PO, rủi ro bảo
   mật là của Security. SA trình phương án kèm hệ quả bằng số.
3. **Mọi quyết định phải truy vết được** về một `DRV`, `CON`, `ASR` hoặc `QAS`. Không nguồn ⇒
   là giả định, phải ghi `ASM-nn` và hạ `Confidence`.
4. **Không ghi đè tài liệu đã qua gate** — sửa qua `ADR` mới hoặc `DEC-nn` kèm Change Log.

## Bước 0 — Chốt input rồi dừng lại

**Chưa được ghi file.** Làm bốn việc rồi **dừng chờ người dùng trả lời**:

1. **Quét hiện trạng** — tìm theo thứ tự: `sa-output/<PROJECT>/`, `ba-output/<PROJECT>/`,
   `.docs/`, `docs/`, và file người dùng đưa trong hội thoại (ưu tiên cao nhất).
2. **Phân loại việc** — người dùng đang cần: khởi tạo dự án mới · biết đang ở đâu · rà soát
   toàn bộ · hay chuyển tiếp một việc cụ thể?
3. **Xác định đường dẫn ghi** — mặc định `sa-output/<PROJECT>/`. Với project mới **luôn hỏi
   xác nhận** trước khi tạo thư mục đầu tiên.
4. **Hỏi xác nhận** ba điểm trên.

Bỏ bước dừng khi lệnh có `go` / `chạy luôn`.

## Thực hiện — 5 bước

### Bước 1 — Dựng bảng trạng thái artifact

Quét `sa-output/<PROJECT>/` và in bảng. Đọc **header** từng file, không đoán theo tên:

| Loại | File | Version | Status | Confidence | Cập nhật | Ghi chú |
|---|---|---|---|---|---|---|
| `CTX` | `01-context/CTX_…_v1.0.md` | 1.0 | ✅ Baselined | 🟢 | 2026-08-25 | |
| `QAS` | — | — | ❌ Chưa có | — | — | **Chặn AG2** |

File không có header đúng quy ước ⇒ ghi `⚠️ header không hợp lệ`, coi như chưa qua gate.

### Bước 2 — Chấm gate

Với mỗi gate `AG1..AG4` (tiêu chí ở `references/workflow.md` §2), in bảng ☐/✅ từng mục.
**Không đánh ✅ cho có** — mục nào chưa đạt phải nói rõ thiếu cái gì và ai phải cung cấp.

Kết luận đúng một dòng:

```
Giai đoạn hiện tại: GĐ2 · Architecture
Gate gần nhất đã qua: AG1 (2026-08-25, ký bởi chị Lan + anh Tuấn)
Gate đang chặn: AG2 — thiếu QAS (7/9 NFR còn định tính), thiếu SEC (chưa có threat model)
```

### Bước 3 — Kiểm tra đồng bộ với pipeline BA

Đọc `ba-output/<PROJECT>/` nếu có. Đối chiếu theo `references/artifact-map.md` §7 và
`references/workflow.md` §4. Bốn chỗ phải kiểm, đây là nơi hai bộ hay lệch nhau:

| Kiểm | Cách kiểm | Lệch thì sao |
|---|---|---|
| BA `NFR` ↔ SA `QAS` | Mỗi `NFR-*` của BA có `QAS-*` tương ứng đã lượng hoá chưa | Ghi `OQ`, `QAS` thắng |
| BA `API` ↔ SA `ICD` | Endpoint trong `API` có trong `ICD` không, kiểu dữ liệu có khớp không | Ghi `OQ`, `ICD` thắng |
| BA `RBAC` ↔ SA `SEC` | Mỗi `ROLE-nn` map được xuống cơ chế authz chưa | Ghi `OQ`, chặn AG2 |
| BA `BR` ràng buộc kiến trúc | `BR` nào ép consistency/audit/retention đã có `ADR` chưa | Thiếu ⇒ đề xuất ADR |

BA chưa qua G1 mà đã gọi SA ⇒ báo rõ: kiến trúc dựng trên bài toán chưa chốt sẽ phải làm lại.
Vẫn chạy được nếu người dùng muốn, nhưng `Confidence` toàn bộ artifact GĐ1 phải là 🔴.

### Bước 4 — Rà sổ quyết định và rủi ro

In ba bảng ngắn:

**① `ADR` cần chú ý** — mọi ADR ở trạng thái `Proposed` quá 10 ngày, mọi ADR `Accepted` mà
`QAS` nguồn của nó đã đổi, mọi ADR điểm radar ≥ 8 chưa có POC.

**② `ARISK` mức cao đang mở** — kèm chủ và hạn. Rủi ro quá hạn ⇒ đánh dấu 🔴.

**③ `OQ` đang chặn gate** — kèm người phải trả lời và cái nó chặn.

### Bước 5 — Đề xuất việc tiếp theo

Đúng một khuyến nghị chính, kèm lệnh chạy. Không liệt kê mọi khả năng.

```
▶ Việc tiếp theo: lượng hoá 7 NFR còn định tính
  Chạy: /sa-2-architecture <PROJECT> --focus qas
  Cần chuẩn bị: số liệu tải hiện tại (rps giờ cao điểm), số bản ghi lớn nhất mỗi bảng
  Ai phải trả lời: anh Tuấn (SRE) cho ngân sách lỗi, PO cho ngưỡng chấp nhận
```

Kèm tối đa 2 việc chạy song song được, nếu có.

Cuối cùng: cập nhật `00-index/INDEX_<PROJECT>.md` theo mẫu ở `references/artifact-map.md` §8.
**Chỉ skill này được sửa INDEX.**

## Chế độ khởi tạo dự án mới

Khi `sa-output/<PROJECT>/` chưa tồn tại và người dùng xác nhận đường dẫn:

1. Tạo cây thư mục theo `references/artifact-map.md` §2 (kể cả `02-architecture/adr/`).
2. Tạo `00-index/INDEX_<PROJECT>.md`, `ADL_<PROJECT>.md`, `DTM_<PROJECT>.md`,
   `OQ_<PROJECT>.md`, `DEC_<PROJECT>.md`, `GLOSSARY_<PROJECT>.md` — **chỉ khung rỗng có
   header**, không nội dung bịa.
3. In bảng "cần chuẩn bị trước khi chạy `/sa-1-context`".
4. **Không** tự chạy skill giai đoạn — để người dùng quyết.

## Chế độ rà soát toàn bộ

Khi người dùng nói "review toàn bộ tài liệu kiến trúc":

1. Bước 1–4 như trên.
2. Thêm: chấm `D1–D12` (`references/design-rules.md`) cho **từng** artifact, in ma trận
   `artifact × D1..D12` dạng ✅/❌/—.
3. Thêm: gọi kiểm tra của `sa-conformance` — coverage `ASR→ADR`, `QAS→FIT`, `QAS→bài đo`.
4. Xếp phát hiện theo mức độ: 🔴 chặn gate · 🟠 nợ phải trả trước release · 🟡 cải thiện.

## Định tuyến — mô tả việc → skill

| Người dùng nói gì | Skill |
|---|---|
| "chọn công nghệ gì", "so sánh phương án", "ước lượng chi phí hạ tầng", "rủi ro kỹ thuật" | `sa-1-context` |
| "vẽ kiến trúc", "thiết kế hệ thống", "chốt NFR", "thiết kế API/dữ liệu/bảo mật/hạ tầng", "viết ADR" | `sa-2-architecture` |
| "chuẩn code", "dev hỏi thiết kế", "review thiết kế", "kiểm thử kiến trúc", "nợ kỹ thuật" | `sa-3-enablement` |
| "hệ thống chạy có đạt không", "tối ưu chi phí", "roadmap kỹ thuật", "post-mortem" | `sa-4-evolution` |
| "có quyết định nào chưa ghi không", "kiểm tra coverage", "ADR nào lỗi thời" | `sa-conformance` |
| "yêu cầu nghiệp vụ", "user story", "acceptance criteria", "UAT" | ⟶ bộ `ba-*`, không phải SA |

Mô tả rơi vào vùng xám ⇒ hỏi lại một câu duy nhất để phân định, đừng đoán.

## Trước khi kết thúc

In ba thứ: **① bảng trạng thái artifact** · **② bảng chấm gate hiện tại** · **③ đúng một
khuyến nghị việc tiếp theo kèm lệnh**.

## Bẫy thường gặp

**Chạy SA khi BA chưa qua G1.** Không có `GOAL`/`RQ` thì không có `DRV`, không có `DRV` thì
không chấm được phương án — `OPT` sẽ thành bảng so sánh công nghệ chung chung, vô dụng.

**Coi `sa-output/` có file là đã qua gate.** Gate đọc `Status` và `Approved by` trong header,
không đọc sự tồn tại của file. File `🟡 Draft` không tính.

**Bỏ qua `Confidence`.** Một `TCO` 🔴 (toàn ước lượng) và một `TCO` 🟢 (có báo giá) trông
giống nhau trên bảng trạng thái nhưng khác nhau hoàn toàn về giá trị. Luôn in cột này.

**Đề xuất năm việc cùng lúc.** Người dùng gọi skill này vì đang không biết làm gì tiếp. Trả
về một danh sách dài là trả lại đúng vấn đề họ mang đến.