init git

.claude/skills/sa-4-evolution/templates/architecture-review.md

@@ -0,0 +1,173 @@
+# PMR — Architecture Review / Post-mortem — <PROJECT>
+
+| | |
+|---|---|
+| **Loại** | 🔄 Đánh giá định kỳ *(ATAM rút gọn)* / 🚨 Post-mortem sau sự cố |
+| **Version** | 1.0 |
+| **Date** | YYYY-MM-DD |
+| **Author** | <SA> (skill sa-4-evolution) |
+| **Status** | 🟡 Draft |
+| **Approved by** | Tech Lead: — · EA: — |
+| **Source** | CONF_… · QAS_… · ADR-… · log sự cố … |
+| **Scope** | Kỳ … / Sự cố `INC-…` |
+| **Confidence** | 🟢 |
+
+## Change Log
+
+| Version | Date | Người sửa | Thay đổi |
+|---|---|---|---|
+| 1.0 | | | Bản đầu |
+
+---
+
+# CHẾ ĐỘ A — Đánh giá định kỳ (ATAM rút gọn)
+
+*Dùng mỗi quý. Xoá phần B nếu dùng chế độ này.*
+
+## A1. `QAS` còn đúng không
+
+*Nhu cầu đổi thì thuộc tính chất lượng cũng đổi. `QAS` viết một năm trước có thể đang bảo vệ
+thứ không ai cần nữa.*
+
+| `QAS` | Còn đúng | Lý do | Hành động |
+|---|---|---|---|
+| `QAS-001` | ✅ | | |
+| `QAS-006` | ❌ thừa | Tính năng đã bỏ | Đánh dấu `[DROPPED]`, giữ ID |
+| — | ❌ thiếu | Nhu cầu mới: … | Thêm `QAS-nnn` |
+
+## A2. Điểm nhạy cảm
+
+*Chỗ một thay đổi nhỏ làm một thuộc tính chất lượng đổi nhiều. Đây là chỗ phải cẩn thận nhất
+khi sửa, và là chỗ phải có `FIT` bảo vệ.*
+
+| # | Điểm | Thuộc tính bị ảnh hưởng | Thay đổi nhỏ nào cũng gây tác động lớn | Có `FIT` bảo vệ |
+|---|---|---|---|---|
+| 1 | | `QAS-nnn` | | ☐ |
+
+## A3. Điểm đánh đổi
+
+*Chỗ cải thiện thuộc tính này làm hỏng thuộc tính kia. Phải được nói ra để người sau không
+"tối ưu" một chiều rồi phá chiều còn lại.*
+
+| # | Điểm | Cải thiện | Đánh đổi bằng | Cân bằng hiện tại | Ai quyết |
+|---|---|---|---|---|---|
+| 1 | | `QAS-nnn` | `QAS-nnn` | | PO |
+
+## A4. `ADR` chạm điều kiện xét lại
+
+| `ADR` | Điều kiện (§7 của ADR) | Ngưỡng | Thực tế | Chạm chưa | Hành động |
+|---|---|---|---|---|---|
+
+## A5. Rủi ro mới
+
+| Nguồn | Rủi ro | Mức | Hành động | `ARISK` |
+|---|---|---|---|---|
+| Vendor | *(đổi giá, đổi điều khoản, ngừng dịch vụ)* | | | |
+| Vòng đời công nghệ | *(phiên bản hết hỗ trợ, thư viện ngừng bảo trì)* | | | |
+| Tuân thủ | *(luật mới, chuẩn kiểm toán mới)* | | | |
+| Nhân sự | *(người duy nhất biết một phần hệ thống)* | | | |
+| Quy mô | *(tải sắp vượt ngưỡng thiết kế)* | | | |
+
+## A6. Kết luận định kỳ
+
+| | |
+|---|---|
+| **Kiến trúc còn phù hợp không** | ✅ còn / ⚠️ còn nhưng có điểm phải xử lý / ❌ cần vòng thiết kế mới |
+| **Ba việc quan trọng nhất** | ⟶ `TRM` |
+| **Có cần mở vòng `sa-1-context` mới không** | ☐ · vì sao |
+
+---
+
+# CHẾ ĐỘ B — Post-mortem kiến trúc sau sự cố
+
+*Chỉ cho sự cố có nguyên nhân kiến trúc. Post-mortem vận hành (dòng thời gian, cách xử lý,
+hành động khắc phục ngay) thuộc SRE — tài liệu này không lặp lại phần đó. Xoá phần A nếu dùng
+chế độ này.*
+
+## B1. Tham chiếu
+
+| | |
+|---|---|
+| **Sự cố** | `INC-…` |
+| **Post-mortem vận hành** | *(đường dẫn — đọc trước tài liệu này)* |
+| **Ảnh hưởng** | … phút · … người dùng · … giao dịch |
+| **Ngân sách lỗi tiêu tốn** | … / … phút của tháng |
+
+## B2. Ba câu hỏi kiến trúc
+
+> 🔴 **Không đổ lỗi cho người.** "Dev quên đặt timeout" là triệu chứng. Câu hỏi kiến trúc là
+> "vì sao hệ thống cho phép một lời gọi không timeout tồn tại, và làm sao để lần sau không
+> thể". Câu trả lời thường là một `FIT` mới, không phải một lời nhắc nhở.
+
+### Câu 1 — Kiến trúc đã CHO PHÉP sự cố này ở chỗ nào
+
+| Điều kiện cho phép | Ở đâu | Có trong thiết kế không |
+|---|---|---|
+| | `SAD` §… / `FAIL` `FM-nn` / không có ở đâu cả | |
+
+### Câu 2 — Thiết kế đã dự đoán tình huống này chưa
+
+| | |
+|---|---|
+| **Có trong `FAIL` không** | ☐ có (`FM-nn`) — vậy vì sao biện pháp không hiệu lực? · ☐ không — đây là điểm mù |
+| **Có `QAS` liên quan không** | |
+| **Có `ASM` nào sai không** | `ASM-nn`: … |
+
+**Nếu ĐÃ có trong thiết kế mà vẫn xảy ra** — vấn đề nằm ở một trong ba:
+
+| | Kiểm |
+|---|---|
+| Biện pháp không được cài đặt | ☐ |
+| Cài đặt nhưng tham số sai *(timeout, ngưỡng)* | ☐ |
+| Cài đặt đúng nhưng không đủ *(giả định về quy mô sai)* | ☐ |
+
+### Câu 3 — Sửa ở tầng nào
+
+| Tầng | Sửa gì | Ngăn được lần sau | Chi phí | Chọn |
+|---|---|---|---|---|
+| Code | | chỉ chỗ này | | ☐ |
+| Cấu hình | | chỉ chỗ này | | ☐ |
+| **Kiến trúc** | | cả lớp vấn đề | | ☐ |
+| Quy trình / bài kiểm tự động | | cả lớp vấn đề, không phụ thuộc trí nhớ | | ☐ |
+
+🔴 **Sửa ở tầng code chỉ ngăn được đúng lần này.** Hỏi thêm: *"Còn bao nhiêu chỗ khác trong hệ
+thống có cùng vấn đề?"* — nếu > 1 thì phải sửa ở tầng kiến trúc hoặc bài kiểm.
+
+## B3. Chỗ khác có cùng vấn đề
+
+| Chỗ | Đã kiểm | Có cùng vấn đề | Xử lý |
+|---|---|---|---|
+
+## B4. Hành động
+
+| # | Hành động | Tầng | Chủ | Hạn | Ngăn được gì | Ghi ở đâu |
+|---|---|---|---|---|---|---|
+| 1 | | `FIT` mới | | | cả lớp lỗi này | `FIT-nn` |
+| 2 | | `ADR` mới | | | | `ADR-nnn` |
+| 3 | | cập nhật `FAIL` | | | | `FM-nn` |
+
+## B5. Cập nhật tài liệu
+
+| Tài liệu | Cập nhật gì | Đã làm |
+|---|---|---|
+| `FAIL` | Thêm `FM-nn` cho tình huống này | ☐ |
+| `QAS` | Thêm `QAS-nnn` về thời gian phát hiện | ☐ |
+| `ADR-nnn` | Bổ sung hệ quả chưa lường trước vào §5 | ☐ |
+| `ASM` | Sửa giả định sai, rà mọi thứ dựa trên nó | ☐ |
+| `AGD` | Thêm ràng buộc | ☐ |
+
+*Không sửa quyết định trong `ADR` cũ — chỉ bổ sung hệ quả quan sát được. Quyết định sai ⇒ ADR
+mới có `Supersedes:`.*
+
+---
+
+## Bài học *(cả hai chế độ)*
+
+| Bài học | Áp dụng vào | Ai chịu trách nhiệm |
+|---|---|---|
+| | dự án này / dự án sau / chuẩn chung của tổ chức | |
+
+## Open Questions
+
+| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì |
+|---|---|---|---|---|

.claude/skills/sa-4-evolution/templates/conformance-report.md

@@ -0,0 +1,163 @@
+# CONF — Architecture Conformance Report — <PROJECT> · kỳ <YYYY-MM>
+
+| | |
+|---|---|
+| **Version** | 1.0 |
+| **Date** | YYYY-MM-DD |
+| **Author** | <SA> (skill sa-4-evolution) |
+| **Status** | 🟡 Draft |
+| **Approved by** | PO: — · SRE: — · EA: — |
+| **Source** | QAS_… v1.1 · TCO_… v1.0 · INF_… v1.0 · hoá đơn … · dashboard … · log sự cố … |
+| **Scope** | Kỳ … |
+| **Confidence** | 🟢 *(số đo thật)* / 🟡 *(một phần ước lượng)* |
+
+## Change Log
+
+| Version | Date | Người sửa | Thay đổi |
+|---|---|---|---|
+| 1.0 | | | Bản đầu |
+
+> Mỗi kỳ một file, **không ghi đè kỳ trước**. So sánh giữa các kỳ là nơi xu hướng lộ ra.
+
+---
+
+## 1. Tóm tắt
+
+| | Đạt | Không đạt | **Chưa đo được** |
+|---|---|---|---|
+| `QAS` mức Must | | | |
+| `QAS` mức Should | | | |
+
+| | Ước lượng | Thực tế | Chênh |
+|---|---|---|---|
+| Chi phí hạ tầng/tháng | | | % |
+
+| | Số |
+|---|---|
+| Sự cố trong kỳ | |
+| — truy về một `ADR` | |
+| — truy về một `ASM` sai | |
+| — **điểm mù mới** | |
+| Drift phát hiện được | |
+
+**Ba việc cần xử lý trước:** … *(dẫn sang `TRM`)*
+
+---
+
+## 2. `QAS` × telemetry thật
+
+| `QAS` | Mục tiêu | Đo được | Nguồn đo | Kết quả | Ghi chú / `TD` |
+|---|---|---|---|---|---|
+| `QAS-001` | p95 ≤ 300ms | | Grafana … | ✅ / ❌ / ⚠️ | |
+| `QAS-004` | ≤ 45 phút | | | | |
+
+**Ký hiệu:** ✅ đạt · ❌ không đạt · ⚠️ **chưa đo được**
+
+🔴 **⚠️ không nhẹ hơn ❌ — nó nặng hơn.** ❌ nghĩa là ta biết mình đang ở đâu; ⚠️ nghĩa là ta
+không biết gì cả. Mỗi mục ⚠️ phải ghi rõ vì sao chưa đo được:
+
+| `QAS` | Vì sao chưa đo được | Cần gì để đo được | Vào `TRM` |
+|---|---|---|---|
+| | cách đo ở AG2 không khả thi / thiếu observability / chưa có bài đo | | ☐ |
+
+**Xu hướng so với kỳ trước**
+
+| `QAS` | Kỳ trước | Kỳ này | Xu hướng |
+|---|---|---|---|
+| | | | ↗ xấu đi · → ổn định · ↘ tốt lên |
+
+## 3. `TCO` × hoá đơn thật
+
+| Hạng mục | Ước lượng | Thực tế | Chênh | Giải thích |
+|---|---|---|---|---|
+| Compute | | | % | |
+| CSDL | | | | |
+| Cache | | | | |
+| Lưu trữ | | | | |
+| Message broker | | | | |
+| **Egress** | | | | |
+| Observability | | | | |
+| Non-prod | | | | |
+| **Tổng** | | | % | |
+
+**Chênh lệch > 20% — truy nguyên** *(phải thuộc một trong bốn loại)*
+
+| Hạng mục | Chênh | Loại nguyên nhân | Chi tiết | Hành động |
+|---|---|---|---|---|
+| | | ① tải khác dự kiến · ② cấu hình khác thiết kế · ③ bỏ sót khi ước lượng · ④ đơn giá đổi | | |
+
+🔴 **Không thuộc bốn loại trên ⇒ đang có thứ gì đó chạy mà không ai biết.** Đây là phát hiện
+nghiêm trọng, không phải chuyện kế toán.
+
+**Chi phí trên đơn vị nghiệp vụ** *(chỉ số này ổn định hơn tổng chi phí)*
+
+| | Kỳ trước | Kỳ này |
+|---|---|---|
+| Chi phí / 1.000 giao dịch | | |
+| Chi phí / người dùng hoạt động | | |
+
+## 4. Sự cố × quyết định kiến trúc
+
+| Sự cố | Ngày | Ảnh hưởng | Truy về | Chi tiết | Hành động |
+|---|---|---|---|---|---|
+| `INC-…` | | … phút downtime | `ADR-nnn` | Hệ quả đã ghi trong ADR §5 | Không cần đổi |
+| `INC-…` | | | `ASM-nn` **sai** | Giả định "…" không đúng thực tế | Sửa `ASM`, rà mọi thứ dựa trên nó |
+| `INC-…` | | | 🔴 **điểm mù mới** | Không tài liệu nào nói tới | Thêm `QAS-nnn` + `FM-nn` + `FIT-nn` |
+
+🔴 **Điểm mù mới là phát hiện có giá trị nhất của cả báo cáo.** Nó là thứ không ai nghĩ tới —
+và bây giờ đã nghĩ tới. Ghi kỹ, đừng gộp vào các dòng khác.
+
+**Ngân sách lỗi**
+
+| `QAS` sẵn sàng | Ngân sách/tháng | Đã dùng | Còn lại |
+|---|---|---|---|
+| `QAS-007` 99.9% | 43 phút | | |
+
+Dùng hết ngân sách lỗi ⇒ dừng phát hành tính năng mới, ưu tiên ổn định. Quy tắc này ai chốt: …
+
+## 5. Drift — thiết kế × đang chạy
+
+| # | Loại drift | Phát hiện bằng | Chi tiết | Mức | Hành động |
+|---|---|---|---|---|---|
+| 1 | `FIT` đỏ hoặc bị tắt | lịch sử CI | | | |
+| 2 | Component có trong code, không có trong `SAD` | so repo/deployment | | | Cập nhật `SAD` hoặc gỡ bỏ |
+| 3 | Interface đang gọi, không có trong `ICD` | **trace/log** | | | |
+| 4 | Cấu hình khác `INF` | so IaC thật | | | |
+| 5 | Whitelist `FIT` quá hạn | `FIT` §3 | | | |
+| 6 | `TD` quá hạn xét lại | `TDEBT` | | | |
+
+🔴 **Loại 3 phải tìm bằng trace/log, không bằng đọc code.** Lời gọi phát sinh lúc chạy (qua
+cấu hình, plugin, job định kỳ) không lộ ra khi đọc code tĩnh.
+
+**Kết luận về drift:** kiến trúc đang chạy *(còn khớp thiết kế / đã trôi ở …)*
+
+## 6. `ADR` cần xem lại
+
+| `ADR` | Điều kiện xét lại (§7 của ADR) | Đã chạm ngưỡng | Hành động |
+|---|---|---|---|
+| `ADR-nnn` | thông lượng vượt … | ☐ | |
+
+| `ADR` | Bị thực tế bác bỏ ở đâu | ADR thay thế |
+|---|---|---|
+| | | `ADR-nnn` |
+
+*Không sửa nội dung `ADR` cũ. Viết ADR mới có `Supersedes:`.*
+
+## 7. Bài học kỳ này
+
+| Bài học | Sinh từ | Áp dụng vào đâu |
+|---|---|---|
+| | sự cố / drift / chênh lệch chi phí | `AGD` / `FIT` / quy trình / dự án sau |
+
+## 8. Đề xuất cho `TRM`
+
+*Xếp theo lợi ích/chi phí. **Không xếp thứ tự ưu tiên thay PO** — trình bảng, PO xếp.*
+
+| # | Việc | Chi phí | Lợi ích *(bằng số)* | Rủi ro nếu không làm | Sinh từ |
+|---|---|---|---|---|---|
+| 1 | | … ngày công | … /tháng | | §3 |
+
+## 9. Open Questions
+
+| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì |
+|---|---|---|---|---|

.claude/skills/sa-4-evolution/templates/technical-roadmap.md

@@ -0,0 +1,137 @@
+# TRM — Technical Roadmap & Migration Plan — <PROJECT>
+
+| | |
+|---|---|
+| **Version** | 1.0 |
+| **Date** | YYYY-MM-DD |
+| **Author** | <SA> (skill sa-4-evolution) |
+| **Status** | 🟡 Draft |
+| **Approved by** | PO: — · Tech Lead: — |
+| **Source** | CONF_…_YYYY-MM · TDEBT_… · ARISK_… · PMR_… |
+| **Scope** | Kỳ kế hoạch: … |
+| **Confidence** | 🟡 |
+
+## Change Log
+
+| Version | Date | Người sửa | Thay đổi |
+|---|---|---|---|
+| 1.0 | | | Bản đầu |
+
+> 🔴 **Mỗi mục phải có lợi ích bằng số theo ngôn ngữ PO**: giảm bao nhiêu tiền/tháng, nhanh
+> hơn bao nhiêu ngày mỗi tính năng, giảm bao nhiêu sự cố. Roadmap toàn danh từ kỹ thuật
+> ("tái cấu trúc module X") sẽ không được duyệt, và đúng như vậy.
+
+---
+
+## 1. Bảng trình PO — xếp thứ tự
+
+| # | Việc | Vấn đề nó giải quyết | Chi phí | **Lợi ích/tháng** | Hoà vốn | Rủi ro nếu không làm | Nguồn | PO xếp |
+|---|---|---|---|---|---|---|---|---|
+| 1 | | | … ngày công | … tiền / … ngày công | … tháng | | `CONF` §3 | |
+| 2 | | | | | | | `TDEBT` `TD-05` | |
+
+**Ràng buộc, không phải lựa chọn** *(SA nêu rõ — PO không xếp thứ tự những mục này)*
+
+| Việc | Vì sao là ràng buộc | Hạn cứng |
+|---|---|---|
+| | tuân thủ pháp lý / lỗ hổng bảo mật mức cao / công nghệ hết hỗ trợ | |
+
+## 2. Nguồn đầu vào — đã rà đủ chưa
+
+| Nguồn | Đã rà | Số mục đưa vào roadmap |
+|---|---|---|
+| `QAS` không đạt (`CONF` §2) | ☐ | |
+| `TD` mức cao, lãi suất lớn (`TDEBT` §1) | ☐ | |
+| Drift phải đóng (`CONF` §5) | ☐ | |
+| Chi phí vượt `TCO` (`CONF` §3) | ☐ | |
+| Rủi ro mới: vendor, hết vòng đời, tuân thủ | ☐ | |
+| Tải/tính năng đã biết trước trong roadmap sản phẩm | ☐ | |
+
+## 3. Chi tiết từng mục
+
+### TRM-01 — <tên>
+
+| | |
+|---|---|
+| **Vấn đề** | *(nói bằng hệ quả, không bằng kỹ thuật)* |
+| **Bằng chứng** | `CONF` §… · số đo · hoá đơn |
+| **Phương án đề xuất** | |
+| **Phương án khác đã cân nhắc** | *(quy tắc `D3` vẫn áp dụng)* |
+| **Chi phí** | … ngày công · … chi phí hạ tầng phát sinh |
+| **Lợi ích** | *(bằng số, hàng tháng)* |
+| **Rủi ro khi làm** | |
+| **Rủi ro nếu không làm** | |
+| **Phụ thuộc** | *(phải làm sau mục nào)* |
+| **Cần `ADR` mới không** | ☐ · `ADR-nnn` |
+| **Đo thế nào để biết đã xong** | *(tiêu chí nghiệm thu bằng số)* |
+
+### TRM-02 — <tên>
+
+*(cùng cấu trúc)*
+
+## 4. Phụ thuộc & thứ tự
+
+```mermaid
+flowchart LR
+```
+
+| Mục | Phải xong trước | Vì sao |
+|---|---|---|
+
+## 5. Kế hoạch migration *(nếu có mục là migration)*
+
+### 5.1 Tổng quan
+
+| | |
+|---|---|
+| **Từ** | |
+| **Sang** | |
+| **Kiểu cắt chuyển** | một lần / song song hai hệ thống / cuốn chiếu theo nhóm |
+| **Thời lượng dự kiến** | |
+| **Cửa sổ cắt chuyển** | |
+
+### 5.2 Các bước
+
+| Bước | Việc | Tiêu chí đi tiếp | **Cách rollback ở bước này** | Thời lượng | Chủ |
+|---|---|---|---|---|---|
+| 1 | | | | | |
+| 2 | | | | | |
+
+🔴 **Mỗi bước phải rollback được độc lập.** Kế hoạch chỉ rollback được ở bước cuối là kế hoạch
+một chiều — bước 3 hỏng thì không có đường lui.
+
+### 5.3 Chạy song song
+
+| | |
+|---|---|
+| Hai hệ thống chạy song song bao lâu | |
+| Nguồn sự thật trong thời gian đó | *(chỉ một — xem `DAT` §1)* |
+| Cách đối chiếu dữ liệu hai bên | *(truy vấn nào, tần suất nào)* |
+| Ngưỡng chênh lệch chấp nhận được | |
+| Ai quyết định cắt hẳn | |
+
+### 5.4 Tiêu chí hoàn tất
+
+| Tiêu chí | Đo bằng | Ngưỡng |
+|---|---|---|
+
+## 6. Việc KHÔNG làm trong kỳ này
+
+*Ghi ra để không ai tưởng nó đang được xử lý.*
+
+| Việc | Vì sao hoãn | Xét lại khi nào | Rủi ro chấp nhận trong lúc chờ |
+|---|---|---|---|
+
+## 7. Theo dõi
+
+| Mục | Trạng thái | % hoàn thành | Lợi ích đo được thực tế | So với dự kiến |
+|---|---|---|---|---|
+| TRM-01 | chưa bắt đầu / đang làm / xong | | | |
+
+*Cột "lợi ích đo được thực tế" là cột làm cho roadmap kỳ sau được tin. Không đo lại thì lần
+sau PO không có lý do gì để duyệt.*
+
+## 8. Open Questions
+
+| ID | Câu hỏi | Hỏi ai | Từ ngày | Chặn gì |
+|---|---|---|---|---|