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

package/commands/review-context.md

@@ -1,152 +1,152 @@
-# /review-context — Review PRD or BDD for Quality & Consistency
+# /review-context — Review PRD hoặc BDD về Chất lượng & Tính nhất quán
 
-**READ-ONLY analysis mode — writes a findings file, does NOT modify the target.**
-**Use `--resume` to apply accepted findings.**
+**Chế độ phân tích READ-ONLY — ghi file findings, KHÔNG sửa target.**
+**Dùng `--resume` để áp dụng các finding được chấp nhận.**
 
 ## Gate
-# Gate — Universal Entry Procedure
+# 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ì.
 
 
-*Note: For this command, the target in Step 1 is either a `.md` PRD file or a `.feature` BDD file.
-If the path is a `prd.md` under `{paths.specs_dir}/{domain}/{prd-slug}/` → PRD Review Mode.
-If the path ends with `.feature` → BDD Review Mode.
-If `$ARGUMENTS` contains `--resume` → skip to Resume Mode below.
-If `$ARGUMENTS` contains `--fix` → skip to Fix Mode below (apply all auto-fixable findings immediately).*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một file PRD `.md` hoặc file BDD `.feature`.
+Nếu path là file PRD (`{TICKET-ID}-{prd-slug}.md` — file `.md` ở gốc feature folder `{paths.specs_dir}/{domain}/{prd-slug}/`) → PRD Review Mode.
+Nếu path kết thúc bằng `.feature` → BDD Review Mode.
+Nếu `$ARGUMENTS` chứa `--resume` → bỏ qua sang Resume Mode bên dưới.
+Nếu `$ARGUMENTS` chứa `--fix` → bỏ qua sang Fix Mode bên dưới (áp dụng ngay mọi finding auto-fixable).*
 
 ## Context
-# Context Loader — Load All Project Context
+# Context Loader — Nạp toàn bộ context dự án
 
-Execute these steps in order. Store everything in memory for the duration of the command session.
+Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nhớ trong suốt phiên làm việc của lệnh.
 
-**Priority guide (anti-lost-in-middle):**
-- Steps 1–2 are PROJECT-CONFIG — loaded first, resolve all paths and metadata.
-- Step 3 is CRITICAL — architecture + coding standards, the highest-priority facts for generation.
-- Step 4 is SAFETY — data protection rules, enforced silently for the entire session.
-- Steps 5–6 are DOMAIN KNOWLEDGE — terminology and entity definitions.
-- Step 7 is the WORKING MEMORY RECAP — locks critical facts into the top of working memory.
+**Hướng dẫn ưu tiên (chống lost-in-middle):**
+- Bước 1–2 là PROJECT-CONFIG — nạp trước, phân giải mọi path và metadata.
+- Bước 3 là CRITICAL — kiến trúc + coding standards, là các sự thật ưu tiên cao nhất khi sinh nội dung.
+- Bước 4 là SAFETY — quy tắc bảo vệ dữ liệu, thực thi ngầm suốt cả phiên.
+- Bước 5–6 là DOMAIN KNOWLEDGE — thuật ngữ và định nghĩa entity.
+- Bước 7 là WORKING MEMORY RECAP — chốt các sự thật quan trọng lên đầu bộ nhớ làm việc.
 
 ---
 
-## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+## Bước 1 — [PROJECT-CONFIG] Nạp project-context.yaml
 
-Read `.agent/project-context.yaml`. Extract and store:
+Đọc `.agent/project-context.yaml`. Trích xuất và lưu:
 
 **Tech Stack:**
-- `tech_stack.language` → active language (e.g., Java 17, TypeScript, C#, Go)
-- `tech_stack.framework` → active framework (e.g., Spring Boot 3.2, Angular 17, .NET 8)
-- `tech_stack.build_tool` → build tool (e.g., Maven, npm, dotnet, go)
-- `tech_stack.test_framework` → test framework (e.g., JUnit 5 + Mockito, Jest, xUnit)
-- `tech_stack.database` → database (e.g., PostgreSQL, MySQL, MongoDB)
-- `tech_stack.module` → active module profile (e.g., java-spring, angular, dotnet, golang, context-engineering)
+- `tech_stack.language` → ngôn ngữ đang dùng (vd: Java 17, TypeScript, C#, Go)
+- `tech_stack.framework` → framework đang dùng (vd: Spring Boot 3.2, Angular 17, .NET 8)
+- `tech_stack.build_tool` → build tool (vd: Maven, npm, dotnet, go)
+- `tech_stack.test_framework` → test framework (vd: JUnit 5 + Mockito, Jest, xUnit)
+- `tech_stack.database` → database (vd: PostgreSQL, MySQL, MongoDB)
+- `tech_stack.module` → module profile đang dùng (vd: java-spring, angular, dotnet, golang, context-engineering)
 
 **Conventions:**
-- `conventions.build_command` → how to compile/build
-- `conventions.test_command` → how to run tests
-- `conventions.service_run` → how to start the service
-- `conventions.ticket_prefix` → ticket ID prefix (e.g., PROJ, FEAT, UC)
+- `conventions.build_command` → cách compile/build
+- `conventions.test_command` → cách chạy test
+- `conventions.service_run` → cách khởi động service
+- `conventions.ticket_prefix` → tiền tố ticket ID (vd: PROJ, FEAT, UC)
 
 **Domains:**
-- `domains` → list of active business domains
-
-**Paths (if present):**
-- `paths.specs_dir` → spec artifacts root — PRD, BDD, tech-docs, design-spec. Structure: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
-- `paths.refinement_dir` → findings/review output dir
-- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
-- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
-- `paths.product_definitions_dir` → product definitions root
-- `paths.domain_knowledge_dir` → domain knowledge root
-- `paths.business_dictionary` → path to business-dictionary.md
-- `paths.core_entities` → path to core-entities.md
-- `paths.tech_docs_dir` → technical documentation root (merged with specs_dir in feature-package layout — tech-docs live under `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
-- `paths.trace_dir` → trace state directory; structure: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`
-
-If `paths` section is absent, use these defaults:
+- `domains` → danh sách các business domain đang hoạt động
+
+**Paths (nếu có):**
+- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
+- `paths.refinement_dir` → thư mục output cho findings/review
+- `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
+- `paths.product_definitions_dir` → gốc product definition
+- `paths.domain_knowledge_dir` → gốc domain knowledge
+- `paths.business_dictionary` → path tới business-dictionary.md
+- `paths.core_entities` → path tới core-entities.md
+- `paths.tech_docs_dir` → gốc tài liệu kỹ thuật (gộp với specs_dir trong bố cục feature-package — tech-docs nằm dưới `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
+- `paths.trace_dir` → thư mục trạng thái trace; cấu trúc: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`
+
+Nếu không có section `paths`, dùng các giá trị mặc định:
 - `specs_dir` = `specs`
 - `refinement_dir` = `.agent/review`
 - `qc_dir` = `docs`
@@ -158,184 +158,184 @@ If `paths` section is absent, use these defaults:
 - `tech_docs_dir` = `specs`
 - `trace_dir` = `.trace`
 
-Note: In the feature-package layout, `specs_dir` is the unified root. All spec artifact types (PRD, BDD, tech-docs, design-spec) live under `{specs_dir}/{domain}/{prd-slug}/`. The `prd-slug` is the feature-package folder name, not a separate config variable.
+Lưu ý: Trong bố cục feature-package, `specs_dir` là gốc thống nhất. Mọi loại spec artifact (PRD, BDD, tech-docs, design-spec) đều nằm dưới `{specs_dir}/{domain}/{prd-slug}/`. `prd-slug` là tên folder feature-package, không phải một biến config riêng.
 
-**How to extract `prd_slug` (works for ANY target file, regardless of nesting depth):** given a target path of the form `{specs_dir}/{domain}/{prd-slug}/...`, take the **first path segment after `{specs_dir}/{domain}/`** — i.e. the `{prd-slug}` position. Do NOT use the file's immediate parent folder, because BDD/tech-docs/design-spec artifacts are nested one or two levels deeper inside the package. Examples:
-- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
-- `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(NOT `system`)*
-- `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(NOT `web`)*
-- `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(NOT `tech-docs`)*
+**Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
+- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
+- `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
+- `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
 - `specs/payment/create-invoice/design-spec/PAY-design-spec-web.md` → `prd_slug = create-invoice`
 
-All sibling artifacts of one feature (PRD, every platform's BDD, the BE + FE tech-docs, the design-spec, and the trace TSV) therefore resolve to the **same `prd_slug`** — so a synthesized **system** BDD or **system/BE** tech-doc lands in the same `{specs_dir}/{domain}/{prd-slug}/` package as the web/app artifacts it was derived from.
+Mọi artifact cùng cấp của một feature (PRD, BDD của từng platform, tech-docs BE + FE, design-spec, và trace TSV) đều phân giải về **cùng một `prd_slug`** — nên một BDD **system** hay tech-doc **system/BE** được tổng hợp sẽ nằm chung package `{specs_dir}/{domain}/{prd-slug}/` với các artifact web/app mà nó được suy ra từ đó.
 
-If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+Nếu `tech_stack.module` được đặt, đồng thời nạp `.agent/modules/{module}/stack-profile.yaml` nếu file tồn tại.
 
 ---
 
-## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+## Bước 1.5 — [SERVICE ROUTING] Phân giải path service (chế độ umbrella)
 
-*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+*Bỏ qua hoàn toàn bước này nếu `setup.mode` không phải `"umbrella"` và không có section `services` trong project-context.yaml.*
 
-If `services` section is present:
+Nếu có section `services`:
 
-**1. Detect active domain** (in priority order):
-- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
-- Extract from target file path: `domain` = the first segment after the `specs_dir` base path; `prd_slug` = the next segment (the feature-package folder). This holds for any target depth — see the `prd_slug` extraction rule in Step 1.  
-  *(e.g., `specs/user/create-account/prd.md` **and** `specs/user/create-account/bdd/system/UC1.feature` both → domain = `user`, prd_slug = `create-account`)*
-- If `$ARGUMENTS` contains a path, extract the domain segment after `specs_dir`
+**1. Phát hiện active domain** (theo thứ tự ưu tiên):
+- Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
+- Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
+  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
+- Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
-**2. Route to service** — if active domain matches a key in `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
-- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
-- Store `active_service` = `services.{domain}.path`
-- Store `active_service_module` = `services.{domain}.module`
-- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+**2. Route tới service** — nếu active domain khớp với một key trong `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
+- Lưu `active_service` = `services.{domain}.path`
+- Lưu `active_service_module` = `services.{domain}.module`
+- Nếu service có `module` riêng → dùng nó làm `active_module` (override `tech_stack.module`)
 
-**3. Fallback** — if domain not detected or no matching service key:
-- Keep default paths from Step 1
-- Set `active_service = unresolved`
+**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
+- Giữ path mặc định từ Bước 1
+- Đặt `active_service = unresolved`
 
-**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
-- Override `paths.specs_dir` → `{spec_source}/specs` — **always when `spec_source` is set.** All spec artifacts (PRD, BDD, tech-docs, design-spec) live under the unified spec root in the shared spec repo using the feature-package layout: `{spec_source}/specs/{domain}/{prd-slug}/`. Every umbrella (FE/App/BE) reads from here. *(Per-service `specs/` only when there is no `spec_source`.)*
-- Override `paths.tech_docs_dir` → `{spec_source}/specs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). Tech-docs live at `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
+**4. Tự động override theo spec source** — nếu `setup.spec_source` được đặt VÀ path tương ứng chưa được set tường minh trong `paths:`:
+- Override `paths.specs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt.** Mọi spec artifact (PRD, BDD, tech-docs, design-spec) nằm dưới gốc spec thống nhất trong spec repo dùng chung theo bố cục feature-package: `{spec_source}/specs/{domain}/{prd-slug}/`. Mọi umbrella (FE/App/BE) đều đọc từ đây. *(`specs/` theo service chỉ khi không có `spec_source`.)*
+- Override `paths.tech_docs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt** (bước 2 không còn pin tech-docs theo service trong trường hợp này). Tech-docs nằm tại `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. Tech-design CHÍNH LÀ API contract liên team: BE viết ở đây, FE/App đọc nó từ cùng spec submodule tại `/generate-code --phase=integration`. *(tech-docs theo service chỉ xảy ra khi không có `spec_source` — repo BE thuần đa-service không có spec module dùng chung.)*
 - Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
 - Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 - Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
-- Override `paths.trace_dir` → `{spec_source}/.trace` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Internal structure: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace/{domain}/{prd-slug}/`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **luôn khi `spec_source` được đặt.** Trace TSV được gộp vào spec repo (một nơi authoritative duy nhất, không tách theo service) để PM/PO có một chỗ duy nhất quản lý trạng thái. Cấu trúc bên trong: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`. Các lệnh phía code (`/generate-code`, `/dev-run-test`, `/qc-run-test`) chạy từ `service_root` nhưng **ghi trace row của chúng vào `{spec_source}/.trace/{domain}/{prd-slug}/`** — giống như chúng đã push `feedback/` vào đó. *(`.trace` theo service chỉ khi không có `spec_source`.)*
 
-> **Why under `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** using the feature-package layout so every umbrella (FE/App/BE) and the PM read one source via `/sync`. In the feature-package layout, a single `specs/{domain}/{prd-slug}/` folder groups all artifact types for one PRD, making the spec repo self-contained and navigable by feature. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo. In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
+> **Vì sao đặt dưới `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, feedback của tester, **và trạng thái coverage `.trace/`** đều là **artifact liên team** — chúng nằm trong **spec repo dùng chung** theo bố cục feature-package để mọi umbrella (FE/App/BE) và PM đọc từ một nguồn qua `/sync`. Trong bố cục feature-package, một folder `specs/{domain}/{prd-slug}/` gom tất cả loại artifact của một PRD, giúp spec repo tự đủ và dễ điều hướng theo feature. Service submodule chỉ chứa **code** (+ tooling build/test). `.trace/` và `feedback/` là khu vực **ghi** của dev/QC trong spec repo. Ở chế độ single-service (không có `spec_source`), mọi thứ mặc định dưới gốc repo — vẫn là một repo.
 
 ---
 
-## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
 
-*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc context ở chế độ single-service.*
 
-When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
 
-**1. Locate service config** — try in priority order:
+**1. Định vị config của service** — thử theo thứ tự ưu tiên:
 - `{active_service}/.agent/project-context.yaml`
 - `{active_service}/project-context.yaml`
 
-**2. If found, override with service-specific values:**
+**2. Nếu tìm thấy, override bằng giá trị riêng của service:**
 
-| Variable | Source |
+| Biến | Nguồn |
 |----------|--------|
-| `conventions.test_command` | service's `conventions.test_command` |
-| `conventions.build_command` | service's `conventions.build_command` |
-| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
-| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs`); ignore any service-level `specs_dir`** (all spec artifacts are cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
+| `conventions.test_command` | `conventions.test_command` của service |
+| `conventions.build_command` | `conventions.build_command` của service |
+| `paths.trace_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/.trace`); bỏ qua mọi `trace_dir` cấp service.** Chỉ khi không có `spec_source`: `{active_service}/{service paths.trace_dir}` (mặc định `{active_service}/.trace`). |
+| `paths.specs_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/specs`); bỏ qua mọi `specs_dir` cấp service** (mọi spec artifact đều liên team, không bao giờ theo service ở chế độ này). Chỉ khi không có `spec_source`: `{active_service}/{service paths.specs_dir}` nếu được set, else dùng override ở Bước 1.5. |
 
-**3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
-- Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
-- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
+**3. Lưu** `service_root = {active_service}` làm mốc thư mục làm việc cho mọi lệnh phía sau:
+- Các lệnh shell (`/dev-run-test`, `/dev-gen-test`) chạy **bên trong** `service_root`
+- **File source/test** được ghi tương đối với `service_root`; **trace TSV** được ghi vào `{paths.trace_dir}` (là spec repo khi `spec_source` được đặt — một thao tác ghi liên-repo, commit/push vào spec submodule giống như `feedback/`).
 
-**4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
+**4. Nếu không tìm thấy config của service** — giữ mặc định umbrella, vẫn set `service_root = {active_service}` (luôn cần mốc path kể cả khi không có config override).
 
 ---
 
-## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+## Bước 2 — [PROJECT-CONFIG] Nạp module stack profile (có điều kiện)
 
-If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
-Merge framework-specific conventions (layer patterns, test patterns, naming rules) into the loaded context.
-If the file does not exist → skip silently.
+Nếu `tech_stack.module` được đặt, đọc `.agent/modules/{module}/stack-profile.yaml`.
+Merge các convention riêng của framework (layer pattern, test pattern, quy tắc đặt tên) vào context đã nạp.
+Nếu file không tồn tại → bỏ qua âm thầm.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
+## Bước 3 — [CRITICAL] Nạp CLAUDE.md (phân tầng: root + service overlay)
 
-*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+*Đây là context ưu tiên cao nhất — nó định nghĩa CÁCH viết code và tài liệu cho dự án này.*
 
-CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
-architecture/coding standards compose correctly. The agent always sits at the umbrella
-root, but the implementation code lives in a service submodule with its OWN stack,
-architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+CLAUDE.md được nạp theo **hai tầng** để các quy tắc toàn-umbrella và kiến trúc/coding standards
+riêng của service kết hợp đúng cách. Agent luôn đứng ở gốc umbrella, nhưng code triển khai nằm
+trong một service submodule với stack, kiến trúc, và convention RIÊNG của nó — nên CLAUDE.md của
+service phải thắng khi sinh code.
 
-**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
-Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
-whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
-single-service mode) the project's only architecture + coding standards.
+**Tầng 1 — [BASE] Root CLAUDE.md (toàn umbrella).**
+Đọc `CLAUDE.md` ở gốc repo. Coi nội dung của nó là **nền tảng dùng chung** cho cả umbrella —
+git convention, tư thế bảo vệ dữ liệu, quy tắc xuyên suốt, và (ở chế độ single-service) là
+kiến trúc + coding standards duy nhất của dự án.
 
-**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
-*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
-Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
-the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
-Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
-coding standards, and error handling. Layer-1 values that the service does not redefine
-(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+**Tầng 2 — [OVERLAY] Service CLAUDE.md (chỉ chế độ umbrella).**
+*Chỉ chạy nếu `service_root` đã được set ở Bước 1.6 (tức đã route tới một service thật).*
+Đọc `{service_root}/CLAUDE.md`. File này định nghĩa kiến trúc + coding standards của **stack
+thực sự đang được triển khai** (vd: `user-service` = java-spring, `web` = nextjs).
+Overlay nó lên trên Tầng 1: **khi có xung đột, giá trị của service THẮNG** cho kiến trúc,
+coding standards, và error handling. Các giá trị Tầng 1 mà service không định nghĩa lại
+(vd: git convention, banned pattern dùng chung toàn tổ chức) vẫn có hiệu lực.
 
-From the **merged** result, extract and store:
+Từ kết quả **đã merge**, trích xuất và lưu:
 
-- **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
-- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
+- **§1 Project Overview** → tên dự án, ngôn ngữ, framework, lệnh build/test, domains
+- **§2 Architecture** → thứ tự layer (vd: Controller → Facade → Service → Repository), quy tắc kiến trúc — *service overlay thắng*
+- **§3 Coding Standards** → quy tắc đặt tên (class, method), kiểu response wrapper, pattern bị cấm — *service overlay thắng*
+- **§5 Error Handling** → kiểu exception, mapping HTTP status code, tên class not-found exception — *service overlay thắng*
+- **§7 Git Conventions** → pattern đặt tên branch, format commit message — *lấy theo root trừ khi service định nghĩa lại*
 
-**Resolution rules:**
-- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
-- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
-- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
-- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
+**Quy tắc phân giải:**
+- Nếu cả hai tầng tồn tại → merge như trên; ghi `claude_md_source = root + {service_root}`.
+- Nếu chỉ có service overlay (không có root CLAUDE.md) → dùng file service một mình; `claude_md_source = {service_root}`.
+- Nếu `service_root` được set nhưng `{service_root}/CLAUDE.md` **thiếu** → fallback về root CLAUDE.md và gắn cờ ⚠️ trong recap Bước 7 (service không có định nghĩa kiến trúc/coding-standards — việc sinh code sẽ dùng mặc định umbrella, có thể sai stack).
+- Nếu cả hai đều không tồn tại → ghi nhận CLAUDE.md thiếu và tiếp tục chỉ với dữ liệu từ project-context.yaml.
 
 ---
 
-## Step 4 — [SAFETY] Load Data Protection Rules
+## Bước 4 — [SAFETY] Nạp quy tắc bảo vệ dữ liệu
 
-Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+Đọc `.agent/rules/data-protection.md` (hoặc `rules/data-protection.md` từ bản cài đặt framework).
 
-Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+Lưu các pattern file nhạy cảm — bạn **tuyệt đối không** đọc, ghi, hiển thị, hay tham chiếu nội dung từ các file khớp những pattern đó trong suốt cả phiên.
 
-If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+Nếu cả hai file đều không tồn tại → áp dụng mặc định built-in: không bao giờ truy cập `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
 
 ---
 
-## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+## Bước 5 — [DOMAIN] Nạp Business Dictionary (có điều kiện)
 
-Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+Kiểm tra file business dictionary có tồn tại không (dùng `paths.business_dictionary` đã phân giải ở Bước 1).
 
-If it exists, read it and extract:
-- **Canonical Terms** → complete list of approved terms and their definitions
-- **Banned Terms** → complete list of banned terms and their canonical replacements
-- **Status / Enum Registry** → allowed enum values per entity
+Nếu tồn tại, đọc và trích xuất:
+- **Canonical Terms** → danh sách đầy đủ các thuật ngữ chuẩn và định nghĩa
+- **Banned Terms** → danh sách đầy đủ các thuật ngữ bị cấm và bản thay thế chuẩn
+- **Status / Enum Registry** → các giá trị enum được phép theo từng entity
 
-Store the banned terms list for **active enforcement** throughout the command session:
-- When generating any text (PRD, BDD, code comments, tech docs), verify no banned terms appear
-- Replace banned terms with their canonical equivalents automatically
+Lưu danh sách banned term để **thực thi chủ động** suốt phiên làm việc của lệnh:
+- Khi sinh bất kỳ văn bản nào (PRD, BDD, comment code, tech docs), kiểm tra không có banned term nào xuất hiện
+- Tự động thay banned term bằng bản chuẩn tương đương
 
-If the file does not exist → skip silently. Do not warn or block.
+Nếu file không tồn tại → bỏ qua âm thầm. Không cảnh báo hay chặn.
 
 ---
 
-## Step 6 — [DOMAIN] Load Core Entities (conditional)
+## Bước 6 — [DOMAIN] Nạp Core Entities (có điều kiện)
 
-Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
-Default path: `specs/domain-knowledge/core-entities.md`.
+Kiểm tra file core entities có tồn tại tại `paths.core_entities` không (đã phân giải ở Bước 1).
+Path mặc định: `specs/domain-knowledge/core-entities.md`.
 
-If it exists, read it and store:
-- **Entity catalog** → for each entity: its name, purpose, owner service, key fields (name + type), business invariants, and relationships
-- **Field name registry** → canonical field names to use in generated code and documents
-- **Relationship map** → how entities relate to each other (1:N, N:N, embedded, etc.)
+Nếu tồn tại, đọc và lưu:
+- **Entity catalog** → với mỗi entity: tên, mục đích, service sở hữu, các field chính (tên + kiểu), business invariant, và quan hệ
+- **Field name registry** → tên field chuẩn dùng trong code và tài liệu được sinh ra
+- **Relationship map** → cách các entity liên hệ với nhau (1:N, N:N, embedded, v.v.)
 
-**How to use this catalog:**
-- When generating code: use the field names, types, and relationships defined here — do NOT infer from existing code
-- When generating PRD/BDD: reference entity names from this catalog for consistency
-- When generating tech-docs: use this catalog as the source-of-truth for entity definitions
+**Cách dùng catalog này:**
+- Khi sinh code: dùng tên field, kiểu, và quan hệ định nghĩa ở đây — KHÔNG suy đoán từ code có sẵn
+- Khi sinh PRD/BDD: tham chiếu tên entity từ catalog này để nhất quán
+- Khi sinh tech-docs: dùng catalog này làm nguồn chân lý cho định nghĩa entity
 
-If the file does not exist → skip silently.
+Nếu file không tồn tại → bỏ qua âm thầm.
 
 ---
 
-## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+## Bước 6.5 — [PLATFORM] Suy ra active_module và platform_type
 
-Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+Dùng `tech_stack.module` đã nạp ở Bước 1, suy ra và lưu hai biến để mọi lệnh phía sau dùng:
 
 ```
-active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
 ```
 
 | `platform_type` | Modules |
@@ -344,155 +344,155 @@ active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
 | `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
 | `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
 
-If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
+Nếu `tech_stack.module` rỗng hoặc không nhận diện được → set `platform_type = "unknown"` và gắn cờ ⚠️ trong recap Bước 7.
 
-These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
+Hai biến này (`active_module`, `platform_type`) là nguồn chuẩn cho mọi logic rẽ nhánh trong các lệnh cần hành vi riêng theo platform (dev-gen-test, debug, fix-bug, dev-smoke-test).
 
 ---
 
-## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+## Bước 6.7 — [GUARDRAILS] Nạp Project Lessons (có điều kiện)
 
-*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
-or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+*Các lỗi tích luỹ mà AI không được lặp lại trong dự án này. Chúng được bổ sung dần qua `/learn`
+hoặc được chấp nhận trong `/review-code`, `/fix-bug`, `/debug`.*
 
-Resolve the lessons file path:
-- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
-- Else default `specs/domain-knowledge/lessons-learned.md`
-- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+Phân giải path file lessons:
+- Dùng `paths.lessons_file` nếu được set (có thể bị service override ở chế độ umbrella, Bước 1.6)
+- Else mặc định `specs/domain-knowledge/lessons-learned.md`
+- Ở chế độ umbrella/service (khi `service_root` được set), nếu `paths.lessons_file` chưa set, mặc định `{service_root}/.agent/project-lessons.md`
 
-If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
-- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
-- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
-- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+Nếu file tồn tại, đọc và lưu TẤT CẢ lesson làm **GUARDRAIL ĐANG HOẠT ĐỘNG** cho phiên:
+- Coi **Rule** của mỗi lesson là ràng buộc cứng — cùng mức ưu tiên với coding standards trong CLAUDE.md (Bước 3).
+- Trước khi sinh hoặc sửa bất kỳ artifact nào (PRD, BDD, tech-doc, code, test), đối chiếu output với mọi lesson có `category` khớp lệnh hiện tại VÀ `scope` khớp target (domain / file).
+- Nếu output sinh ra vi phạm một lesson → sửa **trước khi** trình bày, và ghi rõ lesson nào (`L-NNN`) đã được áp dụng.
 
-If the file does not exist → skip silently (no lessons captured yet).
+Nếu file không tồn tại → bỏ qua âm thầm (chưa có lesson nào được ghi nhận).
 
 ---
 
-## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
+## Bước 7 — [RECAP] Working Memory Recap (chống lost-in-middle)
 
-After loading all context, synthesize and output a compact summary block.
-This recap ensures the most critical facts are stated at the END of context loading
-(recency effect — freshest in working memory when the task begins).
+Sau khi nạp toàn bộ context, tổng hợp và xuất một khối tóm tắt gọn.
+Recap này đảm bảo các sự thật quan trọng nhất được nêu ở CUỐI quá trình nạp context
+(hiệu ứng recency — tươi mới nhất trong bộ nhớ làm việc khi bắt đầu task).
 
-Output exactly this block:
+Xuất đúng khối này:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
-CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
+Layers    : {thứ tự layer từ CLAUDE.md §2 đã merge, vd: Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | chỉ {service_root} | chỉ root | ⚠️ service overlay THIẾU — dùng root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
-Lessons   : {loaded — N guardrails | none yet}
+Lessons   : {loaded — N guardrails | chưa có}
 Service   : {active_service} ({active_service_module}) | single-service
-Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
-Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
+Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —
+Status    : {FULL | PARTIAL — thiếu: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
-If any CRITICAL file is missing (CLAUDE.md), flag it clearly so the user can decide whether to proceed.
+Nếu bất kỳ file CRITICAL nào thiếu (CLAUDE.md), gắn cờ rõ ràng để người dùng quyết định có tiếp tục hay không.
 
 ---
 
-## Context Load Complete
+## Hoàn tất nạp Context
 
-After completing all steps, you have loaded:
-- Project identity, tech stack, module conventions
-- Architecture rules and layer order  ← **[CRITICAL — hold in working memory]**
-- Coding standards and naming conventions  ← **[CRITICAL — hold in working memory]**
-- Data protection rules (sensitive file patterns to never access)
-- Terminology rules with banned-term list  ← **[DOMAIN — apply to every generated word]**
-- Entity catalog (field names, types, invariants)  ← **[DOMAIN — use for code generation]**
-- All configured paths
+Sau khi hoàn thành tất cả các bước, bạn đã nạp:
+- Định danh dự án, tech stack, convention module
+- Quy tắc kiến trúc và thứ tự layer  ← **[CRITICAL — giữ trong bộ nhớ làm việc]**
+- Coding standards và quy tắc đặt tên  ← **[CRITICAL — giữ trong bộ nhớ làm việc]**
+- Quy tắc bảo vệ dữ liệu (pattern file nhạy cảm không bao giờ truy cập)
+- Quy tắc thuật ngữ kèm danh sách banned term  ← **[DOMAIN — áp dụng cho mọi từ được sinh ra]**
+- Entity catalog (tên field, kiểu, invariant)  ← **[DOMAIN — dùng khi sinh code]**
+- Toàn bộ path đã cấu hình
 
-Proceed to the next step of the calling command.
+Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 
 ---
 
-## Detect Review Mode
+## Phát hiện Review Mode
 
-After resolving the target file:
-- `.feature` file → **BDD Review Mode** (jump to BDD section)
-- `prd.md` under `{paths.specs_dir}/*/*/` → **PRD Review Mode** (continue below)
-- Unknown → ask: "Is this a PRD file or a BDD feature file? (prd/bdd)"
+Sau khi phân giải target file:
+- File `.feature` → **BDD Review Mode** (nhảy tới section BDD)
+- File `.md` ở gốc feature folder `{paths.specs_dir}/*/*/` (không phải dưới `bdd/`·`tech-docs/`·`design-spec/`) → **PRD Review Mode** (tiếp tục bên dưới)
+- Không xác định → hỏi: "Đây là file PRD hay file BDD feature? (prd/bdd)"
 
-Also check flags:
-- `--fix` present → after running all checks, apply `auto_fixable: true` findings immediately (skip Review Board)
-- `--resume` present → skip analysis entirely, go to Resume Mode
+Đồng thời kiểm tra flag:
+- Có `--fix` → sau khi chạy hết các check, áp dụng ngay các finding `auto_fixable: true` (bỏ qua Review Board)
+- Có `--resume` → bỏ qua phân tích hoàn toàn, sang Resume Mode
 
-Derive the output findings filename:
+Suy ra tên file findings output:
 - PRD: `{paths.refinement_dir}/{prd-slug}-review-context-findings.yaml`
 - BDD: `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`
 
 ---
 
-## Review Procedure
-# Exhaustive Review Fan-Out + Completeness Convergence
+## Quy trình Review
+# Review Fan-Out toàn diện + Hội tụ về độ đầy đủ
 
-**Why this exists:** A single-pass review never lists every issue at once — the model
-stops at "enough" findings, so each later review round surfaces *new* problems
-(whack-a-mole). This procedure forces the review to **converge in one command run**:
-fan out across review dimensions in parallel, then loop a completeness critic until a
-round produces nothing new, *before* writing the findings file.
+**Vì sao có cái này:** Một lượt review đơn không bao giờ liệt kê hết mọi vấn đề cùng lúc — model
+dừng ở mức "đủ" findings, nên mỗi vòng review sau lại lòi ra vấn đề *mới*
+(đập chuột chũi). Quy trình này ép review **hội tụ trong một lần chạy lệnh**:
+fan out song song theo các chiều review, rồi lặp một critic độ-đầy-đủ cho tới khi một
+vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
-The calling command supplies two things:
-- **DIMENSIONS** — the list of review dimensions to fan out over
-  (`/refine-prd` → the 4 lenses; `/review-context` → the P-checks or B-checks).
-- **FINDINGS SCHEMA** — the YAML shape each finding must follow (defined in the command).
+Lệnh gọi cung cấp hai thứ:
+- **DIMENSIONS** — danh sách các chiều review để fan out
+  (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check).
+- **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
 
-> **Sub-agent mode bypass:** If Gate Step 0 set `_agent_mode: true`, this whole
-> procedure is **skipped** — the orchestrator is already running one dimension/UC per
-> sub-agent. Run the command's checks directly on the scoped section and return findings.
+> **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
+> quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
+> sub-agent. Chạy các check của lệnh trực tiếp trên section đã giới hạn và trả về findings.
 
 ---
 
-## Phase 1 — Parallel dimension scan
+## Phase 1 — Quét dimension song song
 
-**How many sub-agents:** the agent *count* is not the completeness lever — breadth is
-fixed by the DIMENSION taxonomy (adding agents to the same dimension just re-finds the
-same issues), and *depth* is owned by the Phase 2 critic loop. Pick the **fan-out
-granularity** by target size, reusing the `steps/spawn-agent.md` thresholds:
+**Bao nhiêu sub-agent:** *số lượng* agent không phải là đòn bẩy độ đầy đủ — bề rộng được
+cố định bởi taxonomy DIMENSION (thêm agent vào cùng một dimension chỉ tìm lại cùng vấn đề),
+còn *độ sâu* thuộc về vòng lặp critic ở Phase 2. Chọn **độ mịn fan-out**
+theo kích thước target, tái dùng ngưỡng của `steps/spawn-agent.md`:
 
-| Target size | Granularity | Agent count |
+| Kích thước target | Độ mịn | Số agent |
 |-------------|-------------|-------------|
-| ≤ 3 UCs **and** ≤ 300 lines | one agent per DIMENSION over the whole file | = number of dimensions |
-| > 3 UCs **or** > 300 lines | one agent per **DIMENSION × UC-scope** (UCs + a PRD-global scope), batched to fit the agent cap | `dimensions × (UCs + 1)`, capped (see below) |
+| ≤ 3 UC **và** ≤ 300 dòng | một agent cho mỗi DIMENSION trên cả file | = số dimension |
+| > 3 UC **hoặc** > 300 dòng | một agent cho mỗi **DIMENSION × phạm vi UC** (các UC + một phạm vi PRD-global), gom batch để vừa giới hạn agent | `dimensions × (UCs + 1)`, có cap (xem dưới) |
 
-The larger granularity keeps each sub-agent's context small and its scan exhaustive on a
-single UC — which is what prevents misses on big PRDs.
+Độ mịn lớn hơn giữ context của mỗi sub-agent nhỏ và quét nó vét cạn trên một
+UC duy nhất — chính là điều ngăn bỏ sót trên các PRD lớn.
 
-> **Global (non-UC) sections — required in `DIMENSION × UC` mode.** Per-UC agents only
-> see one UC each, so PRD-wide sections that belong to no UC (scope, success metrics,
-> problem statement, terminology, glossary, changelog) would go unscanned. Whenever you
-> fan out per UC, also include a **"PRD-global"** scope (the non-UC sections, findings get
-> `uc_id: ""`) alongside the UC list. So the natural agent count is `dimensions × (UCs + 1)`.
-> (Not needed in the whole-file mode — there each agent already sees the global sections.)
+> **Các section global (không thuộc UC) — bắt buộc ở chế độ `DIMENSION × UC`.** Mỗi agent per-UC chỉ
+> thấy một UC, nên các section toàn-PRD không thuộc UC nào (scope, success metric,
+> problem statement, terminology, glossary, changelog) sẽ không được quét. Khi nào
+> fan out theo UC, cũng phải thêm một phạm vi **"PRD-global"** (các section không thuộc UC, finding nhận
+> `uc_id: ""`) bên cạnh danh sách UC. Nên số agent tự nhiên là `dimensions × (UCs + 1)`.
+> (Không cần ở chế độ whole-file — ở đó mỗi agent đã thấy các section global rồi.)
 
-### Agent cap — batch UCs when the fan-out gets too wide
+### Agent cap — gom batch các UC khi fan-out quá rộng
 
-`dimensions × (UCs + 1)` can explode on large PRDs (e.g. 6 checks × (8 UCs + 1) = 54
-agents). Cap the wave at **`AGENT_CAP = 12`** agents and batch UC scopes to fit:
+`dimensions × (UCs + 1)` có thể bùng nổ trên PRD lớn (vd 6 check × (8 UC + 1) = 54
+agent). Giới hạn mỗi wave ở **`AGENT_CAP = 12`** agent và gom batch các phạm vi UC cho vừa:
 
-1. Build the scope list = `[UC1, UC2, …, UCn, PRD-global]` (length `UCs + 1`).
-2. Compute scopes-per-agent-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
-   - If `groups ≥ UCs + 1` → no batching needed, run one agent per `DIMENSION × scope`.
-   - Else split the scope list into `groups` contiguous buckets of roughly equal size
-     (keep `PRD-global` in its own bucket if it fits; otherwise append it to the last
-     bucket). Each agent then handles **one DIMENSION over one bucket of UCs**.
-3. Resulting wave size = `dimensions × groups ≤ AGENT_CAP`.
+1. Dựng danh sách phạm vi = `[UC1, UC2, …, UCn, PRD-global]` (độ dài `UCs + 1`).
+2. Tính số-phạm-vi-mỗi-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
+   - Nếu `groups ≥ UCs + 1` → không cần batch, chạy một agent cho mỗi `DIMENSION × scope`.
+   - Else chia danh sách phạm vi thành `groups` bucket liền kề kích thước xấp xỉ bằng nhau
+     (giữ `PRD-global` ở bucket riêng nếu vừa; nếu không thì gắn vào bucket cuối).
+     Mỗi agent khi đó xử lý **một DIMENSION trên một bucket UC**.
+3. Kích thước wave kết quả = `dimensions × groups ≤ AGENT_CAP`.
 
-A batched agent reviews several UCs at once — still scoped far tighter than the whole
-file, so coverage stays high. `AGENT_CAP` is the only knob; raise it if the host allows
-more concurrency, lower it to save tokens. Whole-file mode (≤ 3 UCs) never hits the cap.
+Một agent đã batch review nhiều UC cùng lúc — vẫn giới hạn chặt hơn nhiều so với cả
+file, nên độ phủ vẫn cao. `AGENT_CAP` là núm chỉnh duy nhất; tăng nếu host cho phép
+concurrency nhiều hơn, giảm để tiết kiệm token. Chế độ whole-file (≤ 3 UC) không bao giờ chạm cap.
 
-Spawn the chosen sub-agents using the Agent tool (send them in a single message so they
-run concurrently). Each sub-agent gets a **fresh context window** and scans its scope
-through its **one** dimension only — deeper coverage than one session juggling every
-dimension at once (avoids lost-in-the-middle).
+Spawn các sub-agent đã chọn bằng Agent tool (gửi trong một message duy nhất để chúng
+chạy đồng thời). Mỗi sub-agent nhận một **context window mới** và quét phạm vi của nó
+chỉ qua **một** dimension duy nhất — độ phủ sâu hơn một session phải tung hứng mọi
+dimension cùng lúc (tránh lost-in-the-middle).
 
-Sub-agent prompt template (fill the braces):
+Template prompt cho sub-agent (điền vào các ngoặc):
 
 ```
 You are a {DIMENSION_NAME} reviewer. Read the full target file at {target_file}.
@@ -508,20 +508,20 @@ Return a JSON array of findings, each:
 Return [] if this dimension is clean. Return ONLY the JSON array.
 ```
 
-Collect every sub-agent's array into one consolidated list `ALL_FINDINGS`.
+Gom mảng findings của mọi sub-agent vào một danh sách hợp nhất `ALL_FINDINGS`.
 
 ---
 
-## Phase 2 — Completeness-critic convergence loop
+## Phase 2 — Vòng lặp hội tụ critic độ-đầy-đủ
 
-This is the anti-whack-a-mole step. Repeat until **two consecutive rounds add zero new
-findings**, or a hard cap of **3 rounds**, whichever comes first:
+Đây là bước chống đập-chuột-chũi. Lặp cho tới khi **hai vòng liên tiếp thêm 0 finding
+mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
 
-1. Spawn one **completeness-critic** sub-agent with the Agent tool. Give it:
-   - the full target file (`{target_file}`),
-   - the current `ALL_FINDINGS` list (so it knows what is already captured),
-   - the same slim context.
-   Prompt it:
+1. Spawn một sub-agent **completeness-critic** bằng Agent tool. Cho nó:
+   - toàn bộ target file (`{target_file}`),
+   - danh sách `ALL_FINDINGS` hiện tại (để nó biết những gì đã được ghi nhận),
+   - cùng context gọn đó.
+   Prompt nó:
    ```
    Here is a document and a list of issues already found. Read the WHOLE document.
    List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
@@ -530,142 +530,140 @@ findings**, or a hard cap of **3 rounds**, whichever comes first:
    Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
    nothing new.
    ```
-2. Append any genuinely new findings (not already in `ALL_FINDINGS`) to the list.
-3. If this round returned 0 new → increment the dry-round counter; else reset it to 0.
-4. Stop when dry-round counter reaches 2, or after 3 rounds total.
+2. Thêm bất kỳ finding thực sự mới (chưa có trong `ALL_FINDINGS`) vào danh sách.
+3. Nếu vòng này trả 0 finding mới → tăng bộ đếm dry-round; ngược lại reset về 0.
+4. Dừng khi bộ đếm dry-round đạt 2, hoặc sau tổng cộng 3 vòng.
 
-Record `convergence_rounds` (how many critic rounds ran) for the report.
+Ghi lại `convergence_rounds` (số vòng critic đã chạy) cho report.
 
 ---
 
-## Phase 3 — Dedup, resolve conflicts, merge
-
-Sub-agents run **blind to each other** (independence = diverse coverage). They never
-talk or reconcile among themselves — all duplicate/conflict resolution happens **here in
-the orchestrator**, where the full set is visible.
-
-1. **Deduplicate** `ALL_FINDINGS`: two findings are duplicates if they target the same
-   `section` + `uc_id` and describe the same underlying issue. Keep the one with the
-   richer `suggestion`; if they differ on severity, keep the **higher** severity.
-2. **Resolve conflicts** — group remaining findings by `section` + `uc_id` and check for
-   contradictions (two findings whose `suggestion`s cannot both be applied, or that
-   propose opposite fixes for the same spot):
-   - If the two suggestions can be **merged** into one coherent fix → merge them into a
-     single finding.
-   - If they are **mutually exclusive** → emit **one** finding that states both options
-     and set `auto_fixable: false` with `status: "needs_discussion"` (PRD) /
-     `status: "pending"` (review) so a human picks — never silently drop one side.
-   - If a finding is **invalidated** by another (e.g. a structural finding says a section
-     is missing, but another quotes content from it) → drop the invalid one.
-3. **Sort** by severity (critical → major → minor), then by `section` order in the file.
-4. **Assign stable IDs** `F001, F002, …` in that sorted order.
-5. Map each finding's `dimension` into the command's schema field
-   (`lens` for `/refine-prd`; `check_id` for `/review-context`).
-6. Write the **single** findings file in the FINDINGS SCHEMA the command defines.
-
-In the command's final report, add one line:
+## Phase 3 — Dedup, giải quyết xung đột, merge
+
+Các sub-agent chạy **mù với nhau** (độc lập = độ phủ đa dạng). Chúng không bao giờ
+trao đổi hay điều hoà giữa chúng — mọi xử lý trùng/xung đột diễn ra **ở đây trong
+orchestrator**, nơi thấy toàn bộ tập findings.
+
+1. **Khử trùng lặp** `ALL_FINDINGS`: hai finding là trùng nếu cùng nhắm tới cùng
+   `section` + `uc_id` và mô tả cùng một vấn đề gốc. Giữ cái có `suggestion`
+   phong phú hơn; nếu khác nhau về severity, giữ severity **cao hơn**.
+2. **Giải quyết xung đột** — nhóm các finding còn lại theo `section` + `uc_id` và kiểm tra
+   mâu thuẫn (hai finding có `suggestion` không thể cùng áp dụng, hoặc đề xuất sửa ngược nhau cho cùng một chỗ):
+   - Nếu hai đề xuất có thể **merge** thành một bản sửa mạch lạc → merge thành một finding duy nhất.
+   - Nếu chúng **loại trừ lẫn nhau** → phát ra **một** finding nêu cả hai phương án
+     và set `auto_fixable: false` với `status: "needs_discussion"` (PRD) /
+     `status: "pending"` (review) để con người chọn — không bao giờ âm thầm bỏ một bên.
+   - Nếu một finding bị **vô hiệu** bởi finding khác (vd một finding cấu trúc nói một section
+     bị thiếu, nhưng một finding khác trích dẫn nội dung từ chính section đó) → bỏ cái không hợp lệ.
+3. **Sắp xếp** theo severity (critical → major → minor), rồi theo thứ tự `section` trong file.
+4. **Gán ID ổn định** `F001, F002, …` theo thứ tự đã sắp đó.
+5. Map `dimension` của mỗi finding vào field schema của lệnh
+   (`lens` cho `/refine-prd`; `check_id` cho `/review-context`).
+6. Ghi **một** file findings duy nhất theo FINDINGS SCHEMA mà lệnh định nghĩa.
+
+Trong report cuối của lệnh, thêm một dòng:
 ```
-Convergence: {convergence_rounds} critic round(s) — findings file is complete; re-running should surface 0 new issues.
+Convergence: {convergence_rounds} vòng critic — file findings đã đầy đủ; chạy lại sẽ lòi ra 0 vấn đề mới.
 ```
 
 
-**How the checks below map onto the procedure:**
-- **DIMENSIONS** = the check groups for the detected mode — PRD: `P1, P2, P4, P5`; BDD: `B1, B2, B3, B4, B5, B6`. Fan out one sub-agent per check group, each scanning the full target file for just that group.
-- **Orchestrator-run checks (not fanned out):** `P0` (umbrella routing) and `P3` (cross-PRD conflict) need config / other-PRD context — the orchestrator runs these itself **before** the fan-out and adds their results to `ALL_FINDINGS`.
-- The completeness-critic loop (Phase 2) guarantees the findings file is complete in one run — re-running `/review-context` should surface **0 new** findings. Map each dimension into the `check_id` field of the schema below.
+**Các check dưới đây map vào quy trình như sau:**
+- **DIMENSIONS** = các nhóm check theo mode phát hiện được — PRD: `P1, P2, P4, P5`; BDD: `B1, B2, B3, B4, B5, B6`. Fan out một sub-agent cho mỗi nhóm check, mỗi cái quét toàn bộ target file chỉ cho nhóm đó.
+- **Check do orchestrator chạy (không fan out):** `P0` (umbrella routing) và `P3` (xung đột cross-PRD) cần config / context của PRD khác — orchestrator tự chạy chúng **trước** fan-out và thêm kết quả vào `ALL_FINDINGS`.
+- Vòng lặp completeness-critic (Phase 2) đảm bảo file findings đầy đủ trong một lần chạy — chạy lại `/review-context` sẽ lòi ra **0 finding mới**. Map mỗi dimension vào field `check_id` của schema dưới đây.
 
 ---
 
 ## PRD Review Mode
 
-### P0 — Umbrella Routing Check (umbrella mode only)
+### P0 — Umbrella Routing Check (chỉ chế độ umbrella)
 
-*Skip this check entirely if `setup.mode` is not `"umbrella"` (i.e., `services` section absent from project-context.yaml).*
+*Bỏ qua hoàn toàn check này nếu `setup.mode` không phải `"umbrella"` (tức không có section `services` trong project-context.yaml).*
 
-When `setup.mode = umbrella`, the PRD must have correct routing metadata so context-loader Step 1.5 can direct generated output to the right service submodule. Run these checks **before P1–P5**:
+Khi `setup.mode = umbrella`, PRD phải có metadata routing đúng để context-loader Bước 1.5 có thể đưa output sinh ra tới đúng service submodule. Chạy các check này **trước P1–P5**:
 
-**P0.1 — `@trace.domain` presence**
-- Read the PRD frontmatter block (lines starting with `@trace.` at top of file)
-- If `@trace.domain` is **absent** → **critical** finding:
-  - `finding`: "`@trace.domain` is missing. Dev team's umbrella routing depends on this field to route BDD and code output to the correct service submodule."
-  - `suggestion`: "Add `@trace.domain: {domain}` to the PRD frontmatter. Use one of the domain keys defined in the umbrella's `project-context.yaml` services section."
-  - `auto_fixable: false` — PO must confirm the correct domain name
+**P0.1 — `@trace.domain` có mặt**
+- Đọc block frontmatter của PRD (các dòng bắt đầu bằng `@trace.` ở đầu file)
+- Nếu `@trace.domain` **vắng mặt** → finding **critical**:
+  - `finding`: "`@trace.domain` đang thiếu. Umbrella routing của team dev phụ thuộc field này để đưa BDD và code output tới đúng service submodule."
+  - `suggestion`: "Thêm `@trace.domain: {domain}` vào frontmatter của PRD. Dùng một trong các domain key được định nghĩa trong section services của `project-context.yaml` của umbrella."
+  - `auto_fixable: false` — PO phải confirm tên domain đúng
 
-**P0.2 — `@trace.domain` matches a service key**
-- If `@trace.domain` is present, check if its value matches any key in the `services` section of project-context.yaml
-- If **no match found** → **critical** finding:
-  - `finding`: "`@trace.domain: {value}` does not match any key in the umbrella's `services` config. Routing will fall back to default paths and BDD may be generated to the wrong location."
-  - `suggestion`: "Either update `@trace.domain` to match an existing service key ({list known keys}), or add a new entry to `services` in project-context.yaml for domain `{value}`."
+**P0.2 — `@trace.domain` khớp một service key**
+- Nếu `@trace.domain` có mặt, kiểm tra giá trị của nó có khớp key nào trong section `services` của project-context.yaml không
+- Nếu **không khớp** → finding **critical**:
+  - `finding`: "`@trace.domain: {value}` không khớp key nào trong config `services` của umbrella. Routing sẽ fallback về path mặc định và BDD có thể được sinh sai chỗ."
+  - `suggestion`: "Hoặc cập nhật `@trace.domain` cho khớp một service key có sẵn ({list known keys}), hoặc thêm entry mới vào `services` trong project-context.yaml cho domain `{value}`."
   - `auto_fixable: false`
-- If `services` section is not yet configured (empty/placeholder) → **major** finding:
-  - `finding`: "Umbrella `services` section is not yet configured. Cannot verify domain routing."
-  - `suggestion`: "Update `.agent/project-context.yaml` services section with domain-to-submodule mapping before generating BDD."
+- Nếu section `services` chưa được cấu hình (rỗng/placeholder) → finding **major**:
+  - `finding`: "Section `services` của umbrella chưa được cấu hình. Không thể kiểm chứng domain routing."
+  - `suggestion`: "Cập nhật section services trong `.agent/project-context.yaml` với mapping domain-to-submodule trước khi sinh BDD."
   - `auto_fixable: false`
 
-**P0.3 — `@trace.status` check**
-- If `@trace.status` is absent → **minor**, `auto_fixable: true` (add `@trace.status: draft`)
-- If `@trace.status: draft` → **major**, `auto_fixable: false`:
-  - `finding`: "PRD status is `draft`. Dev team should not generate BDD from an unapproved PRD."
-  - `suggestion`: "PO/SA should review and update status to `approved` before dev team proceeds."
+**P0.3 — Check `@trace.status`**
+- Nếu `@trace.status` vắng mặt → **minor**, `auto_fixable: true` (thêm `@trace.status: draft`)
+- Nếu `@trace.status: draft` → **major**, `auto_fixable: false`:
+  - `finding`: "PRD status là `draft`. Team dev không nên sinh BDD từ một PRD chưa được duyệt."
+  - `suggestion`: "PO/SA nên review và cập nhật status thành `approved` trước khi team dev tiếp tục."
 
-> **P0 is a gate check:** If P0.1 or P0.2 yields a critical finding, display a warning before proceeding:
+> **P0 là một gate check:** Nếu P0.1 hoặc P0.2 cho finding critical, hiển thị cảnh báo trước khi tiếp tục:
 > ```
-> ⚠️  ROUTING WARNING: @trace.domain issue detected.
->    BDD/code generated from this PRD may land in the wrong service submodule.
->    Resolve P0 findings before running /generate-bdd.
+> ⚠️  ROUTING WARNING: phát hiện vấn đề @trace.domain.
+>    BDD/code sinh từ PRD này có thể rơi vào sai service submodule.
+>    Giải quyết các finding P0 trước khi chạy /generate-bdd.
 > ```
-> Then continue with P1–P5 (do not abort — PO may be reviewing early-stage PRDs).
+> Rồi tiếp tục với P1–P5 (đừng abort — PO có thể đang review PRD giai đoạn sớm).
 
 ### P1 — Terminology Check (Business Dictionary)
 
-Load `{paths.business_dictionary}`.
-Scan the entire PRD for terminology issues:
+Nạp `{paths.business_dictionary}`.
+Quét toàn bộ PRD tìm vấn đề thuật ngữ:
 
-1. **Banned terms** — every occurrence of a term in §Banned Terms:
-   → Severity: **critical**. AI can auto-fix in `--resume`.
+1. **Banned terms** — mọi lần xuất hiện của một term trong §Banned Terms:
+   → Severity: **critical**. AI có thể auto-fix khi `--resume`.
 
-2. **Inconsistent usage** — same concept named differently across sections:
-   → Severity: **major**. Flag both occurrences. Human decides canonical form in Review Board note.
+2. **Dùng không nhất quán** — cùng một khái niệm được đặt tên khác nhau giữa các section:
+   → Severity: **major**. Gắn cờ cả hai chỗ. Người quyết định dạng chuẩn trong note Review Board.
 
-3. **Unlisted business terms** — important terms absent from the dictionary:
-   → Severity: **minor**. Suggest adding to `business-dictionary.md`.
+3. **Business term chưa liệt kê** — các term quan trọng vắng trong dictionary:
+   → Severity: **minor**. Đề xuất thêm vào `business-dictionary.md`.
 
 ### P2 — Ambiguity Check
 
-Scan each AC and BR for:
+Quét mỗi AC và BR tìm:
 
-| Signal | Example | Severity |
+| Tín hiệu | Ví dụ | Severity |
 |--------|---------|----------|
-| Vague quantifier | "fast", "large", "reasonable", "quickly" | Critical |
-| Missing actor | "the system should" with no trigger specified | Major |
-| Undefined reference | "{SomeThing}" used but never defined in this PRD | Major |
-| Missing negative path | AC only describes happy path but BR has error conditions | Minor |
-| Passive voice hiding actor | "Invoice is created" — who creates it? | Minor |
+| Định lượng mơ hồ | "nhanh", "lớn", "hợp lý", "mau" | Critical |
+| Thiếu actor | "hệ thống nên" mà không nêu trigger | Major |
+| Tham chiếu chưa định nghĩa | "{SomeThing}" được dùng nhưng chưa định nghĩa trong PRD này | Major |
+| Thiếu luồng âm | AC chỉ mô tả happy path nhưng BR có điều kiện lỗi | Minor |
+| Câu bị động giấu actor | "Invoice is created" — ai tạo? | Minor |
 
-→ AI cannot auto-fix P2 findings. Human must write the fix in Review Board "Modify" note.
+→ AI không thể auto-fix finding P2. Người phải viết bản fix trong note "Modify" của Review Board.
 
 ### P3 — Domain Conflict Check
 
-List all other PRDs in `{paths.specs_dir}/{domain}/*/prd.md`.
-For each one, check if this PRD contradicts a defined BR (same trigger, different outcome)
-or redefines an entity field/status transition differently.
+Liệt kê tất cả PRD khác trong `{paths.specs_dir}/{domain}/*/*.md` (file `.md` ở gốc mỗi feature folder = PRD).
+Với mỗi PRD, kiểm tra xem PRD này có mâu thuẫn với một BR đã định nghĩa không (cùng trigger, khác outcome)
+hoặc định nghĩa lại field/status transition của một entity khác đi.
 
-→ Severity: **critical**. Human decides which PRD is correct. Note required.
+→ Severity: **critical**. Người quyết định PRD nào đúng. Bắt buộc có note.
 
 ### P4 — Structural Completeness
 
-- [ ] Metadata block: Version, Author, Date, Status
-- [ ] At least 1 UC with `#### {TICKET-ID}-UC{N}:` heading
-- [ ] Each UC has: Description, Actors, Preconditions, Acceptance Criteria, Business Rules
-- [ ] `## Changelog` section exists
-- [ ] No `{{PLACEHOLDER}}` values unfilled
+- [ ] Block Metadata: Version, Author, Date, Status
+- [ ] Ít nhất 1 UC với heading `#### {TICKET-ID}-UC{N}:`
+- [ ] Mỗi UC có: Description, Actors, Preconditions, Acceptance Criteria, Business Rules
+- [ ] Có section `## Changelog`
+- [ ] Không còn giá trị `{{PLACEHOLDER}}` chưa điền
 
-→ Missing sections: **major**. AI can add skeleton in `--resume` if accepted.
+→ Section thiếu: **major**. AI có thể thêm skeleton khi `--resume` nếu được chấp nhận.
 
-### P5 — Custom Criteria (optional)
+### P5 — Custom Criteria (tuỳ chọn)
 
-If `$ARGUMENTS` contains additional criteria after the file path, evaluate them and create
-findings with `check_id: "P5"` and severity as appropriate.
+Nếu `$ARGUMENTS` chứa tiêu chí bổ sung sau path file, đánh giá chúng và tạo
+finding với `check_id: "P5"` và severity phù hợp.
 
 ---
 
@@ -673,8 +671,8 @@ findings with `check_id: "P5"` and severity as appropriate.
 
 ### B1 — PRD Coverage Check
 
-Load the PRD referenced by `# @trace.prd:` in the feature file header.
-Map every AC and every BR (including sub-bullets) to scenarios:
+Nạp PRD được tham chiếu bởi `# @trace.prd:` trong header file feature.
+Map mọi AC và mọi BR (gồm cả sub-bullet) sang scenario:
 
 ```
 AC1 ({short text}) → SC1, SC2  ✅
@@ -683,64 +681,64 @@ BR1 ({short text}) → SC1       ✅
 BR2 ({short text}) → MISSING   ❌
 ```
 
-→ Each missing AC/BR coverage: **critical** finding.
-   If accepted in Review Board, `--resume` generates the missing scenario(s).
+→ Mỗi AC/BR thiếu coverage: finding **critical**.
+   Nếu được chấp nhận trong Review Board, `--resume` sinh scenario còn thiếu.
 
 ### B2 — Terminology & Entity Check
 
-Using `{paths.business_dictionary}` and `{paths.core_entities}`:
+Dùng `{paths.business_dictionary}` và `{paths.core_entities}`:
 
-1. **Banned terms in steps** → **critical**, auto-fixable in `--resume`
-2. **Non-canonical entity names** → **major**, auto-fixable
-3. **Non-canonical field names in data tables** → **major**, auto-fixable
-4. **Technically-looking sample data** (UUIDs, `item_123`) → **minor**, auto-fixable
+1. **Banned terms trong steps** → **critical**, auto-fixable khi `--resume`
+2. **Tên entity không chuẩn** → **major**, auto-fixable
+3. **Tên field không chuẩn trong data table** → **major**, auto-fixable
+4. **Sample data trông kỹ thuật** (UUID, `item_123`) → **minor**, auto-fixable
 
 ### B3 — Gherkin Rules Check (R1–R10)
 
 | Rule | Check | Auto-fixable? |
 |------|-------|---------------|
-| R1 | Every scenario has Given + When + Then | No — needs scenario redesign |
-| R2 | No chained `When … Then … When` | No — needs redesign |
-| R3 | No UI selectors / API paths / tech terms in steps | Yes — replace with business phrasing |
-| R4 | Scenario name is a business outcome | No — needs human rename |
-| R5 | Declarative WHAT, not imperative HOW | No — needs rewrite |
-| R6 | `Then` asserts observable business outcome | No — needs redesign |
-| R7 | Concrete values, not "valid data" | Yes — substitute realistic values |
-| R8 | Each scenario is independently runnable | No — needs redesign |
-| R9 | Data tables have enough columns for Then | Yes — add missing columns |
-| R10 | Cross-UC reference uses navigation phrasing + Note | Yes — add Note comment |
-
-→ R3, R7, R9, R10 violations: auto-fixable. Others require human guidance via Review Board note.
+| R1 | Mỗi scenario có Given + When + Then | No — cần thiết kế lại scenario |
+| R2 | Không chained `When … Then … When` | No — cần thiết kế lại |
+| R3 | Không UI selector / API path / tech term trong steps | Yes — thay bằng cách diễn đạt nghiệp vụ |
+| R4 | Tên scenario là một business outcome | No — cần người đổi tên |
+| R5 | Khai báo WHAT, không phải mệnh lệnh HOW | No — cần viết lại |
+| R6 | `Then` khẳng định business outcome quan sát được | No — cần thiết kế lại |
+| R7 | Giá trị cụ thể, không phải "valid data" | Yes — thay bằng giá trị thực tế |
+| R8 | Mỗi scenario chạy độc lập được | No — cần thiết kế lại |
+| R9 | Data table đủ cột cho Then | Yes — thêm cột còn thiếu |
+| R10 | Cross-UC reference dùng cách diễn đạt navigation + Note | Yes — thêm comment Note |
+
+→ Vi phạm R3, R7, R9, R10: auto-fixable. Còn lại cần người hướng dẫn qua note Review Board.
 
 ### B4 — Compliance Checks (C.1–C.5)
 
-- [ ] C.1 Wireframe Coverage: every screen component/action has ≥1 SC → finding per missing item
-- [ ] C.2 PRD Traceability: covered fully by B1 — do NOT create new findings here; deduplicate against B1 findings
-- [ ] C.3 Business Dictionary terms used → same as B2
-- [ ] C.4 Banned Terms: 0 banned terms → **critical**, auto-fixable
-- [ ] C.5 NHÓM Grouping: if ≥3 SCs, grouped by business theme → **major**, auto-fixable
+- [ ] C.1 Wireframe Coverage: mỗi component/action của màn hình có ≥1 SC → một finding cho mỗi mục thiếu
+- [ ] C.2 PRD Traceability: đã phủ đầy đủ bởi B1 — KHÔNG tạo finding mới ở đây; dedup với finding B1
+- [ ] C.3 Term Business Dictionary được dùng → giống B2
+- [ ] C.4 Banned Terms: 0 banned term → **critical**, auto-fixable
+- [ ] C.5 NHÓM Grouping: nếu ≥3 SC, gom nhóm theo business theme → **major**, auto-fixable
 
 ### B5 — Metadata & Structural Check
 
-- [ ] File header has all required `@trace.*` fields — check each explicitly: `@trace.id`, `@trace.title`, `@trace.revision`, `@trace.domain`, `@trace.service`, `@trace.module`, `@trace.status`, `@trace.author`, `@trace.created_at`, `@trace.prd`, `@trace.prd_version`, `@trace.bdd_version`, `@trace.business_rules`, `@trace.dataset` → **minor** per missing field, auto-fixable
-  - Note: `@trace.revision` is always `1` (static field — see generate-bdd.tmpl). Only check for presence; do NOT flag value as stale.
-- [ ] Every scenario has `# @trace.scenario`, `# @trace.sc_version`, `# @trace.business_rules`, `# Side-effects:` → **minor**, auto-fixable
-- [ ] Coverage Matrix at end of file → **major**, auto-fixable (AI regenerates)
-- [ ] Pre-merge Checklist at end of file → **minor**, auto-fixable
+- [ ] Header file có đủ các field `@trace.*` bắt buộc — kiểm tra từng cái tường minh: `@trace.id`, `@trace.title`, `@trace.revision`, `@trace.domain`, `@trace.service`, `@trace.module`, `@trace.status`, `@trace.author`, `@trace.created_at`, `@trace.prd`, `@trace.prd_version`, `@trace.bdd_version`, `@trace.business_rules`, `@trace.dataset` → **minor** cho mỗi field thiếu, auto-fixable
+  - Lưu ý: `@trace.revision` luôn là `1` (field tĩnh — xem generate-bdd.tmpl). Chỉ kiểm tra có mặt; KHÔNG gắn cờ giá trị là stale.
+- [ ] Mỗi scenario có `# @trace.scenario`, `# @trace.sc_version`, `# @trace.business_rules`, `# Side-effects:` → **minor**, auto-fixable
+- [ ] Coverage Matrix ở cuối file → **major**, auto-fixable (AI sinh lại)
+- [ ] Pre-merge Checklist ở cuối file → **minor**, auto-fixable
 
 ### B6 — Side-effect Completeness
 
-For each `@happy` scenario:
-- `# Side-effects:` comment lists all observable side effects
-- `Then` block has `And <side-effect>` for each listed side effect
+Với mỗi scenario `@happy`:
+- Comment `# Side-effects:` liệt kê tất cả side effect quan sát được
+- Block `Then` có `And <side-effect>` cho mỗi side effect đã liệt kê
 
-→ Missing side-effect assertion: **major**, auto-fixable.
+→ Thiếu assertion side-effect: **major**, auto-fixable.
 
 ---
 
-## Write Findings File
+## Ghi File Findings
 
-After running all checks, write `{paths.refinement_dir}/{slug}-review-*-findings.yaml`:
+Sau khi chạy hết các check, ghi `{paths.refinement_dir}/{slug}-review-*-findings.yaml`:
 
 ```yaml
 source_file: "{absolute path to reviewed file}"
@@ -750,14 +748,14 @@ status: "pending_review"
 
 findings:
   - id: "F001"
-    check_id: "P1"           # P1-P5 for PRD; B1-B6 for BDD
+    check_id: "P1"           # P1-P5 cho PRD; B1-B6 cho BDD
     severity: "critical"     # critical | major | minor
-    section: "{section or scenario ID where issue was found}"
-    uc_id: "{UC-ID this finding belongs to — PRD: the UC heading; BDD: @trace.id; \"\" if global}"
-    quote: "{verbatim snippet copied EXACTLY from the reviewed file at the issue location, ≤120 chars}"
-    finding: "{clear description of the issue}"
-    suggestion: "{specific actionable fix — AI will apply this in --resume if accepted}"
-    auto_fixable: true       # true = AI can apply; false = human must write note in Review Board
+    section: "{section hoặc scenario ID nơi tìm thấy lỗi}"
+    uc_id: "{UC-ID mà finding này thuộc về — PRD: UC heading; BDD: @trace.id; \"\" nếu global}"
+    quote: "{trích đoạn nguyên văn copy CHÍNH XÁC từ file đang review tại vị trí lỗi, ≤120 ký tự}"
+    finding: "{mô tả rõ ràng vấn đề}"
+    suggestion: "{bản fix cụ thể, hành động được — AI sẽ áp dụng khi --resume nếu được chấp nhận}"
+    auto_fixable: true       # true = AI áp dụng được; false = người phải viết note trong Review Board
     status: "pending"        # pending | accepted | modified | rejected | deferred
 
 summary:
@@ -768,54 +766,54 @@ summary:
   recommendation: "APPROVED | NEEDS_REVISION | BLOCKED"
 ```
 
-> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
-> For every finding, copy a short **verbatim** `quote` straight from the reviewed file at the exact
-> spot the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
-> Set `uc_id` to the owning Use Case (`@trace.id` for BDD, the UC heading for PRD; `""` if global).
-> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+> **Field định vị (`quote` + `uc_id`) — bắt buộc cho source-jump của Review Board.**
+> Với mỗi finding, copy một đoạn `quote` **nguyên văn** thẳng từ file đang review tại đúng
+> chỗ lỗi xảy ra — KHÔNG diễn giải lại; nó được so khớp với tài liệu để định vị dòng.
+> Đặt `uc_id` là Use Case sở hữu (`@trace.id` cho BDD, UC heading cho PRD; `""` nếu global).
+> Hai field này cho phép reviewer click một finding trong Review Board và nhảy tới đúng vị trí nguồn.
 
-## Post-Analysis Routing
+## Định tuyến sau phân tích (Post-Analysis Routing)
 
-After running all checks and writing the findings file:
+Sau khi chạy hết các check và ghi file findings:
 
-**If `--fix` flag present** → jump to Fix Mode (apply `auto_fixable: true` findings immediately).
+**Nếu có flag `--fix`** → nhảy tới Fix Mode (áp dụng ngay các finding `auto_fixable: true`).
 
-**If no flag** → print Report below and stop.
+**Nếu không có flag** → in Report bên dưới và dừng.
 
 ## Report
 
-# 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 |
 |-------|----------|
@@ -829,219 +827,219 @@ 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.)*
 
 
 ```
-/review-context Complete — {target file}
+/review-context Hoàn tất — {target file}
 Mode: {PRD | BDD}
 Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
 Auto-fixable: {N} | Needs human decision: {N}
 
-Findings file:
+File findings:
   {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
   {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
 
-Next options:
+Lựa chọn tiếp theo:
   A) Quick fix  : /review-context --fix {target-file}
-                  → applies all auto-fixable findings immediately
-  B) Review Board: open findings file → accept/modify/reject
+                  → áp dụng ngay mọi finding auto-fixable
+  B) Review Board: mở file findings → accept/modify/reject
                   → /review-context --resume {target-file}
 ```
 
 ---
 
-## Fix Mode — Apply Auto-Fixable Findings Immediately
+## Fix Mode — Áp dụng ngay các Finding Auto-Fixable
 
-*Triggered when `$ARGUMENTS` contains `--fix`.*
-*Example: `/review-context --fix specs/payment/process-payment/bdd/PAY-001.feature`*
+*Kích hoạt khi `$ARGUMENTS` chứa `--fix`.*
+*Ví dụ: `/review-context --fix specs/payment/process-payment/bdd/PAY-001.feature`*
 
-This mode runs the full analysis (same as default), then immediately applies every
-`auto_fixable: true` finding without going through the Review Board.
+Mode này chạy toàn bộ phân tích (giống mặc định), rồi áp dụng ngay mọi finding
+`auto_fixable: true` mà không qua Review Board.
 
-Use for: BDD cleanup, terminology fixes, metadata gaps — anything the AI can safely
-correct without a human judgment call. Findings requiring human decisions are written
-to the findings file as usual and left `status: pending`.
+Dùng cho: dọn BDD, fix thuật ngữ, gap metadata — bất cứ thứ gì AI có thể sửa an toàn
+mà không cần phán đoán của con người. Finding cần quyết định của con người vẫn được ghi
+vào file findings như thường và để `status: pending`.
 
-### Phase 1 — Run analysis
+### Phase 1 — Chạy phân tích
 
-Run all checks via the **Review Procedure** (fan-out + completeness loop) exactly as in the default mode.
-Write the findings file with all `status: "pending"` as usual.
+Chạy hết các check qua **Quy trình Review** (fan-out + completeness loop) đúng như mode mặc định.
+Ghi file findings với tất cả `status: "pending"` như thường.
 
-### Phase 2 — Apply auto-fixable findings
+### Phase 2 — Áp dụng các finding auto-fixable
 
-For each finding where `auto_fixable: true`, in order (critical → major → minor):
+Với mỗi finding có `auto_fixable: true`, theo thứ tự (critical → major → minor):
 
-**For PRD files:**
+**Với file PRD:**
 
-| check_id | What to apply |
+| check_id | Áp dụng gì |
 |----------|--------------|
-| P0.3 (Missing status) | Add `@trace.status: draft` to frontmatter |
-| P1 (Banned term) | Replace every banned term occurrence with canonical term |
-| P4 (Structure) | Add missing section/metadata skeleton |
+| P0.3 (Thiếu status) | Thêm `@trace.status: draft` vào frontmatter |
+| P1 (Banned term) | Thay mọi lần xuất hiện banned term bằng canonical term |
+| P4 (Structure) | Thêm skeleton section/metadata còn thiếu |
 
-**For BDD files:**
+**Với file BDD:**
 
-| check_id | What to apply |
+| check_id | Áp dụng gì |
 |----------|--------------|
-| B2 (Terminology) | Replace banned terms, fix entity/field names, fix technical sample data |
-| B3 R3 | Replace tech terms/UI selectors with business phrasing |
-| B3 R7 | Substitute concrete realistic values |
-| B3 R9 | Add missing data table columns |
-| B3 R10 | Add cross-UC navigation Note comment |
-| B4 C4 | Fix banned terms in tags |
-| B4 C5 | Add NHÓM grouping if ≥3 SCs |
-| B5 | Add missing @trace headers, regenerate Coverage Matrix / Pre-merge Checklist |
-| B6 | Add missing `And <side-effect>` to Then blocks |
-
-After applying each finding, mark it `status: "applied_automatically"` in the findings file.
+| B2 (Terminology) | Thay banned term, fix tên entity/field, fix sample data kỹ thuật |
+| B3 R3 | Thay tech term/UI selector bằng cách diễn đạt nghiệp vụ |
+| B3 R7 | Thay bằng giá trị thực tế cụ thể |
+| B3 R9 | Thêm cột data table còn thiếu |
+| B3 R10 | Thêm comment Note navigation cross-UC |
+| B4 C4 | Fix banned term trong tag |
+| B4 C5 | Thêm NHÓM grouping nếu ≥3 SC |
+| B5 | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
+| B6 | Thêm `And <side-effect>` còn thiếu vào block Then |
+
+Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied_automatically"` trong file findings.
 
 ### Phase 3 — Version bump
 
-- **PRD**: if ≥1 finding applied → bump **minor** version (auto-fix only applies P1 banned-term replacements and P4 skeleton additions — never alters UC structure or BR content, so minor bump is always correct), add Changelog entry:
+- **PRD**: nếu ≥1 finding được áp dụng → bump version **minor** (auto-fix chỉ áp dụng thay banned-term P1 và thêm skeleton P4 — không bao giờ thay đổi cấu trúc UC hay nội dung BR, nên minor bump luôn đúng), thêm entry Changelog:
   `Auto-fix: applied {N} auto-fixable review-context findings`
-- **BDD**: if ≥1 finding applied → increment `@trace.bdd_version` by 0.1
+- **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1
 
 ### Phase 4 — Report
 
 ```
-/review-context --fix Applied — {target file}
+/review-context --fix Đã áp dụng — {target file}
 Mode: {PRD | BDD}
 
 Auto-fixed : {N} findings ({critical} critical, {major} major, {minor} minor)
-  - {change 1 summary}
-  - {change 2 summary}
+  - {tóm tắt change 1}
+  - {tóm tắt change 2}
 
-Still pending (needs human decision): {N}
-  - F00X [{severity}] {finding summary}  ← open findings file in Review Board
+Còn pending (cần quyết định của con người): {N}
+  - F00X [{severity}] {tóm tắt finding}  ← mở file findings trong Review Board
 
 {If PRD}: Version bumped: {old} → {new}
 {If BDD}: bdd_version: {old} → {new}
 
-Findings file:
+File findings:
   {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
   {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
-Re-run /review-context {file} to confirm 0 remaining critical findings.
+Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
 ```
 
-If 0 findings were auto-fixable → print:
+Nếu 0 finding nào auto-fixable → in:
 ```
-Nothing to auto-fix. All {N} findings require human decision.
-Open findings file in Review Board → then run: /review-context --resume {file}
+Không có gì để auto-fix. Cả {N} finding đều cần quyết định của con người.
+Mở file findings trong Review Board → rồi chạy: /review-context --resume {file}
 ```
 
 ---
 
-## Resume Mode — Apply Accepted Findings
+## Resume Mode — Áp dụng các Finding được chấp nhận
 
-*Triggered when `$ARGUMENTS` contains `--resume`.*
-*Example: `/review-context --resume specs/payment/process-payment/prd.md`*
+*Kích hoạt khi `$ARGUMENTS` chứa `--resume`.*
+*Ví dụ: `/review-context --resume specs/payment/process-payment/PAY01-process-payment.md`*
 
-### Phase 1 — Read accepted findings
+### Phase 1 — Đọc các finding được chấp nhận
 
-1. Derive findings filename from target file using the same rule as Detect Review Mode:
+1. Suy ra tên file findings từ target file dùng cùng quy tắc như Detect Review Mode:
    - PRD: `{paths.refinement_dir}/{prd-slug}-review-context-findings.yaml`
    - BDD: `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`
-2. Read the findings file.
-3. Collect findings where `status: "accepted"` or `status: "modified"`.
-4. If none → report "No accepted findings. File unchanged." and stop.
+2. Đọc file findings.
+3. Gom các finding có `status: "accepted"` hoặc `status: "modified"`.
+4. Nếu không có → báo "No accepted findings. File unchanged." và dừng.
 
-### Phase 2 — Apply fixes
+### Phase 2 — Áp dụng fix
 
-Apply in order: critical → major → minor.
+Áp dụng theo thứ tự: critical → major → minor.
 
-**For PRD findings:**
-| check_id | What to do |
+**Với finding PRD:**
+| check_id | Làm gì |
 |----------|-----------|
-| P0.3 (Missing status) | Add `@trace.status: draft` to frontmatter |
-| P1 (Banned term) | Replace every occurrence of banned term with canonical term |
-| P2 (Ambiguity) | Apply the fix stated in `suggestion` or `modified` note |
-| P3 (Conflict) | Apply the resolution stated in the modified note |
-| P4 (Structure) | Add the missing section/metadata field |
-| P5 (Custom) | Apply as stated in suggestion/note |
+| P0.3 (Thiếu status) | Thêm `@trace.status: draft` vào frontmatter |
+| P1 (Banned term) | Thay mọi lần xuất hiện banned term bằng canonical term |
+| P2 (Ambiguity) | Áp dụng fix nêu trong `suggestion` hoặc note `modified` |
+| P3 (Conflict) | Áp dụng cách giải quyết nêu trong note modified |
+| P4 (Structure) | Thêm section/metadata field còn thiếu |
+| P5 (Custom) | Áp dụng như nêu trong suggestion/note |
 
-→ After applying, bump PRD version (minor) and add Changelog entry.
+→ Sau khi áp dụng, bump version PRD (minor) và thêm entry Changelog.
 
-**For BDD findings:**
-| check_id | What to do |
+**Với finding BDD:**
+| check_id | Làm gì |
 |----------|-----------|
-| B1 (Coverage gap) | Generate new scenario(s) for the uncovered AC/BR and insert into correct NHÓM |
-| B2 (Terminology) | Replace banned terms, fix entity/field names |
-| B3 (Gherkin rule) | Apply rule-specific fix (replace tech terms, add concrete values, etc.) |
-| B4 (Compliance) | Add NHÓM grouping, fix @trace tags |
-| B5 (Metadata) | Add missing @trace headers, regenerate Coverage Matrix / Pre-merge Checklist |
-| B6 (Side effects) | Add missing `And <side-effect>` to Then block |
+| B1 (Coverage gap) | Sinh scenario mới cho AC/BR chưa phủ và chèn vào đúng NHÓM |
+| B2 (Terminology) | Thay banned term, fix tên entity/field |
+| B3 (Gherkin rule) | Áp dụng fix theo từng rule (thay tech term, thêm giá trị cụ thể, v.v.) |
+| B4 (Compliance) | Thêm NHÓM grouping, fix tag @trace |
+| B5 (Metadata) | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
+| B6 (Side effects) | Thêm `And <side-effect>` còn thiếu vào block Then |
 
-→ After applying, increment `@trace.bdd_version` in file header by 0.1.
-→ Also update `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: set `bdd_version` column to the new `@trace.bdd_version` value for all rows, and set `last_updated` to today's date.
+→ Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1.
+→ Đồng thời cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row, và đặt `last_updated` thành ngày hôm nay.
 
 ### Phase 3 — Report
 
 ```
-/review-context --resume Applied — {target file}
+/review-context --resume Đã áp dụng — {target file}
 Applied  : {N} findings ({critical} critical, {major} major, {minor} minor)
 Skipped  : {N} rejected/deferred
 
 Changes:
-  - {change 1 summary}
-  - {change 2 summary}
+  - {tóm tắt change 1}
+  - {tóm tắt change 2}
 
 {If PRD}: Version bumped: {old} → {new}
 {If BDD}: bdd_version: {old} → {new}
 
-Re-run /review-context {file} to confirm 0 remaining critical findings.
+Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
 ```