sys-analysis-design/.claude/skills/sad-pipeline/SKILL.md

name, description

name	description
sad-pipeline	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.
   • 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ì.