@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/skills/prd/SKILL.md

@@ -1,496 +1,387 @@
 ---
-description: Generates a PRD from a product definition, or analyzes an existing PRD through 4 review lenses (QA, DEV, SA, PO) to find gaps and risks. Trigger when: "/generate-prd", "/refine-prd", "tạo PRD", "generate PRD", "phân tích PRD", "review PRD", "refine PRD", "PRD có vấn đề gì không", "check PRD quality".
+description: Sinh PRD từ một product definition, hoặc phân tích một PRD có sẵn qua 4 lăng kính review (QA, DEV, SA, PO) để tìm gap và rủi ro. Trigger when: "/generate-prd", "/refine-prd", "tạo PRD", "generate PRD", "phân tích PRD", "review PRD", "refine PRD", "PRD có vấn đề gì không", "check PRD quality".
 ---
 
 # PRD Skills — Generate & Refine
 
-This skill handles two commands: `/generate-prd` to create a PRD, and `/refine-prd` to analyze it for gaps.
+Skill này xử lý hai lệnh: `/generate-prd` để tạo PRD, và `/refine-prd` để phân tích PRD tìm gap.
 
 ---
 
-## /generate-prd — Generate Product Requirements Document
+## /generate-prd — Sinh Product Requirements Document
 
 ### Gate
 
-<!-- Directory: specs/product-definition/**/*.md -->
-# Gate — Universal Entry Procedure
+<!-- Directory: {paths.product_definitions_dir}/**/*.md -->
+# Gate — Quy trình vào chuẩn cho mọi lệnh
 
-Every command must execute this gate before proceeding with its specific logic.
+Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
 
-## Step 0 — Sub-Agent Mode Check
+## Bước 0 — Kiểm tra chế độ Sub-Agent
 
-Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
 
-1. Attempt to parse `$ARGUMENTS` as JSON.
-2. If it parses successfully **and** contains `"_agent_mode": true`:
-   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
-   - Set target file = `payload.target_file`
-   - Set loaded context = `payload.context` (do NOT run context-loader.md)
-   - Set UC scope = `payload.uc_id` (process only this UC)
-   - Set line range = `payload.uc_section` (read only that PRD section)
-   - Proceed directly to the command-specific logic.
-3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+1. Thử parse `$ARGUMENTS` dưới dạng JSON.
+2. Nếu parse thành công **và** chứa `"_agent_mode": true`:
+   - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.**
+   - Đặt target file = `payload.target_file`
+   - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
+   - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
+   - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đi thẳng tới phần logic riêng của lệnh.
+3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 
-## Step 0-B — Model Check
+## Bước 0-B — Kiểm tra Model
 
-*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+*Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).*
 
-Complex generation and review commands require strong reasoning.
-Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+Các lệnh sinh nội dung và review phức tạp đòi hỏi khả năng suy luận mạnh.
+Dùng model nhỏ hơn sẽ rủi ro: bỏ sót edge case, phân tích spec thiếu sót, vi phạm kiến trúc.
 
-Display and wait for response:
+Hiển thị và chờ phản hồi:
 
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (or latest Opus model)
-  Why needed   : Spec analysis, architecture review, code generation
-                 require deep reasoning. Smaller models miss edge cases.
+  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
+  Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
+                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
 
-  To switch in Claude Code:
-    • Settings → Model → select "claude-opus"
-    • or: /model → choose claude-opus
+  Cách đổi trong Claude Code:
+    • Settings → Model → chọn "claude-opus"
+    • hoặc: /model → chọn claude-opus
 
-  Running on claude-opus?
-    Y — yes, on claude-opus → proceed
-    S — skip check (I accept lower quality risk with current model)
+  Đang chạy claude-opus?
+    Y — đúng, đang dùng claude-opus → tiếp tục
+    S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
 ──────────────────────────────────────────────────────────────────
 ```
 
-- "Y" → proceed to Step 1.
-- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
-- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+- "Y" → tiếp tục sang Bước 1.
+- "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
+- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
 
-## Step 1 — Resolve Target File
+## Bước 1 — Xác định Target File
 
-1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
-2. If `$ARGUMENTS` is a **bare UC-ID / ticket ID / partial name** (no path) → resolve it to a file by globbing the feature-package layout. The `{prd-slug}` is **not known yet**, so use a `*` wildcard for that segment, and a recursive `**` under `bdd/` so the platform subfolders (`bdd/web/`, `bdd/app/`, `bdd/system/`) are all covered:
-   - **BDD commands** (target is a `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — or `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` if the domain is also unknown. If a platform/scope is implied by the command (e.g. a system tech-doc needs the `system/` BDD), prefer the match under that platform subfolder.
-   - **PRD commands** (target is `prd.md`): `{specs_dir}/{domain}/*/prd.md` (match the feature folder whose id corresponds), else `{specs_dir}/*/*/prd.md`.
-   - **tech-docs commands**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
-   - **design-spec commands**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+1. Nếu `$ARGUMENTS` được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
+2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
+   - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
+   - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
+   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
-   Once a file matches: set it as the target **and** record `domain` + `prd_slug` from its path (per the extraction rule in `context-loader.md` Step 1 — `prd_slug` = first segment after `{specs_dir}/{domain}/`). Every path the command later reads or writes (sibling BDD/tech-docs/design-spec/trace) uses **that resolved `prd_slug`**, so all artifacts stay in one feature package. If several files match (e.g. multiple platforms), pick per the command's platform/scope or list them and ask.
-3. If `$ARGUMENTS` is empty or no match found:
-   - List files in the relevant directory for this command (e.g., `specs/*/*/prd.md` for PRD commands, `specs/*/*/bdd/**/*.feature` for BDD commands).
-   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
-   - Wait for user selection before continuing.
+   Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
+3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
+   - Chờ người dùng chọn rồi mới tiếp tục.
 
-## Step 2 — Execute Context Loader
+## Bước 2 — Chạy Context Loader
 
-Load all project context by following the procedure in `steps/context-loader.md`.
-Store all loaded context in memory for use throughout this command session.
+Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`.
+Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh.
 
-## Step 3 — CHECKPOINT
+## Bước 3 — CHECKPOINT
 
-After completing Steps 1 and 2, display a summary and wait for confirmation:
+Sau khi hoàn thành Bước 1 và 2, hiển thị bản tóm tắt và chờ xác nhận:
 
 ```
 CHECKPOINT
 -----------
 Target     : {resolved file path}
-Project    : {project.name from project-context.yaml}
+Project    : {project.name từ project-context.yaml}
 Tech stack : {language} / {framework}
-Module     : {module if set, else "not configured"}
-Domains    : {comma-separated domain list}
+Module     : {module nếu có, else "not configured"}
+Domains    : {danh sách domain, ngăn cách bởi dấu phẩy}
 
-Proceed? (Y/N)
+Tiếp tục? (Y/N)
 ```
 
-Wait for explicit "Y" or "N" from the user before continuing.
-- "Y" → proceed to the command-specific steps below.
-- "N" → stop and ask what the user wants to change.
+Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp tục.
+- "Y" → tiếp tục sang các bước riêng của lệnh bên dưới.
+- "N" → dừng lại và hỏi người dùng muốn thay đổi gì.
 
 
-### Generate
+### Quy tắc nội dung — chống jargon kỹ thuật *(áp dụng cho mọi PRD sinh ra)*
 
-Write `specs/{domain}/{prd-slug}/prd.md`:
+**1. PRD platform-agnostic — chỉ mô tả WHAT (nghiệp vụ), KHÔNG mô tả HOW (kỹ thuật).**
+Viết AC / Business Rule / Business Logic theo *kết quả nghiệp vụ*, KHÔNG nhét chi tiết triển khai (API, JWT/token, endpoint, HTTP status, tên class/bảng/cột DB, query, spinner, animation…). Những thứ đó thuộc **Tech Docs** (kỹ thuật) hoặc **Design Spec** (giao diện).
 
-```markdown
-# PRD — {Feature Name}
+| ✅ Viết trong PRD (nghiệp vụ) | ❌ KHÔNG viết trong PRD |
+|---|---|
+| "Đăng nhập thành công → truy cập được tính năng" | "API trả về JWT token" ← Tech Docs |
+| "Sai mật khẩu 5 lần → khoá tài khoản 30 phút" | "Click button → hiện toast" ← Design Spec |
+| "Phiên hết hạn → yêu cầu xác thực lại" | "Hiển thị spinner khi loading" ← Design Spec |
 
-**Version**: 1.0
-**Status**: draft
-**Domain**: {domain}
-**Ticket**: {TICKET_PREFIX}-{N} (if available)
-**Date**: {date}
+- Nếu PO đưa chi tiết UI (màu, layout, animation) → **nhắc**: *"Chi tiết UI này thuộc Design Spec, không thuộc PRD. Ghi nhận để tạo Design Spec sau."*
+- Enum/thuật ngữ kỹ thuật ĐÃ chuẩn hoá trong domain-knowledge (vd `userType`, `TYPE_1`) thì giữ nguyên gốc — đây là từ vựng nghiệp vụ, KHÔNG phải jargon triển khai.
 
-## 1. Problem Statement
-{from product-definition}
+**2. Terminology — bám từ điển dự án.**
+- Thay mọi **banned term** bằng canonical term (xem `business-dictionary.md` § Banned Terms); ghi chú việc thay ở mục **Giả định AI**.
+- Status/Enum → lấy đúng giá trị trong `core-entities.md` (Enum Registry).
+- **Thuật ngữ MỚI**: nếu input PO có từ chưa có trong `business-dictionary.md` và lặp ≥2 lần → **DỪNG, hỏi PO** (nghĩa là gì / canonical term / có thêm vào từ điển không) trước khi tiếp tục.
 
-## 2. Goals & Non-Goals
+**3. Cross-reference bắt buộc.** Mọi chỗ nhắc TICKET-ID khác → inline link `[TICKET-ID](./file.md)` nếu file PRD tồn tại; không để plain text.
 
-### Goals
-- {goal 1}
+### Generate
 
-### Non-Goals
-- {non-goal 1}
+Sinh PRD theo đúng cấu trúc chuẩn dưới đây (template canonical: `templates/prd.template.md`). Quy ước bắt buộc:
+
+- **Ngôn ngữ:** heading + nội dung viết tiếng Việt (giữ thuật ngữ kỹ thuật/Enum nguyên gốc).
+- **Tiêu đề file:** `# {TICKET}-{N} {Feature Name}` — KHÔNG thêm tiền tố "PRD —".
+- **Tên file ghi ra:** `specs/{domain}/{prd-slug}/{TICKET}-{prd-slug}.md` (vd `SEG01-segment-scoring-service.md` — KHÔNG đặt tên `prd.md`; bố cục feature-package — mọi artifact của feature nằm chung folder này, PRD là file `.md` duy nhất ở gốc folder).
+- **Business Rule:** đặt BÊN TRONG từng Use Case (không gom thành mục phẳng), bảng 3 cột `ID | Business Rule | Business Logic`; ID theo dạng `{TICKET}-{N}-UC{n}-BR{m}` (đánh số BR liên tục xuyên suốt các UC, không reset mỗi UC).
+- **Acceptance Criteria:** danh sách phẳng `**AC{n}:**`, văn xuôi — KHÔNG ép Given/When/Then.
+- **Liên kết:** trỏ tới PRD/tài liệu liên quan bằng link tương đối; trỏ `core-entities` / `business-dictionary` ở mục Tài liệu tham khảo.
+- **Giả định AI:** nếu phát hiện độ vênh/giả định chưa được PO chốt → liệt kê thành `Q1…Qn` để PO xác nhận; nếu mọi thứ đã rõ từ product-definition → ghi "Không có — toàn bộ nội dung đã được PO xác nhận".
+
+Template (cấu trúc đầu ra — single-source từ `templates/prd.template.md`):
+
+````markdown
+# {TICKET}-{N} {Feature Name}
+
+<!--
+  Template này được sử dụng bởi workflow /generate-prd.
+  AI Agent sẽ điền các section dựa trên input từ PO.
+  Các placeholder {…} cần được thay thế bằng nội dung thực tế.
+
+  FORMAT CHUẨN: Business Rule = bảng 3 cột
+  ID | Business Rule | Business Logic (KHÔNG tách Business Logic ra khối riêng).
+
+  TERMINOLOGY:
+  - Tuân thủ 100% từ điển project: specs/domain-knowledge/business-dictionary.md
+    (KHÔNG dùng từ điển của project khác). Thay banned term bằng canonical term;
+    nếu phát hiện banned term trong input PO → thay + ghi chú trong "Giả định AI".
+  - Status/Enum values → tham chiếu core-entities.md (Enum Registry).
+
+  CROSS-REFERENCE (BẮT BUỘC): Bất kỳ chỗ nào nhắc đến một tính năng/ticket khác
+    (pre-condition, business rule, giả định, AC, hay bất kỳ section nào) → PHẢI gắn inline link:
+      [TICKET-ID khác](../{prd-slug-khác}/{TICKET-ID-khác}-{prd-slug-khác}.md)
+    Không để TICKET-ID dạng plain text nếu tồn tại file PRD tương ứng. (Mỗi PRD nằm trong feature-package riêng nên link trỏ sang folder anh em `../{prd-slug-khác}/`.)
+    Ngoài ra, ghi rõ quan hệ phụ thuộc trong "Tài liệu tham khảo" ở Appendix.
+
+  NEW TERM DETECTION: Nếu input PO xuất hiện thuật ngữ CHƯA CÓ trong business-dictionary.md
+    và lặp lại ≥ 2 lần → DỪNG lại, hỏi PO confirm trước khi tiếp tục:
+      + Thuật ngữ đó nghĩa gì trong ngữ cảnh hệ thống?
+      + English term chuẩn nên dùng là gì?
+      + Có cần bổ sung vào business-dictionary.md không?
+    Sau khi PO confirm → cập nhật business-dictionary.md (nếu PO đồng ý) rồi mới tiếp tục.
+
+  NUMBERING:
+  - UC ID: {TICKET}-{N}-UC{n}  (n bắt đầu từ 1, tăng theo từng use case)
+  - BR ID: {TICKET}-{N}-UC{n}-BR{m}  (m tăng LIÊN TỤC xuyên suốt PRD, KHÔNG reset mỗi UC)
+-->
 
-## 3. User Stories
+---
 
-As a {persona}, I want to {action} so that {benefit}.
+## Metadata
 
-## 4. Use Cases
+| Field         | Value                                    |
+|---------------|------------------------------------------|
+| **PRD ID**    | {TICKET}-{N}                             |
+| **Version**   | 1.0                                      |
+| **Status**    | draft                                    |
+| **Author**    | AI-assisted                              |
+| **Domain**    | {domain}                                 |
+| **Created**   | {date}                                   |
+| **Updated**   | {date}                                   |
+| **Jira Ticket** | [{TICKET}-{N}]({ticket_url})            |
+| **API Source** | *(để trống nếu greenfield — chỉ điền `existing` khi PRD bọc một API đã chạy production)* |
 
-| UC-ID | Name | Priority | Description |
-|-------|------|----------|-------------|
-| {DOMAIN}-UC1 | {name} | High | {description} |
+---
 
-## 5. Business Rules
+# Feature
 
-| BR-ID | Rule | UC |
-|-------|------|----|
-| BR-1 | {rule} | UC1 |
+**{Feature Name}**
 
-## 6. Acceptance Criteria
+{Đoạn mô tả tổng quan: feature làm gì, cho ai, giải quyết vấn đề gì — lấy từ product-definition.}
 
-### {DOMAIN}-UC1: {Name}
-- AC1: Given {context}, when {action}, then {result}
+---
 
-## 7. Out of Scope
-{from product-definition}
+# 1. Tổng quan
 
-## 8. Cross-Service Dependencies
-{from product-definition}
+## a. User Story
 
-## 9. Open Questions
-- [ ] {question requiring clarification}
-```
+- **Là một (As a)** {persona}
+- **Tôi muốn (I want to)** {action}
+- **Để (So that)** {benefit}
 
-### Output
+## b. Phạm vi
 
-```
-✅ PRD created: specs/{domain}/{prd-slug}/prd.md
-Status: draft
-```
+**In Scope**
+- {hạng mục trong phạm vi 1}
+- {hạng mục trong phạm vi 2}
 
-# Report Footer — Standard Command Output Format
+**Out of Scope** *(chỉ thêm khi có ranh giới cần nói rõ)*
+- {hạng mục ngoài phạm vi + lý do / chủ sở hữu}
 
-Every command report must end with this standard footer section.
+---
 
-## Status Badge
+# 2. Acceptance Criteria
 
-Choose one based on outcome:
-- `✅ Complete` — all steps succeeded, no issues found
-- `❌ Failed` — command could not complete due to a blocking error
-- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.}
 
-## Output Artifacts
+**AC2:** {…}
 
-List every file created or modified by this command:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({brief description})
-  {created|updated} {file-path} ({brief description})
-```
+---
 
-If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+# 3. Use Case
 
-## Pipeline Position
+#### {TICKET}-{N}-UC1: {Tên use case}
 
-Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
-so the user always sees where this command sits in the end-to-end flow:
+**Actor:** {actor}
 
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
+**Description:** {mô tả luồng}
 
-Find the current command in this phase legend and mark **its** phase in the map above:
+**Pre-condition:**
+- {điều kiện trước 1}
 
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
+**Post-condition:**
+- {kết quả sau 1}
 
-For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+**Business Rule**
 
-**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
-**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+| ID | Business Rule | Business Logic |
+|----|---------------|----------------|
+| {TICKET}-{N}-UC1-BR1 | {luật ngắn gọn} | - {logic chi tiết, xuống dòng bằng `<br/>`}<br/>- {…} |
+| {TICKET}-{N}-UC1-BR2 | {…} | - {…} |
 
-## Next Command Suggestion
+---
 
-Suggest the logical next command based on workflow phase:
+#### {TICKET}-{N}-UC2: {Tên use case}
+
+{lặp cấu trúc UC như trên; BR đánh số tiếp tục BR3, BR4…}
 
-| Current command         | Suggest next                                  |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` to start your first feature |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
-| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
-| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
-| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
-| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
-| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
-| /dev-smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
-| /fix-bug                | Create PR and link to ticket                  |
-| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
-| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
-| /learn                  | Continue working — lesson applies on next command |
-| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
-
-Format the footer as:
-```
 ---
-Status   : {badge}
-{Output Artifacts block}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {suggested command with example arguments}
-```
-*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
 
+# 4. UI/UX Guidelines
 
----
+## a. User Flow
 
-## /refine-prd — Analyze PRD Through 4 Review Lenses
+```mermaid
+flowchart TD
+    START(["{điểm bắt đầu}"]) --> A{"{điểm quyết định}"}
+    A -->|{nhánh}| B["{bước}"]
+```
 
-Performs a structured multi-perspective analysis of a PRD and writes findings to a YAML file for human review.
+## b. Wireframe
 
-### Gate
+### Screen 1: {Tên màn}
 
-<!-- Directory: specs/*/*/prd.md -->
-# Gate — Universal Entry Procedure
+| Thành phần | Chi tiết |
+|------------|----------|
+| **Screen** | {tên/ngữ cảnh màn} |
+| **Components** | - {thành phần 1}<br/>- {thành phần 2} |
+| **Actions** | - {hành động 1 → kết quả}<br/>- {hành động 2 → kết quả} |
 
-Every command must execute this gate before proceeding with its specific logic.
+---
 
-## Step 0 — Sub-Agent Mode Check
+### Screen 2: {Tên màn}
 
-Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+{lặp bảng như trên cho từng màn}
 
-1. Attempt to parse `$ARGUMENTS` as JSON.
-2. If it parses successfully **and** contains `"_agent_mode": true`:
-   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
-   - Set target file = `payload.target_file`
-   - Set loaded context = `payload.context` (do NOT run context-loader.md)
-   - Set UC scope = `payload.uc_id` (process only this UC)
-   - Set line range = `payload.uc_section` (read only that PRD section)
-   - Proceed directly to the command-specific logic.
-3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+---
 
-## Step 0-B — Model Check
+# Appendix
 
-*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+## Input gốc từ PO
 
-Complex generation and review commands require strong reasoning.
-Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+> {Trích nguyên văn input/ghi chú gốc của PO + đường dẫn product-definition nguồn.}
 
-Display and wait for response:
+## Tài liệu tham khảo
 
-```
-⚙️  MODEL CHECK
-──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (or latest Opus model)
-  Why needed   : Spec analysis, architecture review, code generation
-                 require deep reasoning. Smaller models miss edge cases.
+- [{TICKET liên quan}](../{prd-slug-khác}/{TICKET-ID-khác}-{prd-slug-khác}.md) — {quan hệ: pre-condition / overlapping / related…}
+- Từ điển nghiệp vụ: `{path}/business-dictionary.md`
+- Domain knowledge: `{path}/{domain}.md`
 
-  To switch in Claude Code:
-    • Settings → Model → select "claude-opus"
-    • or: /model → choose claude-opus
+## Existing API Contract *(CHỈ brownfield — điền khi API Source = existing; greenfield BỎ QUA cả section này)*
 
-  Running on claude-opus?
-    Y — yes, on claude-opus → proceed
-    S — skip check (I accept lower quality risk with current model)
-──────────────────────────────────────────────────────────────────
-```
+<!--
+  Chỉ dùng khi PRD bọc một API đã tồn tại trên hệ thống. PO ghi lại contract để:
+  - /generate-bdd (system) dùng trực tiếp làm input — không cần tổng hợp từ FE/App BDD;
+  - /generate-tech-docs chạy mode reverse-document (mô tả lại as-is, không design mới);
+  - /review-tech-docs bỏ qua cổng T7 cross-team sign-off (contract đã cố định).
+  Nếu greenfield (thiết kế mới) → xoá toàn bộ section này.
+-->
 
-- "Y" → proceed to Step 1.
-- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
-- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+| Method | Path | Auth | Request | Response |
+|--------|------|------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/path} | {Bearer / none} | `{ field: type }` | `{ field: type }` |
 
-## Step 1 — Resolve Target File
+**Error responses:**
 
-1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
-2. If `$ARGUMENTS` is a **bare UC-ID / ticket ID / partial name** (no path) → resolve it to a file by globbing the feature-package layout. The `{prd-slug}` is **not known yet**, so use a `*` wildcard for that segment, and a recursive `**` under `bdd/` so the platform subfolders (`bdd/web/`, `bdd/app/`, `bdd/system/`) are all covered:
-   - **BDD commands** (target is a `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — or `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` if the domain is also unknown. If a platform/scope is implied by the command (e.g. a system tech-doc needs the `system/` BDD), prefer the match under that platform subfolder.
-   - **PRD commands** (target is `prd.md`): `{specs_dir}/{domain}/*/prd.md` (match the feature folder whose id corresponds), else `{specs_dir}/*/*/prd.md`.
-   - **tech-docs commands**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
-   - **design-spec commands**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+| HTTP Status | Error Code | Khi nào xảy ra |
+|-------------|------------|----------------|
+| {4xx/5xx} | {ERR_CODE} | {condition} |
 
-   Once a file matches: set it as the target **and** record `domain` + `prd_slug` from its path (per the extraction rule in `context-loader.md` Step 1 — `prd_slug` = first segment after `{specs_dir}/{domain}/`). Every path the command later reads or writes (sibling BDD/tech-docs/design-spec/trace) uses **that resolved `prd_slug`**, so all artifacts stay in one feature package. If several files match (e.g. multiple platforms), pick per the command's platform/scope or list them and ask.
-3. If `$ARGUMENTS` is empty or no match found:
-   - List files in the relevant directory for this command (e.g., `specs/*/*/prd.md` for PRD commands, `specs/*/*/bdd/**/*.feature` for BDD commands).
-   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
-   - Wait for user selection before continuing.
+## Giả định AI
 
-## Step 2 — Execute Context Loader
+> {Giả định / độ vênh AI phát hiện khi đối chiếu product-definition với domain-knowledge — cần PO review. AI KHÔNG tự hoà giải.}
 
-Load all project context by following the procedure in `steps/context-loader.md`.
-Store all loaded context in memory for use throughout this command session.
+- **Q1 — [AI DRAFT] {tiêu đề}:** {mô tả độ vênh + nguồn}. **Cần PO chốt {điều gì}.**
 
-## Step 3 — CHECKPOINT
+_(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã được PO xác nhận qua Product Definition.")_
 
-After completing Steps 1 and 2, display a summary and wait for confirmation:
+---
 
-```
-CHECKPOINT
------------
-Target     : {resolved file path}
-Project    : {project.name from project-context.yaml}
-Tech stack : {language} / {framework}
-Module     : {module if set, else "not configured"}
-Domains    : {comma-separated domain list}
+# Change Log
 
-Proceed? (Y/N)
-```
+### v1.0 — {mô tả} ({date})
 
-Wait for explicit "Y" or "N" from the user before continuing.
-- "Y" → proceed to the command-specific steps below.
-- "N" → stop and ask what the user wants to change.
-
-
-### Analyze — 4 Lenses (run all four perspectives)
-
-#### QA Lens — Test Coverage & Edge Cases
-Evaluate:
-- Are all acceptance criteria testable and measurable?
-- Are edge cases and error scenarios specified?
-- Are boundary conditions defined?
-- Is there ambiguity in expected behavior?
-
-#### DEV Lens — Technical Clarity & Feasibility
-Evaluate:
-- Are API inputs/outputs clearly defined?
-- Are business rules unambiguous enough to implement?
-- Are there performance or scalability concerns?
-- Are cross-service dependencies fully described?
-- Is there anything technically infeasible or risky?
-
-#### SA Lens — Architecture & Design
-Evaluate:
-- Does this fit the existing architecture?
-- Are there design patterns or constraints to apply?
-- Is data modeling clear (entities, relationships)?
-- Are there security or auth implications?
-
-#### PO Lens — Business Value & Scope
-Evaluate:
-- Is scope clearly bounded?
-- Are priorities clear?
-- Are success metrics defined?
-- Are stakeholder needs fully captured?
-- Any scope creep risk?
-
-### Write Output
-
-Derive the output filename from the PRD slug:
-- PRD file: `specs/payment/create-invoice/prd.md` → output: `.agent/review/create-invoice-findings.yaml`
-- Rule: take the PRD's parent folder name (the `prd-slug`), append `-findings.yaml`
-
-Write findings to `.agent/review/{prd-slug}-findings.yaml`:
-
-```yaml
-# Generated by /refine-prd
-# Review each finding and mark: accepted / rejected / needs_discussion
-prd_source: "specs/{domain}/{prd-slug}/prd.md"
-generated_at: "{ISO datetime}"
-status: "pending_review"
-
-findings:
-  - id: "F001"
-    lens: "QA"           # QA | DEV | SA | PO
-    severity: "major"    # critical | major | minor
-    section: "§6. Acceptance Criteria"
-    finding: "{Clear description of the gap or issue}"
-    suggestion: "{Specific actionable improvement}"
-    status: "pending"    # pending | accepted | rejected | needs_discussion
-
-  - id: "F002"
-    lens: "DEV"
-    severity: "minor"
-    section: "§8. Cross-Service Dependencies"
-    finding: "{finding}"
-    suggestion: "{suggestion}"
-    status: "pending"
-
-summary:
-  total_findings: {N}
-  by_severity:
-    critical: {N}
-    major: {N}
-    minor: {N}
-  by_lens:
-    QA: {N}
-    DEV: {N}
-    SA: {N}
-    PO: {N}
-  recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
-```
+| Mục | Thay đổi |
+|-----|----------|
+| — | Bản đầu — sinh từ product-definition. |
 
-### Report to User
+---
 
-```
-/refine-prd Complete — {PRD name}
+<!--
+  NEXT STEPS:
+  Khi PRD được approve (status: approved), chạy:
+  /generate-bdd "specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
+  để sinh BDD feature specs từ PRD này.
+-->
 
-Findings: {total} total
-  🔴 Critical: {N}  🟡 Major: {N}  🟢 Minor: {N}
+````
 
-Top issues:
-  [F001] QA/major — {brief description}
-  [F002] DEV/minor — {brief description}
+### Output
 
-Review file: .agent/review/{prd-slug}-findings.yaml
-→ Open with Review Board extension (right-click file) to accept/reject each finding
-→ After review: update PRD and run /generate-bdd
+```
+✅ Đã tạo PRD: specs/{domain}/{prd-slug}/{TICKET}-{prd-slug}.md
+Status: draft
 ```
 
-# Report Footer — Standard Command Output Format
+# Report Footer — Định dạng output chuẩn cho mọi lệnh
 
-Every command report must end with this standard footer section.
+Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
 
 ## Status Badge
 
-Choose one based on outcome:
-- `✅ Complete` — all steps succeeded, no issues found
-- `❌ Failed` — command could not complete due to a blocking error
-- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+Chọn một theo kết quả:
+- `✅ Complete` — mọi bước thành công, không có vấn đề
+- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
+- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
 
 ## Output Artifacts
 
-List every file created or modified by this command:
+Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
 ```
 Output Artifacts:
-  {created|updated} {file-path} ({brief description})
-  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({mô tả ngắn})
+  {created|updated} {file-path} ({mô tả ngắn})
 ```
 
-If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
 
 ## Pipeline Position
 
-Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
-so the user always sees where this command sits in the end-to-end flow:
+In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
+để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
 
 ```
 Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
 ```
 
-Find the current command in this phase legend and mark **its** phase in the map above:
+Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
 
 | Phase | Commands |
 |-------|----------|
@@ -504,59 +395,72 @@ Find the current command in this phase legend and mark **its** phase in the map
 | QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
 | Trace Audit | `/validate-traces` |
 
-For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
 `Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
 
-**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
-**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
+**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
 
-## Next Command Suggestion
+## Gợi ý lệnh tiếp theo
 
-Suggest the logical next command based on workflow phase:
+Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 
-| Current command         | Suggest next                                  |
+| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
 |-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` to start your first feature |
+| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
 | /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
-| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
-| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
 | /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
-| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
+| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
-| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
+| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
 | /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
 | /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
-| /dev-smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
-| /fix-bug                | Create PR and link to ticket                  |
-| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
-| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
-| /learn                  | Continue working — lesson applies on next command |
-| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
-
-Format the footer as:
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
+| /dev-smoke-test             | Tạo PR và link tới ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
+| /fix-bug                | Tạo PR và link tới ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
+| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
+| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
+
+Định dạng footer như sau:
 ```
 ---
 Status   : {badge}
-{Output Artifacts block}
+{khối Output Artifacts}
 Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {suggested command with example arguments}
+           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {lệnh gợi ý kèm ví dụ tham số}
 ```
-*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
+
+
+---
+
+## /refine-prd — Phân tích PRD qua 4 lăng kính review
+
+Lệnh này thực thi **y hệt** `commands/refine-prd.md` — không nhân bản logic ở đây để tránh lệch schema findings.
+
+`commands/refine-prd.md` bao gồm:
+- Phân tích PRD bằng 4 lăng kính **fan-out đa sub-agent** (QA / DEV / SA / PO) + vòng completeness-critic (1 lần chạy ra đủ finding).
+- Ghi findings YAML với **schema đầy đủ** (`uc_id`, `quote`, `auto_fixable`) — bắt buộc cho source-jump và nút "Apply to PRD" của Review Board.
+- **Resume Mode** (`--resume`): áp dụng findings đã accept → bump version → ghi changelog → reset `draft`.
 
+→ **Đọc và tuân theo `commands/refine-prd.md`** với cùng `$ARGUMENTS`.