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

package/steps/gate.md

@@ -1,87 +1,87 @@
-# 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à `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **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/*/*/prd.md` 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ì.

package/steps/report-footer.md

@@ -1,35 +1,35 @@
-# 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 |
 |-------|----------|
@@ -43,58 +43,58 @@ 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.)*

package/steps/review-fanout.md

@@ -1,67 +1,67 @@
-# Exhaustive Review Fan-Out + Completeness Convergence
+# 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}.
@@ -77,20 +77,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,
@@ -99,40 +99,38 @@ 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.
 ```