@longph2102/v-flow 1.5.0

package/skills/specify/ba-critic/examples/good/critic-report-round1.md

@@ -0,0 +1,51 @@
+# Ví dụ — BA Critic Report Round 1
+
+> Đây là mẫu output chuẩn cho BA Critic Agent khi phản biện spec.
+
+---
+
+## 📋 BA Critic Report — Round 1
+
+**Spec version reviewed**: spec.md (2026-04-15 15:30)
+**Issues found**: 4 (≥3 required ✅)
+**Verdict**: ❌ REVISE NEEDED
+
+---
+
+### Issues
+
+#### CR-001: REQ-E01 thiếu error handling path
+- **Severity**: 🔴 Critical
+- **REQ affected**: REQ-E01 (Login)
+- **Chiều phản biện**: Completeness
+- **Mô tả**: REQ-E01 chỉ mô tả happy path (login success → redirect). Thiếu hoàn toàn các error cases: invalid email format, wrong password, account locked, rate limiting.
+- **Đề xuất fix**: Tách thành REQ-E01 (success path) + REQ-E02 (invalid credentials) + REQ-E03 (account locked) + REQ-O01 (rate limit khi > 5 attempts).
+
+#### CR-002: REQ-U01 mơ hồ — "password phải đủ mạnh"
+- **Severity**: 🟡 Major
+- **REQ affected**: REQ-U01
+- **Chiều phản biện**: Ambiguity
+- **Mô tả**: "Đủ mạnh" là chủ quan, không testable. 2 developer sẽ implement khác nhau.
+- **Đề xuất fix**: Thay bằng: "Password phải có ≥8 ký tự, ≥1 uppercase, ≥1 number, ≥1 special character."
+
+#### CR-003: REQ-E03 conflict với No-Go Zone
+- **Severity**: 🔴 Critical
+- **REQ affected**: REQ-E03
+- **Chiều phản biện**: Feasibility
+- **Mô tả**: REQ-E03 yêu cầu modify `auth-service/legacy-sso.js` — file nằm trong No-Go Zone theo context.md (rủi ro Cao, "SSO integration ổn định 2 năm").
+- **Đề xuất fix**: Tạo adapter layer mới `auth-adapter.js` wrap legacy SSO, implement logic mới trong adapter.
+
+#### CR-004: REQ-S01 thiếu exit condition
+- **Severity**: 🟢 Minor
+- **REQ affected**: REQ-S01
+- **Chiều phản biện**: Testability
+- **Mô tả**: "Trong khi user đang ở trang settings, hệ thống phải auto-save mỗi 30s." Thiếu: khi nào DỪNG auto-save? Navigate away? Close tab? Session timeout?
+- **Đề xuất fix**: Thêm exit conditions: "Auto-save dừng khi user navigate khỏi trang hoặc session hết hạn."
+
+---
+
+### Summary
+- Critical: 2
+- Major: 1
+- Minor: 1
+- **Routing**: → BA Agent fix → Round 2

package/skills/specify/ba-critic/gotchas.md

@@ -0,0 +1,40 @@
+# Gotchas — BA Critic
+
+> Cập nhật liên tục khi Agent gặp bias hoặc edge case mới.
+> Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
+
+---
+
+## Anti-Patterns
+
+1. ❌ **"Specs tốt rồi" / LGTM** — KHÔNG được chấp nhận. Luôn có ≥3 issues.
+   - **Hậu quả**: Spec mơ hồ leak ra implement → costly rework.
+
+2. ❌ **Bias từ round trước** — Đọc spec mới như chưa từng đọc.
+   - **Hậu quả**: Miss issues mới do BA Agent vô tình giới thiệu khi fix issues cũ.
+
+3. ❌ **Focus nên fixing thay vì finding** — Critic Agent TÌM issues, không FIX.
+   - **Fix**: Mô tả issue + suggest hướng fix. BA Agent quyết cách fix.
+
+4. ❌ **Nitpicking wording, bỏ qua logic** — Sửa dấu chấm câu nhưng miss missing REQ.
+   - **Fix**: Sort by severity — Critical/Major trước, Minor sau.
+
+5. ❌ **Confirm bias** — "Round trước nói 3 issues, round này cũng 3 vì spec tốt hơn rồi."
+   - **Fix**: Fresh context. Đọc spec fresh, tìm issues hoàn toàn MỚI.
+
+6. ❌ **Copy issues từ blueprint** — Tìm issues generic ("cần thêm error handling") thay vì specific.
+   - **Fix**: Mỗi issue phải reference REQ-xxx + giải thích cụ thể VÌ SAO sai.
+
+7. ❌ **Quên context.md** — Review spec mà không kiểm tra No-Go Zones.
+   - **Check**: REQ-xxx có yêu cầu modify code trong No-Go Zone? → CRITICAL issue.
+
+8. ❌ **Quên constitution.md** — Spec suggest pattern khác constitution.
+   - **Check**: Architecture pattern trong spec align với constitution? Naming conventions?
+
+---
+
+## Edge Cases
+
+- ✅ Spec rất ngắn (< 5 REQs) → Vẫn phải tìm ≥3 issues. Check completeness kỹ hơn.
+- ✅ First round trên fresh spec → Focus ambiguity + completeness (thường nhiều issues nhất).
+- ✅ Round 3+ vẫn REVISE NEEDED → Escalate cho human. Ghi vào `_session.md`.

package/skills/specify/ba-critic/scripts/check-spec-quality.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# check-spec-quality.sh — Pre-scan spec.md trước khi BA Critic phản biện adversarial.
+# Usage: ./check-spec-quality.sh <spec.md_path>
+#
+# KHÔNG thay thế critic (LLM). Chỉ surface "smell" cấu trúc để critic neo ≥3 issues
+# và không tốn lượt vào lỗi hiển nhiên. Checks: counts (REQ/AC/UC), ambiguity (từ mơ hồ),
+# completeness (error path, REQ↔AC), testability (AC mơ hồ).
+
+SPEC="${1:-spec.md}"
+
+if [ ! -f "$SPEC" ]; then
+  echo "❌ File not found: $SPEC"
+  exit 1
+fi
+
+echo "🔎 Spec Quality Pre-Scan: $SPEC"
+echo "════════════════════════════════════════"
+HINTS=0   # số smell phát hiện → gợi ý cho critic (KHÔNG phải verdict)
+
+# 1. Overview counts — đếm token bằng `grep -o | wc -l` (mỗi match 1 dòng).
+echo ""
+echo "### 1. Overview"
+REQ=$(grep -oE "REQ-[A-Za-z][0-9]+" "$SPEC" | sort -u | wc -l | tr -d ' ')
+AC=$(grep -oE "\bAC-[0-9]+\b" "$SPEC" | sort -u | wc -l | tr -d ' ')
+UC=$(grep -oE "\bUC-[0-9]+\b" "$SPEC" | sort -u | wc -l | tr -d ' ')
+echo "   REQ: $REQ · AC-NN: $AC · UC: $UC"
+[ "$REQ" -eq 0 ] && echo "   ⚠️  Không thấy REQ-xxx — spec có thể chưa đặc tả requirement" && HINTS=$((HINTS+1))
+[ "$AC" -eq 0 ] && echo "   ⚠️  Không thấy mã AC-NN — Acceptance Criteria chưa đánh mã (§4)" && HINTS=$((HINTS+1))
+
+# 2. Ambiguity — từ mơ hồ (đồng bộ với '5 Chiều Phản Biện' → Ambiguity của SKILL.md).
+echo ""
+echo "### 2. Ambiguity (từ mơ hồ)"
+AMB=0
+for word in "nên" "should" "hợp lý" "dễ dùng" "user-friendly" "nhanh" "tối ưu" "linh hoạt" "đơn giản"; do
+  count=$(grep -ci "$word" "$SPEC")   # grep -c luôn in số nguyên (0 nếu không có)
+  [ "$count" -gt 0 ] && echo "   ⚠️  '$word' xuất hiện $count lần — cần định lượng/làm rõ" && AMB=$((AMB+count))
+done
+[ "$AMB" -eq 0 ] && echo "   ✅ Không thấy từ mơ hồ phổ biến"
+HINTS=$((HINTS+AMB))
+
+# 3. Completeness — có error/exception path không? (signal cho Completeness dimension)
+echo ""
+echo "### 3. Completeness"
+ERRPATH=$(grep -ciE "lỗi|error|ngoại lệ|exception|4[0-9][0-9]|5[0-9][0-9]|timeout|invalid" "$SPEC")
+if [ "$ERRPATH" -eq 0 ]; then
+  echo "   ⚠️  Không thấy đề cập error/exception path — kiểm tra REQ chỉ có happy path?"
+  HINTS=$((HINTS+1))
+else
+  echo "   ✅ Có đề cập error/exception ($ERRPATH tín hiệu)"
+fi
+# REQ↔AC: mỗi REQ nên có ≥1 AC. So sánh số đếm (heuristic, critic xác nhận ngữ nghĩa).
+if [ "$REQ" -gt 0 ] && [ "$AC" -lt "$REQ" ]; then
+  echo "   ⚠️  AC-NN ($AC) ít hơn REQ ($REQ) — có REQ chưa có acceptance criterion?"
+  HINTS=$((HINTS+1))
+fi
+
+# 4. Testability — AC mơ hồ ("đúng"/"tốt"/"hoạt động" không có expected output cụ thể).
+echo ""
+echo "### 4. Testability"
+VAGUEAC=$(grep -ciE "hoạt động đúng|hoạt động tốt|chính xác|như mong đợi|phù hợp" "$SPEC")
+if [ "$VAGUEAC" -gt 0 ]; then
+  echo "   ⚠️  $VAGUEAC tiêu chí dạng 'đúng/tốt/phù hợp' — thiếu expected output đo được?"
+  HINTS=$((HINTS+1))
+fi
+[ "$VAGUEAC" -eq 0 ] && echo "   ✅ Không thấy AC mơ hồ kiểu 'đúng/tốt'"
+
+echo ""
+echo "════════════════════════════════════════"
+echo "📊 Pre-scan hints: $HINTS"
+echo "→ Đây CHỈ là gợi ý cấu trúc. Critic vẫn phải tìm ≥3 issues (gồm ambiguity/completeness/"
+echo "  consistency/feasibility/testability) bằng phán đoán — KHÔNG dừng ở pre-scan này."
+exit 0

package/skills/specify/ba-doc-generator/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: ba-doc-generator
+description: |
+  Hỗ trợ Business Analyst tạo tài liệu BA chuyên nghiệp theo đúng template phù hợp với từng đối tượng nhận tài liệu. Nhận input là nội dung BA thô (requirement, spec, meeting notes, model...) và audience target, tự động chọn template đúng, adapt ngôn ngữ & mức độ chi tiết, rồi gen ra tài liệu hoàn chỉnh sẵn sàng gửi đi.
+
+  Sử dụng skill này bất cứ khi nào BA cần tạo tài liệu để communicate với stakeholder, khi người dùng nói "tạo tài liệu cho dev", "viết spec cho tester", "làm báo cáo cho sếp", "tạo tài liệu cho C-level", "viết hướng dẫn cho user", "gen tài liệu BA", "tạo package cho stakeholder", "viết tài liệu review", "tạo tài liệu tích hợp cho partner", "làm tài liệu compliance", "tạo brief cho PM". Luôn dùng skill này khi BA cần communicate thông tin ra bên ngoài dù người dùng không nói rõ từ "skill".
+---
+
+# BA Document Generator Skill
+
+Skill giúp BA tạo tài liệu phù hợp **từng đối tượng nhận** — đúng template, đúng ngôn ngữ, đúng mức độ chi tiết — dựa trên nội dung BA thô đầu vào.
+
+---
+
+## Quy trình thực hiện
+
+### Bước 1 — Thu thập Input
+
+Nếu người dùng chưa cung cấp đủ, hỏi lần lượt:
+
+1. **Nội dung BA thô**: requirement, spec, meeting notes, model, elicitation results...
+2. **Audience**: Đối tượng sẽ nhận tài liệu này là ai?
+3. **Mục đích**: Review / Approval / Development / Testing / Training / Audit / Integration?
+4. **Format output**: `.md` (mặc định) hay `.docx`?
+
+> Nếu audience chưa rõ, hỏi: *"Tài liệu này sẽ được gửi cho ai — developer, tester, C-level, user cuối, hay đối tác bên ngoài?"*
+
+---
+
+### Bước 2 — Xác định Template
+
+Dựa vào audience, chọn template tương ứng:
+
+| Audience | Template File | Mục đích chính |
+|----------|--------------|----------------|
+| C-level / Sponsor / Ban lãnh đạo | `references/template-clevel.md` | Quyết định, phê duyệt ngân sách |
+| Product Owner / PM | `references/template-pm.md` | Quản lý scope, timeline, risk |
+| Developer / Tech Lead | `references/template-dev.md` | Implement solution |
+| Tester / QA | `references/template-tester.md` | Viết test case, kiểm thử |
+| End User / Trainer | `references/template-user.md` | Sử dụng hệ thống, đào tạo |
+| Legal / Compliance | `references/template-compliance.md` | Audit, tuân thủ quy định |
+| Stakeholder Review | `references/template-review.md` | Review & approval chính thức |
+| External Partner / Tích hợp | `references/template-partner.md` | Tích hợp hệ thống |
+
+> **Đọc file template tương ứng** trước khi gen tài liệu để áp dụng đúng cấu trúc và nguyên tắc.
+
+---
+
+### Bước 3 — Adapt nội dung
+
+Khi gen tài liệu, luôn áp dụng các nguyên tắc adapt sau:
+
+#### Ngôn ngữ
+- **C-level / User**: Ngôn ngữ business, tránh thuật ngữ kỹ thuật, dùng ví dụ thực tế
+- **Dev / Tester**: Ngôn ngữ kỹ thuật, chính xác, có thể dùng code/pseudocode
+- **PM / PO**: Cân bằng business + technical, focus vào scope & impact
+- **Legal**: Ngôn ngữ chính thức, trích dẫn điều khoản rõ ràng, có số hiệu
+
+#### Mức độ chi tiết
+- **C-level**: High-level, 1-2 trang, bullet points ngắn gọn
+- **PM/PO**: Medium, có đủ context để ra quyết định
+- **Dev/Tester**: Deep-dive, đầy đủ edge case, rule, data type
+- **User**: Step-by-step, có screenshot placeholder, ví dụ cụ thể
+
+#### Format
+- **C-level / Review**: Slide-style hoặc executive summary
+- **Dev**: Table + code block + diagram
+- **Tester**: Bảng acceptance criteria + test scenario
+- **User**: Numbered steps + note + warning box
+
+---
+
+### Bước 4 — Gen tài liệu
+
+Tạo tài liệu theo đúng template đã chọn, điền đầy đủ nội dung từ input BA thô.
+
+Cuối tài liệu luôn thêm:
+```
+---
+📌 Ghi chú cho BA:
+- Các phần đánh dấu [TBD] cần được điền thêm thông tin
+- Các phần đánh dấu [?] cần confirm lại với stakeholder
+- Phiên bản: v0.1 — Draft
+```
+
+---
+
+### Bước 5 — Output
+
+- Mặc định: xuất `.md` inline trong chat
+- Nếu người dùng cần file `.docx`: tham khảo skill `docx` để xuất file Word
+- Hỏi người dùng: *"Bạn cần tạo thêm phiên bản cho đối tượng nào khác không?"*
+
+---
+
+## Nguyên tắc quan trọng
+
+1. **One audience, one document** — Không cố gắng viết 1 tài liệu cho nhiều audience, sẽ không phù hợp cho ai cả
+2. **Preserve BA content** — Không tự ý thay đổi nội dung requirement, chỉ thay đổi cách trình bày
+3. **Flag thông tin thiếu** — Dùng `[TBD]` khi thông tin chưa có, `[?]` khi cần confirm
+4. **Không kỹ thuật hóa với non-tech** — Khi viết cho C-level hay User, tuyệt đối không dùng jargon kỹ thuật
+5. **Không business hóa với tech** — Khi viết cho Dev/Tester, cần đủ chi tiết kỹ thuật, không được mơ hồ

package/skills/specify/ba-doc-generator/references/template-clevel.md

@@ -0,0 +1,84 @@
+# Template: Executive Summary
+> Dành cho: C-level / Sponsor / Ban lãnh đạo
+> Mục đích: Quyết định, phê duyệt, nắm bắt tổng quan
+
+---
+
+## Nguyên tắc viết cho C-level
+- Tối đa 2 trang
+- Không dùng thuật ngữ kỹ thuật
+- Focus vào: Business value, ROI, Risk, Decision cần làm
+- Dùng số liệu cụ thể khi có thể
+- Mỗi bullet point tối đa 1-2 dòng
+- Kết thúc bằng câu hỏi / action item rõ ràng
+
+---
+
+## CẤU TRÚC TÀI LIỆU
+
+```
+# [Tên dự án / Tính năng / Thay đổi]
+**Ngày**: [Date] | **Chuẩn bị bởi**: [BA Name] | **Phiên bản**: [v0.1]
+
+---
+
+## 1. Tóm tắt (1 đoạn, tối đa 5 câu)
+[Mô tả ngắn gọn: đang làm gì, tại sao, kỳ vọng đạt được gì]
+
+---
+
+## 2. Vấn đề hiện tại
+[Mô tả pain point bằng ngôn ngữ business, có thể kèm số liệu thiệt hại/rủi ro]
+- Vấn đề 1: ...
+- Vấn đề 2: ...
+
+---
+
+## 3. Giải pháp đề xuất
+[Mô tả giải pháp ở mức high-level, không kỹ thuật]
+- Sẽ làm gì: ...
+- Không làm gì (ngoài scope): ...
+
+---
+
+## 4. Lợi ích kỳ vọng
+| Lợi ích | Đo lường | Thời gian |
+|---------|----------|-----------|
+| [Lợi ích 1] | [KPI / metric] | [Khi nào] |
+| [Lợi ích 2] | [KPI / metric] | [Khi nào] |
+
+---
+
+## 5. Chi phí & Nguồn lực
+| Hạng mục | Ước tính |
+|----------|----------|
+| Thời gian thực hiện | [X tuần/tháng] |
+| Nhân sự | [X người] |
+| Chi phí [nếu có] | [VND/USD] |
+
+---
+
+## 6. Rủi ro chính
+| Rủi ro | Mức độ | Biện pháp |
+|--------|--------|-----------|
+| [Rủi ro 1] | Cao/TB/Thấp | [Biện pháp xử lý] |
+
+---
+
+## 7. Lộ trình tổng quan
+[Timeline ngắn gọn dạng milestone, không chi tiết từng task]
+- [Tháng/Tuần X]: Giai đoạn 1 — [Tên]
+- [Tháng/Tuần Y]: Giai đoạn 2 — [Tên]
+- [Tháng/Tuần Z]: Go-live
+
+---
+
+## 8. Quyết định cần từ Ban lãnh đạo
+- [ ] Phê duyệt tiến hành dự án
+- [ ] Phê duyệt ngân sách: [số tiền]
+- [ ] Xác nhận ưu tiên so với các dự án khác
+- [ ] [Quyết định khác nếu có]
+
+---
+*Liên hệ: [Tên BA] — [Email] — [Phone]*
+```

package/skills/specify/ba-doc-generator/references/template-compliance.md

@@ -0,0 +1,83 @@
+# Template: Compliance & Regulatory Document
+> Dành cho: Legal / Compliance / Kiểm toán nội bộ
+> Mục đích: Audit trail, tuân thủ quy định pháp lý / nội bộ
+
+---
+
+## Nguyên tắc viết cho Legal/Compliance
+- Ngôn ngữ chính thức, chính xác, không mơ hồ
+- Trích dẫn rõ số điều, khoản của văn bản pháp lý
+- Mỗi yêu cầu compliance phải có trạng thái: Đáp ứng / Chưa đáp ứng / Không áp dụng
+- Có evidence / bằng chứng đáp ứng
+- Trace được từ requirement → thiết kế → implementation
+
+---
+
+## CẤU TRÚC TÀI LIỆU
+
+```
+# Báo cáo Tuân thủ: [Tên dự án / Tính năng]
+**Ngày**: [Date] | **Chuẩn bị bởi**: [BA/Compliance Name]
+**Phiên bản**: [v1.0] | **Phân loại**: [Nội bộ / Mật / Công khai]
+
+---
+
+## 1. Phạm vi & Mục đích
+- **Phạm vi áp dụng**: [Hệ thống / Module / Quy trình nào]
+- **Mục đích tài liệu**: [Audit / Review / Phê duyệt / Lưu trữ]
+- **Đối tượng sử dụng**: [Phòng pháp chế / Kiểm toán / Regulator...]
+
+---
+
+## 2. Văn bản pháp lý & Quy định áp dụng
+| # | Văn bản | Số hiệu | Ban hành | Điều khoản liên quan |
+|---|---------|---------|---------|---------------------|
+| 1 | [Tên luật / Nghị định] | [Số/YYYY/CP] | [Date] | Điều [X], Khoản [Y] |
+| 2 | [Chính sách nội bộ] | [Mã chính sách] | [Date] | Mục [Z] |
+
+---
+
+## 3. Ma trận Tuân thủ
+
+| # | Yêu cầu | Nguồn (Điều/Khoản) | Trạng thái | Cách đáp ứng | Evidence |
+|---|---------|-------------------|------------|-------------|----------|
+| C-01 | [Mô tả yêu cầu tuân thủ] | [Văn bản, Điều X] | ✅ Đáp ứng | [Mô tả cơ chế/tính năng đáp ứng] | [Link / Tài liệu] |
+| C-02 | [Yêu cầu 2] | | ⚠️ Một phần | [Giải thích] | |
+| C-03 | [Yêu cầu 3] | | ❌ Chưa đáp ứng | [Kế hoạch xử lý + deadline] | |
+| C-04 | [Yêu cầu 4] | | N/A | [Lý do không áp dụng] | |
+
+---
+
+## 4. Kiểm soát Dữ liệu & Bảo mật
+| Loại dữ liệu | Phân loại | Cách lưu trữ | Mã hóa | Thời gian lưu | Quyền truy cập |
+|-------------|-----------|-------------|--------|--------------|---------------|
+| [CCCD / Thông tin cá nhân] | Nhạy cảm | [Database X] | AES-256 | [X năm] | [Role có quyền] |
+| [Dữ liệu giao dịch] | Nội bộ | | | | |
+
+---
+
+## 5. Audit Trail
+Hệ thống ghi lại các hành động sau để phục vụ kiểm toán:
+| Hành động | Thông tin ghi lại | Lưu trữ bao lâu |
+|-----------|------------------|----------------|
+| [Tạo / Sửa / Xóa dữ liệu] | User, Timestamp, IP, Old value, New value | [X năm] |
+| [Đăng nhập / Đăng xuất] | User, Timestamp, IP | [X năm] |
+| [Phê duyệt / Từ chối] | User, Timestamp, Lý do | [X năm] |
+
+---
+
+## 6. Gap Analysis & Kế hoạch xử lý
+| Gap | Mức độ rủi ro | Deadline xử lý | Owner | Trạng thái |
+|-----|--------------|---------------|-------|-----------|
+| [Mô tả gap] | Cao/TB/Thấp | [Date] | [Tên] | In Progress |
+
+---
+
+## 7. Xác nhận & Phê duyệt
+| Vai trò | Họ tên | Chữ ký | Ngày |
+|---------|--------|--------|------|
+| BA soạn thảo | | | |
+| Legal review | | | |
+| Compliance Officer | | | |
+| Phê duyệt cuối | | | |
+```

package/skills/specify/ba-doc-generator/references/template-dev.md

@@ -0,0 +1,138 @@
+# Template: Technical Specification
+> Dành cho: Developer / Tech Lead
+> Mục đích: Implement solution — đủ chi tiết để code không cần hỏi thêm
+
+---
+
+## Nguyên tắc viết cho Dev/Tech Lead
+- Càng chi tiết càng tốt — ambiguity = bug
+- Có đủ: business rule, validation rule, edge case, error handling
+- Data model rõ ràng: field name, data type, constraint
+- API contract nếu liên quan tích hợp
+- Không giải thích "tại sao" quá nhiều — dev cần biết "làm gì" và "như thế nào"
+- Có thể dùng pseudocode, bảng, diagram
+
+---
+
+## CẤU TRÚC TÀI LIỆU
+
+```
+# [Tên tính năng / Module] — Technical Spec
+**Ngày**: [Date] | **BA**: [Name] | **Dev**: [Name] | **Phiên bản**: [v0.1]
+
+---
+
+## 1. Tổng quan kỹ thuật
+- Mô tả ngắn: [Tính năng này làm gì về mặt kỹ thuật]
+- Module / Service liên quan: [Tên module, microservice...]
+- Công nghệ: [Stack, framework nếu có ràng buộc]
+
+---
+
+## 2. Actors & Permissions
+| Actor/Role | Quyền | Điều kiện |
+|-----------|-------|-----------|
+| [Role 1] | Create / Read / Update / Delete | [Điều kiện nếu có] |
+| [Role 2] | Read only | |
+
+---
+
+## 3. Luồng xử lý chính (Happy Path)
+
+### [Tên luồng 1]
+```
+1. [Actor] thực hiện [action]
+2. Hệ thống kiểm tra [condition]
+3. Nếu hợp lệ → [xử lý]
+4. Lưu [data] vào [table/collection]
+5. Trả về [response]
+```
+
+### Exception Flow
+| Trường hợp | Điều kiện | Xử lý | Message hiển thị |
+|-----------|-----------|-------|-----------------|
+| [Case 1] | [Condition] | [Action] | "[Error message]" |
+
+---
+
+## 4. Business Rules & Validation
+
+### Validation Rules
+| Field | Rule | Error Message |
+|-------|------|---------------|
+| [field_name] | Required / Max length X / Format regex | "[Message]" |
+| [field_name] | Unique / FK constraint | "[Message]" |
+
+### Business Rules
+- BR-01: [Quy tắc nghiệp vụ 1 — mô tả cụ thể]
+- BR-02: [Quy tắc nghiệp vụ 2]
+- BR-03: [Công thức tính toán nếu có: field_A = field_B * field_C / 100]
+
+---
+
+## 5. Data Model
+
+### Entity: [Tên entity]
+| Field | Data Type | Required | Constraint | Mô tả |
+|-------|-----------|----------|------------|-------|
+| id | UUID | Yes | PK | |
+| [field_name] | VARCHAR(255) | Yes | Unique | [Mô tả] |
+| [field_name] | DECIMAL(15,2) | No | >= 0 | [Mô tả] |
+| created_at | TIMESTAMP | Yes | Default NOW() | |
+| status | ENUM | Yes | [ACTIVE, INACTIVE, PENDING] | |
+
+### Quan hệ
+- [Entity A] 1 — N [Entity B] qua field [foreign_key]
+- [Entity B] N — N [Entity C] qua bảng trung gian [table_name]
+
+---
+
+## 6. API Contract (nếu có)
+
+### [POST] /api/v1/[resource]
+**Request:**
+```json
+{
+  "field_1": "string",
+  "field_2": 0,
+  "field_3": true
+}
+```
+**Response 200:**
+```json
+{
+  "id": "uuid",
+  "status": "success",
+  "data": { ... }
+}
+```
+**Response 4xx/5xx:**
+| HTTP Code | Trường hợp | Message |
+|-----------|-----------|---------|
+| 400 | Validation fail | "Invalid input: [field]" |
+| 403 | Không có quyền | "Access denied" |
+| 404 | Không tìm thấy | "[Resource] not found" |
+
+---
+
+## 7. Edge Cases & Lưu ý kỹ thuật
+- [Edge case 1: mô tả + cách xử lý]
+- [Edge case 2]
+- [Performance note nếu có: query này cần index trên field X]
+- [Security note: cần sanitize input field Y]
+
+---
+
+## 8. Checklist trước khi dev bắt đầu
+- [ ] Đã đọc và hiểu toàn bộ spec
+- [ ] Các open question đã được resolve (xem mục 9)
+- [ ] Database migration script đã được plan
+- [ ] Unit test plan đã có
+
+---
+
+## 9. Open Questions cho Dev
+| # | Câu hỏi | Người trả lời | Trạng thái |
+|---|---------|--------------|-----------|
+| Q1 | [Câu hỏi kỹ thuật cần confirm] | BA / Architect | Pending |
+```