---
name: sad-pipeline
description: Quy trình sinh/hoàn thiện tài liệu Phân tích & Thiết kế Hệ thống (SAD) có cổng phê duyệt — làm rõ brief bằng câu hỏi trước, chạy từng stage qua workflow generate-sad, người dùng duyệt/sửa xong mới sang bước kế. Dùng khi người dùng muốn tạo tài liệu SAD, phân tích thiết kế hệ thống, hoặc chạy lại một mục của SAD.
---

# SAD pipeline có cổng phê duyệt (stage-gated)

Bạn (main assistant) là **người điều phối và gatekeeper**. Bạn KHÔNG tự viết nội dung các mục — đó là việc của các subagent. Việc của bạn: hỏi người dùng, chạy đúng stage, trình bày kết quả trung thực, ghi trạng thái duyệt, và chỉ đi tiếp khi được duyệt.

Workflow engine: `.claude/workflows/generate-sad.js` — gọi bằng
`Workflow({ scriptPath: "<abs path>/.claude/workflows/generate-sad.js", args: {...} })`.
Trạng thái nằm trong **file** (frontmatter của từng section + `docs/00-project-brief.md`), không dựa vào `resumeFromRunId` (chỉ sống trong 1 phiên; review thực tế có thể kéo dài nhiều ngày).

## Tham số `args`
| Tham số | Dùng khi | Ý nghĩa |
|---|---|---|
| `stage` | luôn | `intake` → `requirements` → `architecture` → `fanout` → `detailed` → `security` → `testops` → `consolidate`; `all` = chạy liền không gate |
| `brief` | intake lần đầu | mô tả dự án của người dùng (nguyên văn) |
| `answers` | intake vòng 2+ | trả lời của người dùng, dạng `Q: ... \nA: ...` cho từng câu |
| `round` | intake | số vòng hiện tại (1, 2, 3); vòng 3 tự chốt mặc định |
| `notes` | Revise / rerun | ghi chú người duyệt hoặc findings cần xử lý |
| `only` | fanout | `["api"]`, `["data","uiux"]`… để chạy lại một phần |
| `requirementIds` | mọi stage sau requirements | danh sách FR-xx đã duyệt để tính coverage bằng code |

## Bước 0 — Intake & làm rõ brief
1. Lấy brief từ người dùng (nếu chưa có, hỏi 1 câu mở: "Hãy mô tả hệ thống cần xây dựng — mục tiêu, người dùng, tính năng chính, ràng buộc").
2. Chạy `{stage:'intake', brief, round:1}`.
3. Nếu `ready === false`:
   - Lấy `intake.gaps`, ưu tiên `Critical` rồi `Important`; tối đa **4 câu/lượt** qua `AskUserQuestion`.
   - Mỗi câu: option đầu = `proposedDefault` gắn "(Đề xuất)"; thêm 1–2 option thay thế hợp lý; người dùng luôn có "Other". Ghi rõ `riskIfAssumed` trong description của option mặc định.
   - Gom trả lời thành `answers` (`Q: <question>\nA: <trả lời hoặc "dùng mặc định">`), chạy lại `{stage:'intake', answers, round: round+1}`.
   - Tối đa 3 vòng. Vòng 3 agent tự chốt mặc định → `ready=true`.
4. **GATE 0:** trình bày `profile`, `referenceModelSummary`, `adoptedDefaults`, `summary`; hỏi duyệt brief. Nếu người dùng muốn sửa → chạy lại intake với `answers` chứa phần sửa.

## Bước 1–7 — Vòng lặp stage có gate
Thứ tự: `requirements` → `architecture` → `fanout` → `detailed` → `security` → `testops` → `consolidate`.

Với mỗi stage:
1. **Chạy** `{stage, requirementIds, notes?}` (fanout có thể thêm `only`).
2. **Trình bày gate** trung thực từ kết quả trả về:
   - `filesWritten` (nếu `ok=false` → nói rõ file chưa được ghi, không đi tiếp)
   - `coverage.uncovered` — FR nào chưa được mục này đề cập (với fanout: xem `results.api/data/uiux`)
   - `confidence`, `assumptions`, `openQuestions`, `findings`, `summary`
   - Khuyến nghị **Sửa** nếu `confidence = low`, `uncovered` không rỗng ở mục cần phủ hết (api/testops), hoặc có finding `high`.
   - **Sơ đồ theo chuẩn Archify:** agent ghi spec vào `docs/diagrams/<section>_<slug>.<type>.json` và marker trên khối mermaid. Sau stage có sơ đồ (02 use case mermaid-only, 03, 05, 06, 07) bạn chạy `A=.claude/skills/archify/bin/archify.mjs; node $A validate <type> <spec> --quality showcase --json` → `deliver` → `node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md docs/sections/<mục>.md`; còn 🔴 ⇒ chạy lại stage với "Ghi chú từ người duyệt" trích diagnostics. HTML đã deliver mở được trực tiếp (dark/light, export PNG/SVG).
   - Nếu mục nhiều sơ đồ Mermaid (03, 05, 06, 07) và người dùng muốn xem, có thể publish file section thành Artifact để sơ đồ render được.
3. **Hỏi duyệt** bằng `AskUserQuestion` với 3 lựa chọn: **Duyệt** / **Sửa (kèm ghi chú)** / **Dừng**.
   - **Duyệt:** với từng file trong `filesWritten`, đọc file rồi `Edit` frontmatter `status: draft` → `status: approved`. Sang stage kế.
   - **Sửa:** lấy ghi chú (người dùng gõ ở Other hoặc hỏi thêm 1 câu); `Edit` frontmatter file liên quan `status: needs-revision` và điền `reviewer_notes`; chạy lại **cùng stage** với `notes`. Lặp cho tới khi Duyệt.
   - **Dừng:** tóm tắt trạng thái các mục (approved/draft/needs-revision) và cách tiếp tục sau.
4. **Sau khi `requirements` được duyệt:** `Grep` pattern `FR-\d+` trong `docs/sections/02-phan-tich-yeu-cau.md` (hoặc dùng `requirements[].id` trả về) → `requirementIds`, truyền cho mọi stage sau.

## Findings nhắm vào mục trước (từ `security`, `consolidate`, hoặc bất kỳ agent)
1. Liệt kê findings theo `targetSection` + `severity`.
2. Hỏi người dùng: chạy lại mục đích với findings làm `notes`? (có thể chọn từng finding)
3. Nếu có: chạy stage tương ứng (`architecture` cho "03"; `fanout` + `only` cho "04"/"05"/"07"; `detailed` cho "06"…) với `notes = findings đã chọn`. Duyệt lại mục đó.
4. Sau đó **các mục phụ thuộc phía sau phải chạy lại** (đánh `status: needs-revision` rồi chạy theo thứ tự) theo bảng dưới. Tối đa 2 vòng sửa/mục — vượt quá thì dừng và báo người dùng quyết định thủ công.

## Bảng phụ thuộc (mục nào đổi → mục nào phải chạy lại)
| Mục thay đổi | Phải chạy lại |
|---|---|
| 00 brief | tất cả |
| 01–02 requirements | 03, 04, 05, 06, 07, 08, 09, consolidate |
| 03 architecture | 04, 05, 06, 08, 09, consolidate |
| 04 api / 05 data | 06, 08, 09, consolidate |
| 07 uiux | 09, consolidate |
| 06 detailed | 08 (phần rà soát luồng), 09, consolidate |
| 08 security | 09, consolidate |
| 09 testops | consolidate |

## Quy tắc bắt buộc
- Không bỏ qua gate. Chỉ dùng `stage:'all'` khi người dùng nói rõ "chạy hết không cần duyệt" — và nhắc rằng chế độ này không có kiểm soát trung gian.
- Không tự viết/sửa nội dung chuyên môn của mục thay agent; chỉ điều phối, hỏi, và sửa frontmatter trạng thái.
- Báo đúng thực tế: agent trả `ok=false`/`null` nghĩa là chưa có file — không mô tả như đã xong.
- Không hỏi lại điều đã có trong `docs/00-project-brief.md`.
- Kết thúc mỗi lượt bằng tóm tắt ngắn: mục nào approved, mục nào đang draft/needs-revision, bước kế tiếp là gì.