@educa-corp/sdd-framework 0.2.4 → 0.2.5

package/docs/explain/00b-generate-architecture.md

@@ -0,0 +1,76 @@
+[← Explain Home](README.md) · [Prev: /setup-ai-first](00-setup-ai-first.md) · [Next: /define-product →](01-define-product.md)
+
+# 00b · `/generate-architecture` — Sinh / làm mới Architecture Context (SSOT)
+
+> **Một câu.** Thu thập kiến trúc từ **mọi nguồn sẵn có** (config + tài liệu + code) rồi **phỏng vấn lấp chỗ trống** để dựng `architecture.md` — nguồn chân lý kiến trúc cắt ngang, do SA/Tech Lead verify.
+
+---
+
+## Vấn đề giải quyết
+
+`/generate-tech-docs` cần biết kiến trúc thật của hệ thống (tầng, ranh giới truy cập dữ liệu, auth, multi-tenant…) để tech-design không "tự chế" mỗi feature một kiểu. Nguồn đó là `architecture.md`.
+
+Nhưng một template kiến trúc đầy đủ có ~140 ô. Bắt SA điền tay từ giấy trắng là **không tối ưu** — vừa nản, vừa trùng lặp với thứ đã nằm trong config/tài liệu/code. Lệnh này đảo ngược gánh nặng: **máy hút cái đã biết, người chỉ trả lời cái chưa biết**.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** bước nền (foundation), ngoài vòng lặp per-feature. Chạy sau `/setup-ai-first`, một lần rồi refresh khi kiến trúc đổi.
+- **Đặc biệt:** bỏ qua Gate Bước 1 (không có feature-file input). Vẫn chạy model check + context-loader.
+- **Tiền đề:** đã có `project-context.yaml` + `CLAUDE.md`. Brownfield thì cần code để scan; greenfield thì dựa vào phỏng vấn.
+
+---
+
+## Input / Output
+
+**Input:** `$ARGUMENTS` tuỳ chọn — `{service-path}` (umbrella), `--from=<paths>` (tài liệu có sẵn), `--section=<slug>` (điền dần 1 mục), `--interview` (ép phỏng vấn).
+
+**Output:** `specs/architecture.md` (hoặc `{service}/specs/architecture.md`) — theo **tier** (core / conditional / ops), mục chưa làm để dạng **STUB**, frontmatter `verified_by: AI-draft` chờ người verify.
+
+---
+
+## Các bước xử lý ⭐
+
+| Bước | Làm gì |
+|------|--------|
+| **1 · Phân giải** | Target file + chế độ (brownfield/greenfield) + parse cờ. File đã `verified_by: {người}` → sang refresh có kiểm soát (không đè). |
+| **2 · Thu thập đa nguồn** | Theo ưu tiên: **config** (`project-context`+`CLAUDE.md`) → **tài liệu** (`--from`) → **scan code**. Mỗi field ghi kèm nguồn + độ chắc chắn; đánh dấu field còn trống / xung đột. |
+| **3 · Phỏng vấn thích ứng** | Báo cáo coverage → **Pha 1 sàng lọc** (thẻ dễ hiểu, bỏ câu đã có đáp án) → **Pha 2 đào sâu** (drill loop có ràng buộc, chỉ trên mục đã "CÓ", lối thoát "để sau"). |
+| **4 · Lắp ráp theo tier** | core luôn viết · conditional viết nếu bật, else STUB · ops mặc định STUB. Chèn `<!-- nguồn -->` / `<!-- ⚠️ xung đột -->`. Frontmatter trust-gate. |
+| **5 · `--section`** | Chỉ lấp/refresh 1 mục (điền dần), gỡ cờ stub. |
+| **6 · Refresh** | File đã verify → chỉ xuất drift, không đè. |
+| **7 · Bàn giao** | Nhắc SA verify + đổi `verified_by`. |
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 Nếu file đang `AI-draft` → hỏi trước khi regenerate đè.
+- 🔒 **Trust-gate `verified_by`**: chỉ khi là **người thật**, `/generate-tech-docs` mới coi doc là ràng buộc chính thức; `AI-draft` bị gắn ⚠️ và thua CLAUDE.md/BDD khi mâu thuẫn.
+- Umbrella không có service path → DỪNG (kiến trúc là per-service).
+
+---
+
+## Cơ chế đặc biệt
+
+- **Điền dần (progressive):** mục chưa làm là STUB, lấp sau bằng `--section=<slug>` — không phải regenerate cả file.
+- **Skip-if-answered:** câu phỏng vấn nào (kể cả follow-up) đã có đáp án từ config/tài liệu/code thì **không hỏi**.
+- **Phỏng vấn 2 pha có ràng buộc:** chỉ đào sâu trong phạm vi SA đã trả lời CÓ, gộp 2–3 câu/lượt, luôn có "để sau" → loop chắc chắn kết thúc.
+- **Tier lọc context:** `/generate-tech-docs` chỉ nạp **core + conditional**, bỏ **ops** → giảm nhiễu.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chi phí SA:** từ "điền 140 ô" → "trả lời vài thẻ + duyệt draft". Điểm mấu chốt là chất lượng bước **hút nguồn** (Bước 2) — hút càng tốt, hỏi càng ít.
+- **Rủi ro:** draft `AI-draft` có thể sai; trust-gate ép người verify trước khi nó ảnh hưởng code-gen. Đừng để doc kẹt mãi ở `AI-draft`.
+- **Phụ thuộc:** chất lượng phụ thuộc `--from` (tài liệu tốt) + code rõ ràng. Greenfield dựa nhiều vào phỏng vấn.
+
+---
+
+## Kết nối
+
+**Trước:** [`/setup-ai-first`](00-setup-ai-first.md) (đã có config).
+**Sau:** [`/generate-tech-docs`](07-generate-tech-docs.md) nạp `architecture.md` (Bước 0.5 [ARCH]) để tech-design bám kiến trúc.
+**Người sở hữu:** SA / Tech Lead — xem [Guide · Architect / SA](../03-guides/architect.md).

package/docs/explain/01-define-product.md

@@ -0,0 +1,79 @@
+[← /generate-architecture](00b-generate-architecture.md) · [Explain Home](README.md) · [Next: /generate-prd →](02-generate-prd.md)
+
+# 01 · `/define-product` — Khám phá tính năng (Q&A 8 Phase)
+
+> **Một câu.** Dẫn PO qua một buổi hỏi-đáp **8 phase có checkpoint** để biến ý tưởng bằng lời thành một **product-definition** có cấu trúc — nền cho PRD.
+
+---
+
+## Vấn đề giải quyết
+
+Đây là **thượng nguồn**. Sai ở đây nhân lên cấp số nhân xuống toàn pipeline. Command ép PO diễn đạt intent **một lần, có cấu trúc, chốt từng phase** — để người lẫn AI hiểu giống nhau, không nhảy thẳng ý-tưởng → code.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Discovery (bước 1).
+- **Tiền đề:** đã `/setup-ai-first`; có ý tưởng bằng lời (+ tuỳ chọn Figma).
+- **Gate ra:** không gate cứng — output là `product-definition` (chưa phải PRD).
+
+---
+
+## Input / Output
+
+**Input:** ý tưởng natural language + context nền (CLAUDE.md, domain-knowledge nạp qua context-loader).
+
+**Output:** `{product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `product-definition.template.md`, có **Metadata với `Completed Phase` + `Status`** để resume.
+
+> ⭐ **`slug` sinh ở đây là định danh feature-package dùng xuyên suốt** — PRD/BDD/tech-docs/design-spec/trace đều kế thừa nguyên văn. Sinh một lần, không tái sinh.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+Sau Gate + Context-Loader chung, chạy **Business Language Guard** (giữ giọng nghiệp vụ) rồi 8 phase:
+
+| Phase | Tên | Việc | Checkpoint |
+|-------|-----|------|:----------:|
+| **0** | Knowledge Sync | AI **tự** quét dự án: khái niệm liên quan, feature bị ảnh hưởng, rule có sẵn, **chuẩn hoá thuật ngữ** (map input PO → business-dictionary; phát hiện NEW TERM lặp ≥2 lần → dồn hỏi ở Phase 3) | — (AI tự) |
+| **1** | Feature Definition | Hỏi **lần lượt từng câu**: Context · Problem · Goal · Actors · In/Out Scope · User Story · **Phụ thuộc liên service** | 🛑 1 |
+| **2** | User Flow | Entry point · Flow steps (bảng) · **Màn hình & thành phần chính** (nguồn cho Wireframe + coverage BDD) · Exit point · Edge cases | 🛑 2 |
+| **3** | Clarification Log | AI xác định gap, hỏi follow-up nhiều vòng. **BLOCK: còn "Mục chưa giải quyết" → không sang Phase 4** | 🛑 3 |
+| **4** | Business Rules | Suy từ Phase 1–3: mỗi BR = system MUST/MUST NOT + điều kiện | 🛑 4 |
+| **5** | Business Logic | Map mỗi BR → logic nghiệp vụ (rẽ nhánh/công thức) — KHÔNG mô tả thay đổi dữ liệu/UI | 🛑 5 |
+| **6** | Acceptance Criteria | Suy từ BR + User Story; mỗi AC testable (pass/fail rõ) | 🛑 6 |
+| **7** | Validation Report | AI tự sinh **ma trận độ phủ** (Flow action × Rule/Logic/AC), phát hiện xung đột & gap | — |
+
+Mỗi checkpoint: AI tóm tắt → chờ PO `✅ xác nhận: Có` → mới sang phase sau. **Cập nhật `Completed Phase` sau mỗi checkpoint** → resume được nếu ngắt giữa chừng.
+
+---
+
+## Checkpoint & Gate
+
+- 🔴 **Mật độ HITL cao nhất toàn pipeline** — 6 checkpoint tường minh (Phase 1–6) + BLOCK ở Phase 3.
+- Hỏi **từng câu một** (không dồn), có ví dụ gợi ý khi PO lúng túng.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Phase 0 tách khỏi Q&A** — AI tự làm phần "bối cảnh hệ thống" (không cần PO), chỉ dồn câu hỏi thật vào các phase sau → không phá trải nghiệm.
+- **NEW TERM detection** — thuật ngữ mới lặp ≥2 lần được phát hiện ở Phase 0 nhưng **hỏi ở Phase 3**, và có thể cập nhật ngược `business-dictionary.md`.
+- **Altitude enforcement** — Phase 4/5/6 tách rõ BR (quy tắc) vs Logic (cơ chế nghiệp vụ) vs AC (nghiệm thu); Business Language Guard chặn kỹ thuật lọt vào.
+- **Resume qua Metadata** — `Completed Phase` cho phép ngắt/tiếp buổi khác.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chi phí HITL cao** — 6 checkpoint tuần tự, hỏi từng câu, có thể dài với feature nhỏ. Đáng cân nhắc "fast mode" cho feature đơn giản (gộp phase, short-circuit khi AI đủ tự tin) — hiện chưa có.
+- **Phase 3 BLOCK** là điểm dễ kẹt nếu AI đặt câu hỏi không hội tụ. Chất lượng câu hỏi phụ thuộc Phase 0 quét dự án tốt tới đâu.
+- **Trùng "8 chặng" vs "8 phase"** — tài liệu concept từng nói "8 chặng"; thực tế là Phase 0–7. Cần đồng bộ để review không nhầm.
+- **Ma trận Phase 7** là một dạng self-review sớm — có thể tái dùng ý này ở downstream.
+
+---
+
+## Kết nối
+
+**Trước:** [`/setup-ai-first`](00-setup-ai-first.md) · **Sau:** [`/generate-prd {product-definition-file}`](02-generate-prd.md).

package/docs/explain/02-generate-prd.md

@@ -0,0 +1,78 @@
+[← /define-product](01-define-product.md) · [Explain Home](README.md) · [Next: /refine-prd →](03-refine-prd.md)
+
+# 02 · `/generate-prd` — Sinh Product Requirements Document
+
+> **Một câu.** Biến `product-definition` (8 phase Q&A) thành một **PRD chuẩn nghiệp vụ** đúng template, với đánh số UC/BR và traceability AC↔BR↔UC.
+
+---
+
+## Vấn đề giải quyết
+
+`product-definition` là bản ghi buổi discovery — chưa phải tài liệu chính thức. `/generate-prd` chuyển nó thành **PRD** có cấu trúc cố định (Metadata, AC, UC, BR, Wireframe, Change Log), đánh số nhất quán, và **link traceability** — làm hợp đồng nghiệp vụ để phân rã xuống BDD.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Specification (đầu).
+- **Tiền đề:** có `product-definition/{TICKET-ID}-{slug}.md`.
+- **Gate ra:** PRD sinh với `Status: draft` — cần `/refine-prd` + `/review-context` + PO approve.
+
+---
+
+## Input / Output
+
+**Input:** file product-definition + bảng **Chuẩn hoá thuật ngữ** (Phase 0) + business-dictionary + core-entities.
+
+**Output:** `{specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` — **một** file PRD ở gốc feature folder (KHÔNG đặt tên `prd.md`).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+Sau Gate + Context-Loader + Business Language Guard:
+
+1. **Áp Terminology Map từ product-definition** — mỗi cặp `thuật ngữ PO → chuẩn` dùng bản chuẩn khi viết PRD (ưu tiên kể cả khi dictionary vắng).
+2. **Thay banned term + chỉ dùng canonical term.**
+3. **NEW TERM DETECTION (lưới an toàn)** — nếu vẫn còn thuật ngữ lặp ≥2 lần không có trong dictionary → **DỪNG hỏi PO** (nghĩa là gì, English canonical, bổ sung dictionary?).
+4. **Quy tắc Cross-Reference** — mọi TICKET-ID khác được nhắc → phải là inline link tới folder anh em `../{prd-slug-khác}/…`, không để plain text.
+5. **Đánh số UC/BR:**
+   - UC: `{TICKET}-UC{n}` (n từ 1).
+   - BR: `{TICKET}-UC{n}-BR{m}` — **m tăng liên tục toàn PRD, KHÔNG reset theo UC**.
+6. **Traceability AC↔BR↔UC (2 chiều bắt buộc):**
+   - Mỗi AC remap ref BR từ discovery → BR ID của PRD; mỗi AC có ≥1 ref BR.
+   - Mỗi UC liệt kê "AC liên quan"; hai chiều phải **khớp đúng** (lệch = lỗi traceability, sửa trước khi ghi).
+7. **Platform Strategy** — PRD thuần WHAT nghiệp vụ; cho phép Wireframe mức nghiệp vụ; chi tiết visual → Design Spec, contract kỹ thuật → Tech Docs.
+   - **Ngoại lệ brownfield:** `API Source: existing` → Appendix "Existing API Contract" được chứa chi tiết kỹ thuật (trích as-is).
+8. **Generate** — ghi PRD theo template: Metadata (Version 1.0, Status draft, Domain, Ticket, API Source) · Feature · §1 Tổng quan (User Story, Scope, Phụ thuộc liên service) · §2 AC · §3 UC (BR table 3 cột: ID | Business Rule | Business Logic) · Wireframe · Change Log.
+
+---
+
+## Checkpoint & Gate
+
+- Không checkpoint riêng ngoài Gate chung + DỪNG khi NEW TERM.
+- Output `Status: draft` — **chưa** mở khoá downstream.
+
+---
+
+## Cơ chế đặc biệt
+
+- **BR đánh số liên tục toàn PRD** (không reset) — để BR ID tự mang thông tin UC, suy ngược traceability.
+- **AC↔BR↔UC nhất quán 2 chiều** — self-check ngay khi sinh.
+- **Business Rule = bảng 3 cột** (không tách Business Logic ra khối riêng) — giữ altitude.
+- **Brownfield exception** — chỉ Appendix "Existing API Contract" được chứa kỹ thuật.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **NEW TERM detection lặp lại** ở cả `/define-product` (Phase 0/3) lẫn đây (lưới an toàn). Nếu discovery làm tốt, bước này hiếm khi kích hoạt — nhưng vẫn tốn prompt. Cân nhắc: đây là redundancy có chủ đích (an toàn) hay dư thừa?
+- **Traceability 2 chiều tự kiểm** là điểm mạnh — có thể là mẫu để nhân sang các artifact khác.
+- **Phụ thuộc chất lượng product-definition** — nếu discovery sơ sài, PRD sẽ mỏng; `/generate-prd` không tự bù bằng Q&A (đó là việc `/refine-prd`).
+- **Business Language Guard chạy lại** ở đây dù đã chạy ở discovery — chi phí lặp.
+
+---
+
+## Kết nối
+
+**Trước:** [`/define-product`](01-define-product.md) · **Sau:** [`/refine-prd`](03-refine-prd.md) → [`/review-context`](04-review-context.md).

package/docs/explain/03-refine-prd.md

@@ -0,0 +1,86 @@
+[← /generate-prd](02-generate-prd.md) · [Explain Home](README.md) · [Next: /review-context →](04-review-context.md)
+
+# 03 · `/refine-prd` — Tinh chỉnh PRD qua 3 lăng kính
+
+> **Một câu.** Fan-out review PRD qua **3 lăng kính DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
+
+---
+
+## Vấn đề giải quyết
+
+Một lượt review đơn không bao giờ liệt kê hết vấn đề — model dừng ở mức "đủ", nên mỗi vòng sau lại lòi lỗi mới (**đập chuột chũi**). `/refine-prd` ép review **hội tụ trong một lần chạy**, bắt lỗi nghiệp vụ *trước* khi truyền xuống BDD, giữ altitude & ngôn ngữ nghiệp vụ.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Specification (sau `/generate-prd`).
+- **Tiền đề:** có PRD draft.
+- **Đặc biệt:** có **Resume Mode** (`--resume`) áp findings đã accept và bump version PRD.
+
+---
+
+## Input / Output
+
+**Input:** PRD + core-entities + business-dictionary.
+
+**Output:** `{refinement_dir}/{prd-slug}-findings.yaml` — findings với `lens` (DEV/SA/PO), severity, `quote`+`uc_id` (để Review Board jump-to-source), `suggestion`, `resolution_edge_cases`, `status`.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
+
+### Phase 1 — Fan-out song song theo dimension
+- **DIMENSIONS = 3 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
+  | Lăng kính | Soi gì |
+  |-----------|--------|
+  | **DEV** (cơ chế nghiệp vụ) | BR + Business Logic đã đủ & không mơ hồ để build không phải đoán chưa? Nhánh nghiệp vụ thiếu, điều kiện biên, đường lỗi bỏ ngỏ |
+  | **SA** (thông suốt & nhất quán) | Luồng nghiệp vụ thông suốt trên cả feature/domain? Tương tác UC, quan hệ entity, vòng đời trạng thái, ai-làm-gì |
+  | **PO** | Scope khoanh vùng? Priority? Success metric? Rủi ro scope creep? |
+- ⚠️ **Nguyên tắc DEV & SA: đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ** — chỉ nêu *cái nghiệp vụ còn thiếu/mơ hồ* + đặt câu hỏi làm rõ; KHÔNG đề xuất cơ chế kỹ thuật.
+- `GRANULARITY = per-uc` → luôn fan-out `DIMENSION × UC` (+ phạm vi PRD-global), bỏ ngưỡng cả-file → **lần đầu quét sâu**. Agent cap = 12/wave, gom batch UC nếu vượt.
+
+### Phase 2 — Vòng lặp completeness-critic
+- Spawn một critic đọc **toàn PRD** + danh sách findings đã có (slim) → liệt kê **chỉ vấn đề mới** (gap, mâu thuẫn, edge/negative path thiếu, **vi phạm altitude/role-boundary**: cơ chế nằm trong AC, AC lặp lại BR…).
+- Lặp tới khi **2 vòng liên tiếp 0 finding mới** hoặc cap **3 vòng**. Ghi `convergence_rounds`.
+
+### Phase 3 — Dedup / xung đột / merge
+- Khử trùng (giữ suggestion phong phú hơn, severity cao hơn); merge được thì merge, loại trừ nhau → một finding `needs_discussion`; sắp theo severity; gán ID `F001…`; map dimension → `lens`; ghi **một** file findings.
+
+### Full vs Delta
+- Lần đầu (chưa có findings file) → **FULL**. Lần sau so `prd_version`: chưa đổi → DỪNG; đổi do chính resume này (`applied_to_version` khớp) → **DELTA** (chỉ UC đã đổi + UC mới); đổi bởi actor khác → **FULL** + cảnh báo.
+
+### Resume Mode (`--resume`)
+- Áp finding theo `status` (`accepted`/`modified`), bump version PRD, ghi `applied_to_version`. `needs_discussion` chặn resume tới khi người quyết.
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 **Review Board** — PO accept/reject/modify **từng** finding (không auto-apply). Finding lifecycle: `pending → accepted|modified|rejected|needs_discussion|deferred → applied`.
+- `recommendation`: critical≥1 → `BLOCKED`; major≥1 → `NEEDS_REVISION`; else `APPROVED_WITH_MINOR_CHANGES`.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Không có `--fix` mode** (khác `/review-context`) — finding 3 lăng kính là phán đoán DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
+- **`resolution_edge_cases`** — phân tích bậc-hai (chỉ critical/major): "nếu chốt phương án này thì đẻ ra edge case gì?" → PO thấy trước khi accept (advisory, không chặn).
+- **QA lens đang DISABLED** (comment trong file) — có hướng dẫn bật lại nếu cần.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 3 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
+- **Completeness-critic tới 3 vòng** — điểm đáng đo: thực tế hội tụ ở vòng mấy? Nếu thường 1–2 vòng thì cap 3 hợp lý.
+- **Full/delta logic phức tạp** (`applied_to_version` tracking) — mạnh nhưng nhiều nhánh; dễ rơi về FULL khi có actor khác sửa PRD (vd `/review-context` xen giữa).
+- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (3 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-prd`](02-generate-prd.md) · **Sau:** mở Review Board → cập nhật PRD → [`/review-context`](04-review-context.md).

package/docs/explain/04-review-context.md

@@ -0,0 +1,100 @@
+[← /refine-prd](03-refine-prd.md) · [Explain Home](README.md) · [Next: /generate-design-spec →](05-generate-design-spec.md)
+
+# 04 · `/review-context` — Gate chất lượng PRD & BDD (findings có mã)
+
+> **Một câu.** Cổng chất lượng cuối ở thượng nguồn: fan-out review có mã (**P0–P5** cho PRD, **B1–B6** cho BDD), sạch critical mới mở khoá downstream. Có 3 chế độ: phân tích · `--fix` (auto-apply) · `--resume` (áp finding đã accept).
+
+> ⚠️ **Một lệnh, hai đối tượng.** Target là PRD → **PRD Review Mode**; target là `.feature` → **BDD Review Mode**. Nó chạy ở **hai vị trí** trong pipeline (sau PRD, và sau BDD).
+
+---
+
+## Vấn đề giải quyết
+
+Artifact kém ở thượng nguồn phá huỷ hạ nguồn. `/review-context` là **gate bằng findings**: phân loại lỗi theo mã, chặn tới khi sạch critical + người đặt trạng thái `approved`. Khác `/refine-prd` (phán đoán chất lượng 3 lăng kính), đây là **check có mã, có auto-fix**.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** sau `/generate-prd`/`/refine-prd` (PRD mode) **và** sau `/generate-bdd` (BDD mode).
+- **Gate ra:** sạch critical → người đặt `Status: approved` (PRD) / `@trace.status: approved` (BDD) → mở khoá bước kế.
+
+---
+
+## Input / Output
+
+**Input:** PRD hoặc `.feature` + business-dictionary + core-entities (+ config umbrella cho P0).
+
+**Output:** file findings —
+- PRD: `{refinement_dir}/{prd-slug}-review-context-findings.yaml`
+- BDD: `{refinement_dir}/{uc-id}-{platform}-review-bdd-findings.yaml`
+
+---
+
+## Các bước xử lý (chi tiết)
+
+### 1 · Detect Review Mode
+Target PRD (`.md` ở gốc feature) → PRD mode; target `.feature` → BDD mode.
+
+### 2 · Chạy review-fanout (Phase 1 → 2 → 3)
+Giống `/refine-prd` (fan-out song song → completeness-critic → dedup/merge), nhưng DIMENSIONS là các mã check:
+
+**PRD Review Mode — P0–P5:**
+| Mã | Check | Ghi chú |
+|----|-------|---------|
+| **P0** | Umbrella routing (chỉ umbrella) | **Orchestrator chạy** (cần config); là gate check |
+| **P1** | Terminology (banned/canonical) | fan-out; **auto-fixable** |
+| **P2** | Ambiguity | fan-out; **KHÔNG auto-fixable** (người viết fix) |
+| **P3** | Domain conflict (cross-PRD) | **Orchestrator chạy** (cần PRD khác) |
+| **P4** | Structural completeness | fan-out; **auto-fixable** (thêm skeleton) |
+| **P5** | Custom criteria | fan-out (tuỳ chọn) |
+
+**BDD Review Mode — B1–B6 (đều fan-out):**
+| Mã | Check |
+|----|-------|
+| **B1** | PRD coverage (mọi AC/UC được phủ) |
+| **B2** | Terminology & entity |
+| **B3** | Gherkin rules (R1–R10) |
+| **B4** | Compliance (C.1–C.5) |
+| **B5** | Metadata & structural (@trace header, Coverage Matrix) |
+| **B6** | Side-effect completeness |
+
+### 3 · Ghi file findings + Post-Analysis Routing
+Sạch critical → nhắc người đặt `approved`; còn critical → giữ draft, sửa.
+
+### Chế độ `--fix` (auto-apply)
+Chạy full phân tích rồi **áp ngay** các finding `auto_fixable: true` (không qua Board): PRD (P1 banned term, P1 tech-term reframe, P4 skeleton) · BDD (B2 terminology, B3 R3/R7/R9/R10, B4 C4/C5, B5 header/matrix, B6 side-effect). Finding cần người vẫn để `pending`.
+- **Version bump + reset draft:** ≥1 fix áp → PRD bump minor + **reset `Status: draft`** + Changelog; BDD tăng `@trace.bdd_version` 0.1 + **reset `@trace.status: draft`**. Ghi `applied_to_version`.
+
+### Chế độ `--resume`
+Áp các finding `accepted`/`modified` từ Board; bỏ `rejected`/`deferred`; `needs_discussion` → cảnh báo, bỏ lần này.
+
+---
+
+## Checkpoint & Gate
+
+- 🔒 **Gate bằng trạng thái** — sạch critical là điều kiện *cần*; người đặt `approved` là điều kiện *đủ*.
+- 🛑 Finding cần người → Review Board (accept/reject/modify) → `--resume`.
+
+---
+
+## Cơ chế đặc biệt
+
+- **`--fix` reset con dấu duyệt** — auto-fix làm target đổi sau khi duyệt → status về `draft`, phải duyệt lại (đồng bộ với `/refine-prd`).
+- **P0/P3 do orchestrator chạy** (không fan-out) vì cần config/PRD khác; P1/P2/P4/P5 mới fan-out.
+- **Ngôn ngữ finding thuần nghiệp vụ** — cả PRD và BDD (BDD đứng trước tech-docs); `quote` được miễn (trích nguyên văn, kể cả Gherkin).
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chồng lấn với `/refine-prd`** ở PRD mode — cùng review-fanout, cùng review PRD. Ranh giới: `/refine-prd` = 3 lăng kính phán đoán (không auto-fix); `/review-context` = mã P-check (có auto-fix). Đáng review có nên hợp nhất/rõ ranh giới hơn.
+- **`--fix` reset draft** đúng về nguyên tắc nhưng tạo vòng "fix → reset → duyệt lại" — với PRD ổn định chỉ cần dọn thuật ngữ, chi phí duyệt lại đáng cân nhắc.
+- **B1 coverage phụ thuộc chất lượng PRD** — nếu PRD mơ hồ, "phủ đủ" khó đo. B4 C.2 cố ý dedup với B1.
+- **Cùng lệnh 2 mode PRD/BDD** giữ code chung nhưng logic rẽ nhánh dày — điểm cần chú ý khi bảo trì.
+
+---
+
+## Kết nối
+
+**Trước:** [`/refine-prd`](03-refine-prd.md) (PRD) / [`/generate-bdd`](06-generate-bdd.md) (BDD) · **Sau:** PRD approved → [`/generate-design-spec`](05-generate-design-spec.md) (FE/App) hoặc [`/generate-bdd`](06-generate-bdd.md); BDD approved → [`/generate-tech-docs`](07-generate-tech-docs.md).

package/docs/explain/05-generate-design-spec.md

@@ -0,0 +1,73 @@
+[← /review-context](04-review-context.md) · [Explain Home](README.md) · [Next: /generate-bdd →](06-generate-bdd.md)
+
+# 05 · `/generate-design-spec` — Đặc tả thiết kế UI (chỉ FE/App)
+
+> **Một câu.** Sinh đặc tả visual **bám Figma frame thật** (fetch qua Figma MCP) cho từng màn hình — chỉ cho service FE/App — làm nguồn cho BDD giao diện.
+
+---
+
+## Vấn đề giải quyết
+
+BDD UI cần biết màn hình có gì, trạng thái nào, tương tác ra sao. Để `/generate-bdd` tự đoán → coverage thiếu/lệch Figma. Design-Spec chốt visual thật, 2 tầng ngôn ngữ, lái coverage UI.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Design (nhánh FE/App), sau PRD approved.
+- **Chặn cứng:** `platform_type = backend` → **STOP** (BE không có UI).
+
+---
+
+## Input / Output
+
+**Input:** PRD approved (§4 User Flow/Wireframe) + **link Figma frame node-level** cho từng màn + `figma-components/{module}.md`.
+
+**Output:** `{specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md` (platform: web / app / app-ios / app-android).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Platform Check** — suy `active_platform` từ module; backend → STOP; unknown → hỏi.
+2. **Version Check (PRD drift)** — nếu design-spec đã có, so `Built from PRD` với Version PRD hiện tại:
+   - Bằng → hỏi sinh lại? · Khác → CHECKPOINT drift (Y=cập nhật phần ảnh hưởng · F=sinh lại toàn bộ · N=huỷ).
+   - Khi sinh/sinh lại: cập nhật `Built from PRD`, bump Version, **reset `Status: draft`** (design đổi → sign-off lại).
+3. **Screen Discovery** — trích màn hình/page/modal từ PRD §4, trình PO xác nhận → `screen_list`.
+4. **Figma Frame Links (bắt buộc)** — thu **một link node-level cho mỗi màn**:
+   - Validate URL phải chứa `?node-id=...` (link file trần bị từ chối — AI không đọc được).
+   - **Fetch qua Figma MCP** (`get_design_context`, `get_screenshot`) đọc layout/component/token thật; **không bịa** layout frame không thể hiện.
+   - `none` → màn ❌ Missing.
+5. **Gate mềm** — màn thiếu link → spec sinh dạng **draft** với cờ `missing_frames`, giữ `draft` tới khi đủ link đọc được; thêm AI Assumption cho mỗi màn thiếu.
+6. **CHECKPOINT** → chờ Y.
+7. **Generate** theo template: §1 Screen Inventory · §2 Screen Specs (mỗi màn: layout, component, state default/empty/loading/error) · §3 Interaction Patterns (responsive/hover/keyboard web; gesture/navigation app) · §4 Platform Considerations (a11y web; device/OS app) · §5 AC-UI (tiêu chí nghiệm thu design) · Appendix (tóm tắt Figma, design token đã tham chiếu).
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 Screen Discovery + CHECKPOINT trước generate.
+- 🟠 Gate mềm: thiếu Figma frame → draft, không sign-off; `/generate-bdd` cảnh báo mềm nếu design-spec chưa approved.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Phụ thuộc Figma MCP** — đây là command duy nhất trong pipeline **fetch dữ liệu ngoài** (Figma). Chất lượng spec phụ thuộc trực tiếp link node-level + quyền truy cập.
+- **2 tầng ngôn ngữ** — mô tả nghiệp vụ (PO) + tham chiếu component (Dev/Designer).
+- **Drift theo PRD version** — `Built from PRD` giúp phát hiện PRD đổi sau khi design.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Điểm phụ thuộc ngoài mạnh nhất** — nếu Figma MCP không cấu hình/không quyền, mọi màn thành ❌ Missing → spec chỉ text. Đáng có fallback rõ ràng hơn (vd import screenshot thủ công).
+- **Thu link per-màn thủ công** tốn thao tác PO với feature nhiều màn. Có thể tối ưu bằng đọc cả file rồi map node — nhưng bị chặn bởi giới hạn "AI không đọc link file trần".
+- **Reset draft khi drift** đúng nguyên tắc nhưng tạo vòng sign-off lại; cân nhắc drift một phần (chỉ màn đổi).
+- **Nhánh platform (web/app/app-ios/app-android)** nhân đôi một số section — chi phí bảo trì.
+
+---
+
+## Kết nối
+
+**Trước:** [`/review-context`](04-review-context.md) (PRD approved) · **Sau:** Designer + PO sign-off → [`/generate-bdd`](06-generate-bdd.md).

package/docs/explain/06-generate-bdd.md

@@ -0,0 +1,77 @@
+[← /generate-design-spec](05-generate-design-spec.md) · [Explain Home](README.md) · [Next: /generate-tech-docs →](07-generate-tech-docs.md)
+
+# 06 · `/generate-bdd` — Sinh kịch bản BDD (.feature)
+
+> **Một câu.** Phân rã PRD thành các file `.feature` (Gherkin) mang `@trace.*`, theo platform (web/app/system), với fan-out per-UC và tổng hợp **System BDD** từ BDD FE/App.
+
+---
+
+## Vấn đề giải quyết
+
+BDD là **anchor cứng** của traceability — mọi code/test link về scenario. Cấu trúc UC/SC quyết ở đây tác động mọi file code sau. Command phân rã PRD → UC → SC bằng Gherkin, gắn trace, và (cho system) tổng hợp contract từ BDD FE/App.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Design, sau PRD approved (+ design-spec nếu FE/App).
+- **Gate vào:** cảnh báo mềm nếu PRD chưa `approved` (áp mọi mode).
+
+---
+
+## Input / Output
+
+**Input:** PRD approved + design-spec (FE/App) + `feature.template` + BDD FE/App có sẵn (khi tổng hợp system).
+
+**Output:** `.feature` với header `@trace.*` đầy đủ:
+- Spec repo: `bdd/{web|app|system}/{TICKET-ID}-UC{N}-{slug}.feature`
+- Umbrella: `bdd/{TICKET-ID}-UC{N}-{slug}.feature`
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Phát hiện Repo Mode** — spec repo (không có `services`) → Platform Selection; umbrella (có `services`) → Service Detection (routing đã resolve ở context-loader; `unresolved` → DỪNG).
+2. **Platform Selection** (spec mode) — hỏi web / app / **system**; set từ vựng theo platform (clicks/taps/receives).
+3. **System BDD Synthesis** (nếu platform = system) — 5 step:
+   - **S0 Brownfield** — `API Source: existing` → skip scan, dùng contract PRD.
+   - **S1 Scan** BDD web/app có sẵn → phân loại multi/web-only/app-only/backend-only.
+   - **S2 Trích contract** kỳ vọng mỗi platform (triggers, response data, error, business rules).
+   - **S3 Cross-Platform Conflict Check** (multi) — so contract giữa platform; conflict (shape/error/rule/field) → 🛑 **CHECKPOINT bắt buộc** với 4 resolution: A union · B platform-hint · C endpoint riêng · D custom. Ghi `@system.resolution`.
+   - **S4 Generate** scenario dùng từ vựng business-event (không UI).
+4. **Design Spec Gate & Load** (FE/App) — nạp design-spec để lái coverage UI; cảnh báo mềm nếu chưa approved/lỗi thời.
+5. **Orchestration Check** — PRD nhiều UC → **fan-out mỗi UC một sub-agent** (`_agent_mode`), sinh song song, gom kết quả.
+6. **UC Decomposition** — 🛑 trình danh sách UC/SC để PO chốt.
+7. **Generate** — mỗi `.feature` với header @trace (id, platform, service, module, status=draft, prd_version, bdd_version, business_rules, dataset) + scenario theo **R1–R10** + Compliance **C.1–C.5** + **NHÓM grouping** (bắt buộc khi ≥3 SC) + Coverage Matrix.
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 **UC Decomposition** — điểm dừng chính (cấu trúc UC sai kéo cả pipeline).
+- 🛑 **Cross-platform conflict** (system multi) — bắt buộc PO resolve.
+- Sinh với `@trace.status: draft` → cần `/review-context` sạch critical → đặt `approved`.
+
+---
+
+## Cơ chế đặc biệt
+
+- **System BDD là tổng hợp**, không viết tay — suy từ BDD web+app, giải conflict contract trước khi có tech-docs.
+- **Fan-out per-UC** giữ context mỗi sub-agent nhỏ, quét sâu.
+- **Từ vựng theo platform** áp âm thầm; không trộn web/mobile trong một file.
+- **R1–R10 + C.1–C.5** enforce nghiêm, làm input cho gate B3/B4 của `/review-context`.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **System BDD synthesis là phần phức tạp nhất** — phụ thuộc BDD web/app đã tồn tại & chất lượng. Nếu FE/App BDD lệch, conflict check gánh nặng; nếu thiếu → backend-only suy từ PRD.
+- **Conflict resolution ghi vào `@system.resolution`** nhưng quyết định contract thực chốt ở tech-docs (T7). Có thể trùng vai — đáng xem ranh giới BDD-system vs tech-design.
+- **Fan-out per-UC** tốn agent với PRD lớn (giống refine-prd) — chi phí ↔ độ đầy đủ.
+- **Thứ tự platform quan trọng** — system nên sinh *sau* web/app để có contract tổng hợp; pipeline không ép thứ tự này cứng.
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-design-spec`](05-generate-design-spec.md) (FE/App) / [`/review-context`](04-review-context.md) (PRD) · **Sau:** [`/review-context {feature}`](04-review-context.md) → [`/generate-tech-docs`](07-generate-tech-docs.md).

package/docs/explain/07-generate-tech-docs.md

@@ -0,0 +1,71 @@
+[← /generate-bdd](06-generate-bdd.md) · [Explain Home](README.md) · [Next: /review-tech-docs →](08-review-tech-docs.md)
+
+# 07 · `/generate-tech-docs` — Sinh Technical Design (full-stack, gộp/PRD)
+
+> **Một câu.** Sinh **một** tech-design full-stack cho cả PRD (backend API/data/DB **và** client), theo chế độ Fresh/Append tăng dần, với self-review REFUTE và cổng ký liên team.
+
+---
+
+## Vấn đề giải quyết
+
+Đây là ranh giới nghiệp-vụ → kỹ-thuật. Tech-design là **API contract** giữa các team (BE viết, FE/App đọc). Chốt sai = đốt budget cả hai phía. Command chuẩn hoá entity/API/dependency và phủ mọi UC trong một doc.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Design (đầu ra kỹ thuật), sau BDD.
+- **Gate vào:** cổng chất lượng — BDD phải sạch finding critical + cảnh báo mềm nếu chưa `approved`.
+
+---
+
+## Input / Output
+
+**Input:** các `.feature` (batch tech lead trỏ vào) + review-bdd findings + design-spec (cho §4.5 client) + entity catalog + Figma component catalog.
+
+**Output:** `{specs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` — **một** doc 12 section.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Bước 1 · Fresh vs Append** — chưa có doc → **FRESH**; đã có → **APPEND** (tăng dần, **không regenerate** để khỏi mất chỉnh tay + sign-off). Đọc §10 UC Coverage → `covered_ucs`; mỗi UC batch phân loại `add-new` / `extend-platform` / `refresh` (hỏi Y/N) / `skip`.
+2. **Bước 2 · Cổng Chất lượng** — mỗi feature: tìm `{uc-id}-{platform}-review-bdd-findings.yaml`; còn critical `pending` → **DỪNG** (chạy `--fix`/`--resume` trước); `@trace.status ≠ approved` → cảnh báo mềm Y/N.
+3. **Bước 3 · Điều kiện tiên quyết Client** (batch có web/app) — nạp design-spec cho §4.5 (component, Figma map, state, selector); thiếu → §4.5 degraded `[DRAFT — no design-spec]`.
+4. **Bước 4 · Brownfield** — `@trace.api_source: existing` → **reverse-document** (mô tả as-is, ghi gap vs BDD, không thiết kế mới); else **greenfield** (thiết kế từ scenario).
+5. **CHECKPOINT** — trình kế hoạch (mode, batch, platform, API mode, section sẽ sinh) → chờ Y.
+6. **Sinh** doc 12 section: §1 Overview · §2 Architecture · §3 Data Model · §4 API Contracts (+§4.5 client design) · §5 Key Flows (sequence, lane 5.A system/5.B web/5.C app) · §6 Integration · §7 Security · §8 Error Handling · §9 Design Decisions · **§10 UC Coverage** (khoá theo platform×SC) · §11 Cross-cutting · **§12 GAP Register** (ẩn số chưa chốt).
+7. **Self-Review Gate — REFUTE** — trước khi ghi, tự phản biện doc (bắt buộc, cả Fresh lẫn Append).
+8. **Công bố** (umbrella) — chia sẻ doc vào spec repo dùng chung.
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 CHECKPOINT kế hoạch + xác nhận refresh UC đã phủ.
+- 🔒 Cổng chất lượng BDD (chặn nếu còn critical).
+- Sinh với `@trace.status: draft` + `@trace.sign_off` (be/fe/app/sa = pending) → `/review-tech-docs` T7.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Append tăng dần, không regenerate** — bảo toàn chỉnh tay & sign-off; §10 UC Coverage là "sổ" theo dõi UC đã phủ.
+- **Một doc full-stack** — BE §4 + client §4.5 sinh cùng nhau (bỏ cổng "BE contract trước"); §4.5.4 vẫn phải map endpoint thật ở §4.1.
+- **§12 GAP Register** — ghi ẩn số thiết kế chưa chốt (blocker 🔴 chạm UC → generate-code WARN).
+- **REFUTE self-review** — vòng tự phản biện trước khi ghi.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Append phức tạp** — phân loại add-new/extend-platform/refresh/skip theo platform×UC, đánh số sequence trong đúng lane. Đây là logic dày nhất; dễ sai khi nhiều platform. Đáng review độ chắc của việc merge.
+- **Một doc/PRD** dễ điều hướng nhưng có thể rất lớn với PRD nhiều UC × nhiều platform → chạm giới hạn context khi Append đọc lại.
+- **§12 GAP Register + sign-off** là cơ chế "chốt dần" tốt — nhưng phụ thuộc con người cập nhật trạng thái.
+- **Cổng chất lượng chỉ quét batch** (feature tech lead trỏ) — nếu bỏ sót feature, coverage thủng mà không báo.
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-bdd`](06-generate-bdd.md) + [`/review-context {feature}`](04-review-context.md) · **Sau:** [`/review-tech-docs`](08-review-tech-docs.md).