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

package/commands/review-context.tmpl

@@ -1,139 +1,139 @@
-# /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
 {{include:steps/gate.md}}
 
-*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
 {{include:steps/context-loader.md}}
 
 ---
 
-## 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
+## Quy trình Review
 {{include:steps/review-fanout.md}}
 
-**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.
 
 ---
 
@@ -141,8 +141,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  ✅
@@ -151,64 +151,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}"
@@ -218,14 +218,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:
@@ -236,180 +236,180 @@ 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
 
 {{include:steps/report-footer.md}}
 
 ```
-/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.
 ```