spec-lite 1.0.0

package/skills/spec-prd/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: spec-prd
+description: Điền hoặc cập nhật prd.md — Product Requirements Document ở product level. Dùng khi prd.md còn là template rỗng hoặc cần review/cập nhật.
+---
+
+# spec-prd
+
+## Overview
+
+Tạo nội dung cho `specs/main/prd.md` thông qua interview có cấu trúc. PRD là nguồn sự thật ở product level — nó định nghĩa vấn đề, users, scope, và NFRs trước khi bất kỳ technical decision nào được đưa ra.
+
+PRD không chứa: tech stack, implementation details, entity schema, hay bất cứ thứ gì thuộc về `sad.md` hoặc `domain.md`.
+
+## When to Use
+
+- `specs/main/prd.md` chưa có nội dung hoặc vẫn còn là template
+- Cần bổ sung hoặc cập nhật một phần của PRD hiện tại
+- Requirements thay đổi và PRD cần được đồng bộ lại
+
+## When NOT to Use
+
+- Đang muốn thiết kế kiến trúc kỹ thuật → dùng `/spec.sad`
+- Đang muốn định nghĩa domain entities → dùng `/spec.domain`
+
+---
+
+## Process
+
+### Bước 1: Kiểm tra preconditions
+
+Đọc `specs/main/prd.md`:
+
+- **File không tồn tại** → tạo thư mục `specs/main/` (nếu chưa có) rồi tiến hành Bước 2 (full interview).
+
+- **File là template rỗng** → tiến hành Bước 2 (full interview).
+
+- **File có nội dung thực** → quét toàn bộ sections, hiển thị trạng thái từng section, rồi hỏi user muốn làm gì.
+
+  **Các sections cần quét** (theo thứ tự):
+
+  | # | Section | Có nội dung thực? |
+  | --- | --- | --- |
+  | 1 | Problem Statement | ✓ đã có / ✗ trống/thiếu |
+  | 2 | Target Users | ✓ đã có / ✗ trống/thiếu |
+  | 3 | Scope | ✓ đã có / ✗ trống/thiếu |
+  | 4 | Features | ✓ đã có / ✗ trống/thiếu |
+  | 5 | Non-Functional Requirements | ✓ đã có / ✗ trống/thiếu |
+  | 6 | Business Constraints | ✓ đã có / ✗ trống/thiếu |
+
+  Một section được coi là **trống/thiếu** nếu: không tồn tại trong file, hoặc chỉ chứa placeholder template (dấu `{}`), hoặc không có dòng nội dung thực.
+
+  Ngoài các sections thuộc template, **ghi nhận các sections thừa** — những `##` heading có trong file nhưng không có trong template.
+
+  Sau khi quét, liệt kê tất cả sections **theo đúng thứ tự xuất hiện trong file** (không tách nhóm), đánh số liên tục:
+
+  ```
+  PRD hiện tại:
+    [1] Problem Statement       ✓ đã có
+    [2] Target Users            ✓ đã có
+    [3] Scope                   ✓ đã có
+    [4] Risks                   ⚠ không có trong template
+    [5] Features                ✗ chưa có — cần bổ sung
+    [6] Non-Functional Req.     ✓ đã có
+    [7] Business Constraints    ✓ đã có
+    [A] Interview tất cả sections
+
+  Chọn số hoặc A:
+  ```
+
+  - User chọn số section thuộc template → interview section đó rồi merge vào file.
+  - User chọn số section thừa (⚠) → xoá section đó khỏi file ngay, không hỏi thêm.
+  - User chọn A → interview tuần tự tất cả sections thuộc template (sections thừa không bị đụng tới).
+
+---
+
+### Bước 2: Gather — interview requirements
+
+Trước khi hỏi, list ra các assumptions đang tạm thời:
+
+```
+ASSUMPTIONS TÔI ĐANG ĐẶT RA:
+1. Đây là dự án phần mềm (không phải hardware hay process)
+2. Target users là end users (không phải internal tools)
+→ Sửa lại nếu sai, tôi sẽ tiếp tục với các assumptions đúng.
+```
+
+Sau đó hỏi tuần tự, từng phần một — không hỏi tất cả cùng lúc:
+
+**Phần 1 — Problem Statement:**
+> Vấn đề gì đang được giải quyết? Tại sao cần giải quyết bây giờ? (2-3 câu từ góc nhìn business)
+
+**Phần 2 — Target Users:**
+> Ai là người dùng chính? Mô tả theo persona: tên vai trò, mục tiêu chính, pain point hiện tại.
+> (Có thể có nhiều persona)
+
+**Phần 3 — Scope:**
+> Hệ thống sẽ làm gì? Và quan trọng hơn — hệ thống sẽ KHÔNG làm gì (out of scope)?
+> Ghi rõ lý do cho mỗi item out of scope.
+
+**Phần 4 — Features:**
+> Hệ thống cần implement những features gì? Mỗi feature gồm: tên ngắn, mô tả 1 câu (làm gì, cho ai), priority (Must/Should/Could).
+> (Đây sẽ là Feature Index mà các FRD sau này sẽ tham chiếu.)
+
+**Phần 5 — Non-Functional Requirements:**
+> Có yêu cầu về performance, security, availability, scalability không?
+> Mỗi NFR cần: category, mô tả cụ thể, target đo được, priority (Must/Should/Could).
+
+**Phần 6 — Business Constraints:**
+> Có ràng buộc kinh doanh nào không? (deadline, budget, compliance, vendor lock-in, v.v.)
+> Có giả định nào quan trọng cần ghi lại không?
+
+Nếu câu trả lời vague → hỏi lại để làm rõ. Ví dụ:
+- "hệ thống phải nhanh" → "nhanh nghĩa là response time < bao nhiêu ms ở percentile nào?"
+- "bảo mật cao" → "có yêu cầu compliance cụ thể không? (PCI-DSS, HIPAA, ISO27001...)"
+
+---
+
+### Bước 3: Write — sinh nội dung
+
+Sau khi thu thập đủ thông tin, dùng `.claude/templates/main/prd-template.md` làm skeleton, điền nội dung từ interview vào từng section.
+
+Hiển thị draft cho user trước khi ghi file.
+
+---
+
+### Bước 4: Review — xác nhận với user
+
+Trình bày draft và hỏi:
+> Draft PRD trên đã đúng chưa? Có phần nào cần chỉnh không trước khi lưu?
+
+Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → cập nhật draft → hỏi lại.
+
+---
+
+### Bước 5: Save
+
+Ghi nội dung đã được confirm vào `specs/main/prd.md`, thay thế toàn bộ nội dung cũ.
+
+Thông báo kết quả:
+```
+✓ specs/main/prd.md đã được cập nhật (status: draft)
+
+Bước tiếp theo:
+  - /spec-domain → định nghĩa domain entities và business rules
+  - (sau domain) /spec-sad → thiết kế kiến trúc kỹ thuật
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Requirements rõ rồi, không cần hỏi nhiều" | Vague requirements tạo ra PRD vague. PRD vague tạo ra implementation sai. |
+| "NFR có thể thêm sau" | NFR ảnh hưởng đến architecture decisions. Thêm sau là refactor kiến trúc. |
+| "Out of scope thì không cần ghi" | Không ghi out of scope = scope creep không kiểm soát được. |
+| "Target users ai cũng biết rồi" | Persona chưa được viết ra là persona chưa được đồng thuận. |
+
+## Red Flags
+
+- PRD dùng từ ngữ không đo đếm được: "nhanh", "bảo mật", "dễ dùng"
+- NFRs bỏ trống hoàn toàn
+- Scope chỉ có In Scope, không có Out of Scope
+- Problem Statement viết theo góc nhìn kỹ thuật thay vì business
+
+## Verification
+
+Trước khi kết thúc, kiểm tra:
+
+- [ ] Frontmatter đầy đủ và đúng schema (id, type, version, status, owner, project_name)
+- [ ] Problem Statement từ góc nhìn business, không mention tech stack
+- [ ] Mỗi persona có: tên vai trò, mục tiêu, pain point
+- [ ] Out of Scope có ít nhất 1 item với lý do
+- [ ] Features có ít nhất 1 item, mỗi item có ID (F-XXX), tên, mô tả, priority
+- [ ] Mỗi NFR có target đo được (không phải "nhanh", "bảo mật chung chung")
+- [ ] User đã confirm trước khi file được ghi

package/skills/spec-sad/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: spec-sad
+description: Điền hoặc cập nhật sad.md — System Architecture Document (kiến trúc, tech stack, cross-cutting concerns, guardrails). Dùng sau khi prd.md và domain.md đã có nội dung.
+---
+
+# spec-sad
+
+## Overview
+
+Tạo nội dung cho `specs/main/sad.md` thông qua interview có cấu trúc. SAD là bản đồ kỹ thuật của hệ thống — nó định nghĩa các quyết định kiến trúc, tech stack, và đặc biệt là **Architectural Guardrails**: các nguyên tắc bất biến mà mọi agent phải tuân theo khi sinh `tech.md`.
+
+SAD không chứa: feature-level design, business rules, entity details — những thứ đó thuộc về `domain.md` và `fdd.md`.
+
+**Guardrails là phần quan trọng nhất của SAD.** Thiếu guardrails = agent tự quyết định tech pattern mà không có constraint.
+
+## When to Use
+
+- `sad.md` chưa có hoặc còn rỗng
+- Tech stack thay đổi đáng kể và cần cập nhật architectural decisions
+- Cần thêm guardrail mới sau khi phát hiện vấn đề trong quá trình implement
+
+## When NOT to Use
+
+- `prd.md` chưa có nội dung → chạy `/spec-prd` trước
+- Đang muốn thiết kế một feature cụ thể → dùng `/spec-fdd`
+
+---
+
+## Process
+
+### Bước 1: Kiểm tra preconditions
+
+**Đọc `specs/main/prd.md`:**
+
+- **Chưa tồn tại hoặc là template** → dừng ngay:
+  > `prd.md` chưa có nội dung. Hãy chạy `/spec-prd` trước.
+
+- **Đã có nội dung** → đọc để lấy: NFRs (performance, security, availability targets), business constraints, scope.
+
+**Đọc `specs/main/domain.md`:**
+
+- **Chưa tồn tại hoặc là template** → dừng ngay:
+  > `domain.md` chưa có nội dung. Hãy chạy `/spec-domain` trước.
+
+- **Đã có nội dung** → đọc để hiểu: các entities chính, có event-driven behavior không, volume ước tính.
+
+**Đọc `specs/main/sad.md`:**
+
+- **Chưa tồn tại** → tiến hành Bước 2 (full interview).
+
+- **Đã có nội dung thực** → quét toàn bộ sections, hiển thị trạng thái từng section, rồi hỏi user muốn làm gì.
+
+  **Các sections cần quét** (theo thứ tự):
+
+  | # | Section | Có nội dung thực? |
+  | --- | --- | --- |
+  | 1 | Architectural Style | ✓ đã có / ✗ trống/thiếu |
+  | 2 | System Overview | ✓ đã có / ✗ trống/thiếu |
+  | 3 | Tech Stack | ✓ đã có / ✗ trống/thiếu |
+  | 4 | Cross-Cutting Concerns | ✓ đã có / ✗ trống/thiếu |
+  | 5 | Inter-Service Communication | ✓ đã có / ✗ trống/thiếu |
+  | 6 | Infrastructure Overview | ✓ đã có / ✗ trống/thiếu |
+  | 7 | Architectural Guardrails | ✓ đã có / ✗ trống/thiếu |
+
+  Một section được coi là **trống/thiếu** nếu: không tồn tại trong file, hoặc chỉ chứa placeholder template (dấu `{}`), hoặc không có dòng nội dung thực. Ngoài các sections trên, **ghi nhận các sections thừa** — những `##` heading có trong file nhưng không có trong template.
+
+  Sau khi quét, liệt kê tất cả sections **theo đúng thứ tự xuất hiện trong file**, đánh số liên tục:
+
+  ```
+  sad.md hiện tại:
+    [1] Architectural Style          ✓ đã có
+    [2] System Overview              ✓ đã có
+    [3] Tech Stack                   ✓ đã có
+    [4] Cross-Cutting Concerns       ✗ chưa có — cần bổ sung
+    [5] Inter-Service Communication  ✓ đã có
+    [6] ADR Log                      ⚠ không có trong template
+    [7] Infrastructure Overview      ✓ đã có
+    [8] Architectural Guardrails     ✓ đã có
+    [A] Interview tất cả sections
+
+  Chọn số hoặc A:
+  ```
+
+  - User chọn số section thuộc template → interview section đó rồi merge vào file.
+  - User chọn số section thừa (⚠) → xoá section đó khỏi file ngay, không hỏi thêm.
+  - User chọn A → interview tuần tự tất cả sections thuộc template (sections thừa không bị đụng tới).
+
+---
+
+### Bước 2: Gather — interview có cấu trúc
+
+Tóm tắt context đọc được và surface assumptions:
+
+```
+TỪ PRD & DOMAIN TÔI HIỂU:
+- NFRs: {list NFRs từ prd — performance targets, availability, security}
+- Entities chính: {list từ domain}
+- Constraints: {business constraints từ prd}
+
+ASSUMPTIONS TÔI ĐANG ĐẶT RA:
+1. {assumption về scale, team size, v.v.}
+2. {assumption về existing infrastructure nếu có}
+→ Sửa lại nếu sai trước khi tiếp tục.
+```
+
+Hỏi tuần tự từng phần:
+
+**Phần 1 — Architectural Style:**
+> Hệ thống sẽ theo kiến trúc nào? (Monolith / Modular Monolith / Microservices / Event-driven / ...)
+> Nếu chưa quyết định, tôi có thể đề xuất dựa trên NFRs và team size — muốn không?
+
+Nếu user muốn đề xuất → đề xuất 2-3 option với trade-offs rõ ràng, để user chọn. Không quyết định thay.
+
+**Phần 2 — Tech Stack:**
+> Tech stack cho từng layer: Frontend, Backend, Database, Infrastructure?
+> Với mỗi lựa chọn: lý do chọn là gì? (performance, team familiarity, ecosystem...)
+
+Nếu user chưa quyết định layer nào → đề xuất options dựa trên NFRs và architectural style đã chọn.
+
+**Phần 3 — Cross-Cutting Concerns:**
+> Authentication & Authorization: strategy nào? (JWT, session, OAuth, API key...)
+> Error Handling: pattern nào? (global handler, error codes, retry policy...)
+> Logging & Monitoring: approach nào? (structured logging, tracing, alerting...)
+> Caching: có dùng cache không? Ở layer nào? Strategy gì?
+
+**Phần 4 — Inter-Service Communication:** *(chỉ hỏi nếu không phải monolith)*
+> Các service communicate với nhau thế nào? (REST, gRPC, message queue, events...)
+> Có service nào cần sync call vs async không?
+
+**Phần 5 — Infrastructure:**
+> Deploy ở đâu? (cloud provider, on-premise, hybrid)
+> Có bao nhiêu môi trường? (dev, staging, prod)
+> Deployment strategy: (containerized, serverless, VM...)
+
+**Phần 6 — Architectural Guardrails:** *(quan trọng nhất)*
+> Dựa trên tech stack và concerns vừa thảo luận, tôi sẽ đề xuất một bộ guardrails. Bạn review và thêm/bớt nhé.
+
+Đề xuất guardrails cụ thể dựa trên những gì đã thu thập. Ví dụ:
+- Nếu dùng ORM → `GUARD-XXX: Không dùng raw SQL, phải qua ORM`
+- Nếu có external API → `GUARD-XXX: Mọi external API call phải có retry + timeout`
+- Nếu layered architecture → `GUARD-XXX: Không để business logic trong API/controller layer`
+
+---
+
+### Bước 3: Write — sinh draft
+
+Dùng `.claude/templates/main/sad-template.md` làm skeleton, điền nội dung từ interview vào từng section.
+
+Hiển thị draft cho user xem — **chưa ghi file**.
+
+---
+
+### Bước 4: Review — xác nhận với user
+
+Trình bày draft và chú ý hỏi riêng về Guardrails:
+> Phần Architectural Guardrails có đủ và đúng không? Đây là phần agent sẽ dùng để validate mọi technical design sau này.
+
+Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → cập nhật draft → hỏi lại.
+
+---
+
+### Bước 5: Save
+
+Ghi nội dung đã được confirm vào `specs/main/sad.md`.
+
+Thông báo kết quả:
+```
+✓ specs/main/sad.md đã được cập nhật (status: draft)
+
+Bước tiếp theo:
+  - /spec-frd {feature-name} → định nghĩa requirements của từng feature
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Tech stack thì sau quyết định cũng được" | Tech stack ảnh hưởng đến guardrails. Không có guardrails = agent tự ý chọn pattern khi sinh tech.md. |
+| "Guardrails thì ghi ít thôi, ghi nhiều phức tạp" | Mỗi guardrail thiếu là một loại technical debt có thể xảy ra. Ghi đủ ngay từ đầu. |
+| "System diagram thì vẽ sau" | Diagram buộc phải nghĩ về component boundaries. Không có diagram = chưa rõ architecture. |
+| "Cross-cutting concerns thì ai cũng biết rồi" | "Auth strategy" chưa được ghi = mỗi feature tự implement theo cách riêng. |
+
+## Red Flags
+
+- Guardrails section rỗng hoặc chỉ có 1-2 item chung chung
+- Tech stack chọn mà không có lý do
+- Lý do chọn tech là "quen dùng" mà không đối chiếu với NFRs
+- System Overview không có diagram hoặc mô tả component boundaries
+- Cross-cutting concerns bỏ trống
+
+## Verification
+
+Trước khi kết thúc, kiểm tra:
+
+- [ ] Frontmatter đầy đủ và đúng schema
+- [ ] Architectural Style có lý do gắn với NFRs hoặc constraints
+- [ ] Mỗi tech stack item có lý do chọn rõ ràng
+- [ ] Tất cả 4 cross-cutting concerns đã được điền (auth, error, logging, caching)
+- [ ] Guardrails có ít nhất 3 item, mỗi item cụ thể và actionable
+- [ ] User đã confirm — đặc biệt phần Guardrails — trước khi ghi file

package/skills/spec-tech/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: spec-tech
+description: Tạo tech.md cho một integration dựa trên spec.md đã được approve. Dùng sau khi BA đã hoàn thành spec.md. Nhận slug của integration từ argument hoặc cho phép chọn từ danh sách các spec.md chưa có tech.md.
+---
+
+# spec-tech
+
+## Overview
+
+Tạo `tech.md` cho một integration trong `specs/integrations/{slug}/`.
+
+`tech.md` là technical design — định nghĩa **how to build**: solution approach, data model changes, interfaces. Phải có `spec.md` đã approve trước khi chạy skill này.
+
+## When to Use
+
+- `spec.md` đã được BA approve và DEV cần thiết kế technical design
+- Bắt đầu implement nhưng chưa có `tech.md`
+
+## When NOT to Use
+
+- `spec.md` chưa có hoặc chưa được approve → chạy `/spec-new` trước
+- `sad.md` chưa có → chạy `/spec-sad` trước (cần tech stack để đưa ra design đúng hướng)
+- Chỉ muốn cập nhật tech.md đã có → edit file trực tiếp
+
+---
+
+## Process
+
+### Bước 1: Xác định integration
+
+Quét thư mục `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `tech.md`:
+
+```
+Integrations:
+
+  [1] f001-authentication       — User Authentication
+  [2] f003-app-browsing         — App Browsing & Opt-in         ✓ có tech.md
+  [3] f004-credit-system        — Credit System
+
+Chọn số integration:
+```
+
+Nếu không có integration nào → thông báo:
+> Chưa có integration nào. Hãy chạy `/spec-new` trước.
+
+**Nếu có ARGUMENT** → đây là số thứ tự trong danh sách trên (ví dụ `1`, `2`, hoặc `001`). Parse thành số nguyên, bỏ qua leading zeros, map vào integration tương ứng — không cần hiển thị danh sách, chọn luôn.
+
+Nếu integration đã có `tech.md` → hỏi trước khi tiếp tục:
+> `tech.md` đã tồn tại cho integration này. Tiếp tục sẽ ghi đè. Tiếp tục không?
+
+---
+
+### Bước 2: Load context
+
+Load các file sau:
+
+- `specs/integrations/{slug}/spec.md` — đọc toàn bộ: Problem Statement, Requirements, Acceptance Criteria, Out of Scope
+- `specs/main/sad.md` — đọc Tech Stack và Architectural Guardrails
+- `specs/main/domain.md` — đọc Entities và Business Rules
+
+Tóm tắt context và surface assumptions:
+
+```
+TỪ SPEC & SAD TÔI HIỂU:
+- Integration: {title}
+- Yêu cầu chính: {tóm tắt requirements từ spec.md}
+- Tech stack: {từ sad.md}
+- Entities liên quan: {từ domain.md}
+- Guardrails cần tuân theo: {list GUARD-XXX từ sad.md}
+
+ASSUMPTIONS TÔI ĐANG ĐẶT RA:
+1. {assumption về approach}
+2. {assumption về dependencies}
+→ Sửa lại nếu sai trước khi tiếp tục.
+```
+
+---
+
+### Bước 3: Interview
+
+Hỏi tuần tự, từng phần — không hỏi tất cả cùng lúc:
+
+**Phần 1 — Solution Overview:**
+> Approach kỹ thuật nào sẽ dùng? Tại sao chọn approach này (so với alternatives)?
+> Nếu chưa rõ, tôi có thể đề xuất dựa trên sad.md và requirements — muốn không?
+
+Nếu user muốn đề xuất → đề xuất 2-3 options với trade-offs rõ ràng, để user chọn. Không quyết định thay.
+
+**Phần 2 — Data Model Changes:**
+> Integration này có thêm/sửa/xóa entity hoặc field nào không?
+> Nếu có, thay đổi gì và ảnh hưởng thế nào đến business rules hiện tại?
+
+Bỏ qua nếu không có data model changes.
+
+**Phần 3 — Interface Changes:**
+> Có API endpoints mới hoặc thay đổi không? Events, queue messages?
+> Với mỗi endpoint: method, path, request/response shape, auth requirement.
+
+**Phần 4 — Implementation Notes:**
+> Có điểm kỹ thuật đặc biệt nào cần lưu ý không? (edge cases, ordering constraints, known gotchas...)
+
+Bỏ qua nếu không có.
+
+Nếu câu trả lời vague → hỏi lại. Ví dụ:
+- "dùng JWT" → "JWT lưu ở đâu? expiry bao lâu? refresh token có không?"
+- "tạo bảng mới" → "fields gì? quan hệ với entity nào trong domain?"
+
+---
+
+### Bước 4: Write — sinh draft
+
+Tổng hợp và viết draft `tech.md`:
+
+**Cấu trúc file**: dùng `.claude/templates/integrations/tech-template.md` làm skeleton, điền nội dung từ interview vào.
+
+**Cascade Proposals** — điền theo hướng dẫn sau:
+
+### sad.md
+
+{Đề xuất cập nhật nếu phát hiện quyết định kiến trúc mới, tech stack thay đổi, hoặc guardrail mới cần thêm. Hoặc "Không có thay đổi đề xuất."}
+
+### domain.md
+
+{Đề xuất cập nhật nếu phát hiện entity hoặc business rule mới trong quá trình thiết kế. Hoặc "Không có thay đổi đề xuất."}
+
+### fdd.md
+
+{Một trong hai:}
+
+**Tạo mới** `specs/main/features/{feature-id}-{feature-slug}/fdd.md`
+- Dùng khi feature chưa có fdd.md
+- Thư mục theo convention: `{number}-{feature-slug}` (ví dụ: `001-authentication`)
+- Nội dung đề xuất: {tóm tắt Module Structure, Data Flow, Interfaces từ tech.md}
+
+**Cập nhật** `specs/main/features/{feature-id}-{feature-slug}/fdd.md`
+- Dùng khi fdd.md đã tồn tại, ghi rõ thay đổi cụ thể cần thêm/sửa
+
+{Hoặc "Không liên quan" nếu integration không gắn với feature cụ thể nào trong prd.md.}
+```
+
+Hiển thị draft cho user xem — **chưa ghi file**.
+
+---
+
+### Bước 5: Review — xác nhận với user
+
+> Draft trên đã đúng chưa?
+> - Technical Design có đủ để DEV implement không?
+> - Cascade Proposals (nếu có) — cần approve trước khi tiến hành.
+
+Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → cập nhật draft → hỏi lại.
+
+---
+
+### Bước 6: Save
+
+Ghi nội dung đã confirm vào `specs/integrations/{slug}/tech.md`.
+
+Thông báo kết quả:
+```
+✓ specs/integrations/{slug}/tech.md đã được tạo (status: draft)
+
+Bước tiếp theo:
+  - Review và approve tech.md
+  - Implement theo tech.md
+  - Sau khi done: đổi status F-XXX trong prd.md thành DONE
+  - Nếu Cascade Proposals có thay đổi → chạy /spec-domain hoặc /spec-sad
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Tech design thì code xong mới biết được" | Không cần design hoàn hảo, cần đủ để thống nhất approach trước khi viết code. |
+| "Interface thì ghi sau khi implement xong" | Interface chưa được agree = BA không biết integration làm gì, không thể verify AC. |
+| "Cascade Proposals thì sau cập nhật cũng được" | Domain và SAD là shared context. Cập nhật trễ = các tech.md sau dùng context sai. |
+
+## Red Flags
+
+- Solution Overview không có lý do chọn approach — chỉ mô tả "sẽ làm X" mà không giải thích tại sao
+- Interface Changes trống trong khi spec.md có AC về API/response shape
+- Data Model Changes bỏ qua nhưng spec.md có requirement về data mới
+- Cascade Proposals không được review trước khi approve
+
+## Verification
+
+Trước khi ghi file, kiểm tra:
+
+- [ ] Solution Overview có lý do chọn approach (không chỉ mô tả)
+- [ ] Mỗi Acceptance Criterion trong spec.md đều được cover bởi design
+- [ ] Interface Changes đầy đủ method, path, auth requirement (nếu có)
+- [ ] Cascade Proposals đã được user review
+- [ ] User đã confirm draft trước khi ghi file