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

name, description

name

description

sad-proposal

Tổng hợp bộ tài liệu SAD đã hoàn thiện thành bản proposal gửi khách hàng dạng ứng dụng HTML/CSS trực quan (docs/proposal/index.html + biến thể Artifact), qua 3 stage có cổng phê duyệt — content (proposal-writer) → build (proposal-builder) → review (proposal-reviewer chống rò rỉ nội bộ, kiểm tra trung thực). Dùng khi người dùng nói "làm proposal", "đề xuất giải pháp gửi khách", "tổng hợp SAD thành proposal", "xuất proposal HTML/PDF".

Proposal từ SAD — quy trình có cổng phê duyệt

Bạn (main assistant) điều phối và làm gatekeeper. Không tự viết nội dung proposal — proposal-writer viết, proposal-builder dựng, proposal-reviewer rà. Bạn hỏi người dùng, chạy đúng stage, trình bày trung thực, và không bao giờ để tài liệu có rò rỉ nội bộ đi ra ngoài.

Engine: .claude/workflows/generate-proposal.js — gọi Workflow({ scriptPath: "<abs path>/.claude/workflows/generate-proposal.js", args: {...} }).

Tham số args

Tham số	Ý nghĩa
stage	content → build → review; all = chạy liền + 1 vòng tự sửa (chỉ khi người dùng yêu cầu)
notes	ghi chú người duyệt / findings khi chạy lại một stage
keyFacts	mảng {fact, source} lấy từ gate content, truyền cho stage review
autoFix	(all) mặc định true
sadFile, sectionsDir, briefFile, configFile, outDir	đường dẫn; mặc định docs/SAD.md, docs/sections, docs/00-project-brief.md, docs/proposal/proposal-config.md, docs/proposal

Bước 0 — Điều kiện đầu vào

1. Glob docs/SAD.md. Không có → kiểm tra docs/sections/*.md: nếu có, đề nghị chạy stage consolidate của skill sad-pipeline trước; người dùng vẫn có thể tiếp tục từ sections (writer hỗ trợ) nhưng phải được cảnh báo.
2. Grep "^status:" docs/sections/*.md. Mục nào chưa approved → liệt kê và hỏi: tiếp tục với bản chưa duyệt (proposal sẽ là bản nháp nội bộ) hay quay lại duyệt SAD trước? Ghi quyết định vào lượt trả lời.
3. Glob docs/proposal/proposal-config.md. Không có → copy proposal-config.template.md (cùng thư mục skill này) sang docs/proposal/proposal-config.md.

Bước 1 — Thu thập thông tin thương mại (không lấy từ SAD)

AskUserQuestion tối đa 4 câu/lượt, tối đa 2 lượt; không hỏi lại điều đã có trong config hoặc brief:

• Lượt 1: tên khách hàng + người liên hệ; đơn vị đề xuất + người phụ trách; ngày phát hành & hiệu lực; mô hình giá (fixed / time-and-materials / phased / omit — đề xuất omit nếu chưa có số).
• Lượt 2 (nếu cần): timeline bắt đầu/độ dài (prefill từ ràng buộc trong brief, VD "MVP 4 tháng"); đội ngũ (vai trò/số lượng); ngôn ngữ vi/en; màu thương hiệu/logo.
• Cập nhật docs/proposal/proposal-config.md bằng Edit. Câu người dùng chưa trả lời → giữ [[CẦN ĐIỀN]], không tự điền.
• Nếu pricingModel ≠ omit mà chưa có bảng chi phí → hỏi có nhập ngay không; không → để bảng trống có placeholder.

Bước 2 — Stage content (GATE P1)

1. Chạy {stage:'content'} (kèm notes nếu là lần sửa).
2. Trình bày: filesWritten, số section, placeholders (đầy đủ), excludedInternal, confidence, summary. confidence=low → nêu lý do (SAD chưa đủ/config thiếu) và khuyến nghị Sửa hoặc bổ sung config.
3. Hỏi Duyệt / Sửa (ghi chú) / Dừng. Duyệt → Edit frontmatter docs/proposal/proposal-content.md: status: draft → status: content-approved. Sửa → chạy lại content với notes. Lưu keyFacts từ gate để dùng ở bước 4.

Bước 3 — Stage build (GATE P2)

1. Chạy {stage:'build'} (kèm notes nếu sửa).
2. Trình bày: filesWritten, failedChecks (phải rỗng), placeholdersCount, mermaidBlocks, approxSizeKB, summary. Hướng dẫn mở docs/proposal/index.html bằng trình duyệt để xem.
3. Xem trực quan (khuyến nghị): publish docs/proposal/artifact.html bằng Artifact (favicon 📑, description 1 câu; Mermaid render sẵn trong Artifact). Artifact mặc định riêng tư — việc chia sẻ link cho khách là quyết định của người dùng, chỉ sau khi GATE P3 đạt.
4. Hỏi Duyệt / Sửa (ghi chú) / Dừng. failedChecks không rỗng → mặc định khuyến nghị Sửa.

Bước 4 — Stage review (GATE P3 — cổng bảo vệ khách hàng)

1. Chạy {stage:'review', keyFacts}.
2. Trình bày: verdict, leaks (từng snippet), placeholders, findings theo severity, failedFacts, canSend.
3. Định tuyến sửa (tối đa 2 vòng, sau đó dừng và báo người dùng):
   • leaks hoặc finding target=content → chạy lại content với notes = danh sách; rồi chạy lại build (nội dung đổi thì HTML phải dựng lại); rồi review.
   • chỉ finding target=html → chạy lại build với notes; rồi review.
   • placeholders còn → không phải lỗi pipeline: liệt kê để người dùng điền vào config (giá/ngày/tên) rồi chạy lại content → build → review; hoặc người dùng chấp nhận gửi bản nháp nội bộ có đánh dấu vàng.
4. Chỉ khi canSend === true mới gọi là bản gửi được. verdict=pass nhưng còn placeholder → "bản nháp chờ điền".

Bước 5 — Bàn giao

• PDF: mở docs/proposal/index.html → In → "Save as PDF" (đã có CSS in: ẩn sidebar, ngắt trang theo mục, khổ A4).
• Artifact: republish artifact.html (cùng file path → cùng URL) nếu đã sửa; nhắc rằng link mặc định riêng tư.
• Tóm tắt cuối: verdict, số leak (phải 0), số placeholder, đường dẫn 3 file, mục nào đã duyệt. Nhắc: SAD là tài liệu nội bộ, chỉ gửi proposal.

Quy tắc bắt buộc

• Không bỏ gate; stage:'all' chỉ khi người dùng nói rõ, và vẫn phải chạy/đọc review trước khi bàn giao.
• Không tự điền giá/ngày/tên; không tự sửa câu chữ proposal thay agent (trừ frontmatter trạng thái).
• Có leaks → tuyệt đối không publish/share; sửa trước.
• Báo trung thực: ok=false nghĩa là file chưa được ghi.
• Mỗi lượt kết thúc bằng tóm tắt ngắn: trạng thái 3 stage, bước kế tiếp.