@edupia-tutor/spec-driven-docs 0.14.3 → 0.14.4

package/core/commands/refine-prd.md

@@ -16,6 +16,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 
@@ -92,6 +93,19 @@ Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp t
 
 *Lưu ý: Với lệnh này, target file ở Bước 1 là một file PRD (`{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder) dưới `{paths.specs_dir}/{domain}/{prd-slug}/`. Đọc toàn bộ PRD sau khi phân giải file.*
 
+### Bước 0-C — Resume mode routing *(riêng /refine-prd, chạy ngay sau Bước 0 của Gate)*
+
+Nếu `$ARGUMENTS` chứa `--resume`:
+- Tách `--resume` ra, phần còn lại là `raw_target` (file path hoặc prd-slug).
+- **Nạp minimal context:** đọc `.agent/project-context.yaml`, trích xuất `paths.refinement_dir`
+  (default: `.agent/review` nếu không có hoặc file không tồn tại).
+- Chạy **Bước 1** với `raw_target` để phân giải `prd-slug` và `target_file`.
+  Nếu `raw_target` rỗng → liệt kê các file `*.yaml` trong `{paths.refinement_dir}/` và hỏi user chọn findings file nào.
+- **Bỏ qua Bước 0-B, 2, 3** — apply findings là tác vụ cơ học, không cần model check hay load full context.
+- → Nhảy thẳng tới **Resume Mode** ở cuối lệnh này.
+
+Nếu `$ARGUMENTS` không chứa `--resume` → tiếp tục luồng review bình thường bên dưới.
+
 ## Context
 # Context Loader — Nạp toàn bộ context dự án
 
@@ -495,8 +509,16 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
 
 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 đó.
+   - danh sách findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
+     đủ để critic nhận ra trùng lặp (không cần `quote`, `suggestion`, `auto_fixable`, `severity`):
+     ```json
+     [
+       { "uc_id": "...", "section": "...", "finding": "..." },
+       ...
+     ]
+     ```
+     Nếu `ALL_FINDINGS` vượt 60 items, rút gọn `finding` xuống còn 80 ký tự đầu mỗi item.
+   - cùng slim context (banned terms, canonical entities, layer order, domains).
    Prompt nó:
    ```
    Here is a document and a list of issues already found. Read the WHOLE document.
@@ -567,6 +589,13 @@ Suy ra tên file output từ PRD slug:
 - File PRD: `{paths.specs_dir}/payment/create-invoice/PAY01-create-invoice.md` → output: `{paths.refinement_dir}/create-invoice-findings.yaml`
 - Quy tắc: lấy tên folder cha của PRD (prd-slug), thêm hậu tố `-findings.yaml`
 
+Trước khi ghi file, xác định `recommendation` từ findings đã dedup và sắp xếp:
+- `by_severity.critical ≥ 1` → `BLOCKED`
+- `by_severity.critical = 0` và `by_severity.major ≥ 1` → `NEEDS_REVISION`
+- `by_severity.critical = 0` và `by_severity.major = 0` → `APPROVED_WITH_MINOR_CHANGES`
+
+Đảm bảo `{paths.refinement_dir}/` tồn tại — tạo thư mục nếu chưa có trước khi ghi file.
+
 Ghi `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
 
 ```yaml
@@ -583,14 +612,27 @@ findings:
     quote: "{trích đoạn nguyên văn copy CHÍNH XÁC từ PRD tại vị trí lỗi, ≤120 ký tự}"
     finding: "{mô tả gap hoặc vấn đề}"
     suggestion: "{đề xuất cải thiện cụ thể, hành động được}"
-    auto_fixable: false  # true = AI áp dụng khi --resume; false = người phải ghi quyết định trong note
-    status: "pending"    # pending | accepted | rejected | needs_discussion
+    auto_fixable: false
+    # true  = AI tự tin cao vào suggestion này; Review Board có thể hiển thị nút "quick accept"
+    # false = cần human đọc kỹ và ghi quyết định trước khi accept
+    # Resume Mode luôn áp dụng theo status (accepted|modified), bất kể auto_fixable.
+    status: "pending"
+    # Lifecycle finding-level:
+    #   pending          → finding mới, chưa được review
+    #   accepted         → reviewer chấp nhận suggestion gốc → Resume sẽ apply
+    #   modified         → reviewer đã sửa suggestion trong Review Board → Resume dùng suggestion đã sửa
+    #   rejected         → reviewer bác bỏ, không apply
+    #   needs_discussion → hai suggestion xung đột, cần con người quyết định trước khi --resume
+    #   applied          → đã được Resume Mode apply vào PRD
 
 summary:
   total_findings: {N}
   by_severity: { critical: {N}, major: {N}, minor: {N} }
   by_lens: { QA: {N}, DEV: {N}, SA: {N}, PO: {N} }
   recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
+  # Rule: critical ≥ 1                       → BLOCKED
+  #       critical = 0, major ≥ 1            → NEEDS_REVISION
+  #       critical = 0, major = 0            → APPROVED_WITH_MINOR_CHANGES
 ```
 
 > **Field định vị (`quote` + `uc_id`) — bắt buộc cho source-jump của Review Board.**
@@ -703,26 +745,57 @@ Next     : {lệnh gợi ý kèm ví dụ tham số}
 *(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
 
 
+Dùng footer chuẩn với hai field bổ sung `Findings` và `Review` đặt ngay sau `Status`:
+
 ```
-/refine-prd Hoàn tất — {PRD name}
-Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
-Review: {paths.refinement_dir}/{prd-slug}-findings.yaml
-Next: Mở trong Review Board (chuột phải vào file) → Cập nhật PRD
-      → /review-context {prd-file}   ← kiểm tra chất lượng PRD trước khi sinh BDD
-      → /generate-bdd {prd-file}
+---
+Status   : {badge}
+Findings : {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
+Review   : {paths.refinement_dir}/{prd-slug}-findings.yaml
+Output Artifacts:
+  created {paths.refinement_dir}/{prd-slug}-findings.yaml (findings từ 4-lens review)
+Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : Mở trong Review Board (chuột phải vào file) → Cập nhật PRD
+           → /review-context {prd-file}   ← kiểm tra chất lượng PRD trước khi sinh BDD
+           → /generate-bdd {prd-file}
 ```
 
+Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau footer:
+
+```
+⚠️  {N} finding(s) cần quyết định của bạn trước khi --resume:
+   Mở {paths.refinement_dir}/{prd-slug}-findings.yaml
+   Với mỗi finding có status "needs_discussion":
+     1. Đọc cả hai phương án trong `suggestion`
+     2. Chọn một (hoặc viết phương án khác) vào `suggestion`
+     3. Đổi `status` → "accepted"
+   Sau đó chạy: /refine-prd {prd-file} --resume
+```
+*(Bỏ warning block này nếu không có `needs_discussion` finding nào.)*
+
 ---
 
 ## Resume Mode — Áp dụng Findings & Bump Version
 
-*Kích hoạt khi `$ARGUMENTS` chứa `--resume` (gọi bởi nút "Apply to PRD" của Review Board).*
+*Được route tới từ Bước 0-C — Resume mode routing. `prd-slug` và `target_file` đã được phân giải ở Bước 1 trước khi nhảy vào đây.*
 
 ### Phase 1 — Đọc các finding được chấp nhận
 
-1. Đọc `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
-2. Gom tất cả finding có `status: "accepted"` hoặc `status: "modified"`.
-3. Nếu không có finding nào được chấp nhận → báo "No accepted findings. PRD unchanged." và dừng.
+1. Kiểm tra `{paths.refinement_dir}/{prd-slug}-findings.yaml` có tồn tại không.
+   Nếu không → báo lỗi rõ ràng và dừng:
+   ```
+   ❌ Không tìm thấy findings file tại {paths.refinement_dir}/{prd-slug}-findings.yaml
+      Hãy chạy /refine-prd {prd-file} trước để tạo findings, rồi mới --resume.
+   ```
+2. Đọc file findings.
+3. Gom tất cả finding có `status: "accepted"` hoặc `status: "modified"`.
+4. Nếu không có finding nào được chấp nhận → báo "No accepted findings. PRD unchanged." và dừng.
+5. Nếu còn finding nào có `status: "needs_discussion"` → cảnh báo (không dừng):
+   ```
+   ⚠️  {N} finding(s) chưa được giải quyết (needs_discussion) — sẽ bị bỏ qua lần apply này.
+      Giải quyết chúng trong Review Board rồi chạy lại --resume để apply.
+   ```
 
 ### Phase 2 — Áp dụng thay đổi vào PRD
 
@@ -736,7 +809,9 @@ Với mỗi finding được chấp nhận, theo thứ tự severity (critical
 Với mỗi finding đã áp dụng (status là `accepted` hoặc `modified`):
 - Đặt `status: "applied"` trong `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
 
-Cập nhật `summary.status: "applied"` trong file findings.
+Cập nhật `status: "applied"` ở **root level** của file findings (không phải `summary.status`).
+# Lifecycle file-level: pending_review → applied | partially_applied
+# partially_applied khi có finding bị rejected hoặc needs_discussion còn sót lại.
 
 ### Phase 3 — Bump version & ghi entry changelog
 

package/core/commands/report-bug.md

@@ -27,6 +27,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/commands/review-code.md

@@ -18,6 +18,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/commands/review-context.md

@@ -19,6 +19,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 
@@ -519,8 +520,16 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
 
 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 đó.
+   - danh sách findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
+     đủ để critic nhận ra trùng lặp (không cần `quote`, `suggestion`, `auto_fixable`, `severity`):
+     ```json
+     [
+       { "uc_id": "...", "section": "...", "finding": "..." },
+       ...
+     ]
+     ```
+     Nếu `ALL_FINDINGS` vượt 60 items, rút gọn `finding` xuống còn 80 ký tự đầu mỗi item.
+   - cùng slim context (banned terms, canonical entities, layer order, domains).
    Prompt nó:
    ```
    Here is a document and a list of issues already found. Read the WHOLE document.

package/core/commands/review-tech-docs.md

@@ -19,6 +19,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/commands/setup-ai-first.md

@@ -18,6 +18,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/commands/validate-traces.md

@@ -18,6 +18,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/skills/code/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/skills/design-spec/SKILL.md

@@ -31,6 +31,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/skills/prd/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/skills/spec/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/skills/test/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/steps/gate.md

@@ -13,6 +13,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/core/steps/review-fanout.md

@@ -88,8 +88,16 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
 
 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 đó.
+   - danh sách findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
+     đủ để critic nhận ra trùng lặp (không cần `quote`, `suggestion`, `auto_fixable`, `severity`):
+     ```json
+     [
+       { "uc_id": "...", "section": "...", "finding": "..." },
+       ...
+     ]
+     ```
+     Nếu `ALL_FINDINGS` vượt 60 items, rút gọn `finding` xuống còn 80 ký tự đầu mỗi item.
+   - cùng slim context (banned terms, canonical entities, layer order, domains).
    Prompt nó:
    ```
    Here is a document and a list of issues already found. Read the WHOLE document.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edupia-tutor/spec-driven-docs",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "AI-First Spec-Driven Development workflow framework for Claude Code",
   "bin": {
     "spec-driven-docs": "./bin/index.js"

package/skills/code/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/skills/design-spec/SKILL.md

@@ -31,6 +31,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/skills/prd/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/skills/spec/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/skills/test/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/steps/gate.md

@@ -13,6 +13,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặ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)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đ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).
 

package/steps/review-fanout.md

@@ -88,8 +88,16 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
 
 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 đó.
+   - danh sách findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
+     đủ để critic nhận ra trùng lặp (không cần `quote`, `suggestion`, `auto_fixable`, `severity`):
+     ```json
+     [
+       { "uc_id": "...", "section": "...", "finding": "..." },
+       ...
+     ]
+     ```
+     Nếu `ALL_FINDINGS` vượt 60 items, rút gọn `finding` xuống còn 80 ký tự đầu mỗi item.
+   - cùng slim context (banned terms, canonical entities, layer order, domains).
    Prompt nó:
    ```
    Here is a document and a list of issues already found. Read the WHOLE document.