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

package/commands/refine-prd.tmpl

@@ -1,46 +1,46 @@
-# /refine-prd — Analyze PRD Through 4 Review Lenses
+# /refine-prd — Phân tích PRD qua 4 lăng kính review
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target file in Step 1 is a PRD file (`prd.md`) under `{paths.specs_dir}/{domain}/{prd-slug}/`. Read the full PRD after resolving the file.*
+*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.*
 
 ## Context
 {{include:steps/context-loader.md}}
 
 ---
 
-## Review Procedure
+## Quy trình Review
 {{include:steps/review-fanout.md}}
 
 ---
 
-## Analyze — 4 Lenses (fan out over all four, then converge)
+## Phân tích — 4 lăng kính (fan out cả bốn, rồi hội tụ)
 
-Run the review through the **Review Procedure** above (`steps/review-fanout.md`).
+Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
 
-**DIMENSIONS** = the 4 lenses below — fan out one sub-agent per lens, each scanning the
-full PRD through its single lens:
+**DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
+toàn bộ PRD qua đúng lăng kính của nó:
 
-- **QA Lens**: Are ACs testable? Edge cases specified? Boundary conditions defined?
-- **DEV Lens**: Are API inputs/outputs clear? Business rules unambiguous? Cross-service deps fully described? Any technical risk?
-- **SA Lens**: Fits existing architecture? Security/auth implications? Data modeling clear?
-- **PO Lens**: Scope bounded? Priorities clear? Success metrics defined? Scope creep risk?
+- **Lăng kính QA**: AC có testable không? Edge case đã nêu? Điều kiện biên đã định nghĩa?
+- **Lăng kính DEV**: Input/output API rõ chưa? Business rule có mơ hồ không? Cross-service deps mô tả đủ chưa? Có rủi ro kỹ thuật nào?
+- **Lăng kính SA**: Khớp kiến trúc hiện tại? Hệ luỵ security/auth? Mô hình dữ liệu rõ chưa?
+- **Lăng kính PO**: Scope đã khoanh vùng? Priority rõ chưa? Success metric đã định nghĩa? Rủi ro scope creep?
 
-The completeness-critic loop (Phase 2) is what guarantees the findings file is complete
-in one run — re-running `/refine-prd` should surface **0 new** findings. Map each
-dimension into the `lens` field of the schema below.
+Vòng lặp completeness-critic (Phase 2) là cái đảm bảo file findings đầy đủ trong một lần chạy
+— chạy lại `/refine-prd` sẽ lòi ra **0 finding mới**. Map mỗi dimension vào field `lens`
+của schema dưới đây.
 
-## Output File
+## File Output
 
-Derive the output filename from the PRD slug:
-- PRD file: `{paths.specs_dir}/payment/create-invoice/prd.md` → output: `{paths.refinement_dir}/create-invoice-findings.yaml`
-- Rule: take the PRD's parent folder name (the prd-slug), append `-findings.yaml`
+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`
 
-Write `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
+Ghi `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
 
 ```yaml
-prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/prd.md"
+prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
 generated_at: "{ISO datetime}"
 status: "pending_review"
 
@@ -48,12 +48,12 @@ findings:
   - id: "F001"
     lens: "QA"           # QA | DEV | SA | PO
     severity: "major"    # critical | major | minor
-    section: "§6. Acceptance Criteria"   # human-readable heading/section label
-    uc_id: "{TICKET-ID}-UC{N}"           # UC this finding belongs to; "" if PRD-global (scope, metrics, problem statement)
-    quote: "{verbatim snippet copied EXACTLY from the PRD at the issue location, ≤120 chars}"
-    finding: "{description of gap or issue}"
-    suggestion: "{specific actionable improvement}"
-    auto_fixable: false  # true = AI applies in --resume; false = human must write decision in note
+    section: "§2. Acceptance Criteria"   # nhãn heading/section dạng người đọc
+    uc_id: "{TICKET-ID}-UC{N}"           # UC mà finding thuộc về; "" nếu PRD-global (scope, metrics, problem statement)
+    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
 
 summary:
@@ -63,78 +63,78 @@ summary:
   recommendation: "APPROVED_WITH_MINOR_CHANGES | 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 PRD 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 (or `""` for PRD-global findings). These let a reviewer click a
-> finding in the Review Board and jump straight to the precise location in the source PRD.
+> **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ừ PRD 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 (hoặc `""` cho finding PRD-global). Hai field này cho phép reviewer click một
+> finding trong Review Board và nhảy thẳng tới đúng vị trí trong PRD nguồn.
 
 ## Report
 
 {{include:steps/report-footer.md}}
 
 ```
-/refine-prd Complete — {PRD name}
+/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: Open in Review Board (right-click file) → Update PRD
-      → /review-context {prd-file}   ← verify PRD quality before generating BDD
+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}
 ```
 
 ---
 
-## Resume Mode — Apply Findings & Bump Version
+## Resume Mode — Áp dụng Findings & Bump Version
 
-*Triggered when `$ARGUMENTS` contains `--resume` (called by Review Board "Apply to PRD" button).*
+*Kích hoạt khi `$ARGUMENTS` chứa `--resume` (gọi bởi nút "Apply to PRD" của Review Board).*
 
-### Phase 1 — Read accepted findings
+### Phase 1 — Đọc các finding được chấp nhận
 
-1. Read `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
-2. Collect all findings where `status: "accepted"` or `status: "modified"`.
-3. If no accepted findings → report "No accepted findings. PRD unchanged." and stop.
+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.
 
-### Phase 2 — Apply changes to PRD
+### Phase 2 — Áp dụng thay đổi vào PRD
 
-For each accepted finding, in order of severity (critical → major → minor):
-- Navigate to the PRD section indicated by `finding.section`.
-- Apply `finding.suggestion`. For `status: "modified"` findings, the human has already edited `finding.suggestion` in the Review Board — that edited value IS the fix to apply.
-- Do not alter any sections not referenced by an accepted finding.
+Với mỗi finding được chấp nhận, theo thứ tự severity (critical → major → minor):
+- Đi tới section PRD được chỉ định bởi `finding.section`.
+- Áp dụng `finding.suggestion`. Với finding `status: "modified"`, người đã sửa sẵn `finding.suggestion` trong Review Board — giá trị đã sửa đó CHÍNH LÀ bản fix cần áp dụng.
+- Không thay đổi bất kỳ section nào không được tham chiếu bởi một finding được chấp nhận.
 
-### Phase 2.5 — Update findings file
+### Phase 2.5 — Cập nhật file findings
 
-For each finding that was applied (status was `accepted` or `modified`):
-- Set `status: "applied"` in `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
+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`.
 
-Update `summary.status: "applied"` in the findings file.
+Cập nhật `summary.status: "applied"` trong file findings.
 
-### Phase 3 — Bump version & write changelog entry
+### Phase 3 — Bump version & ghi entry changelog
 
-1. Read current `| **Version** |` value from PRD metadata table.
-2. Determine bump type from the set of accepted findings:
-   - **major** (X.0 → next X+1.0): new or removed Use Case, restructured scope, breaking BR change.
-   - **minor** (x.Y → x.Y+1): clarification, new edge case, AC/BR wording refinement.
-3. Compute new version string.
-4. Update PRD metadata:
+1. Đọc giá trị `| **Version** |` hiện tại từ bảng metadata của PRD.
+2. Xác định loại bump từ tập finding được chấp nhận:
+   - **major** (X.0 → X+1.0 kế tiếp): thêm/xoá Use Case, tái cấu trúc scope, thay đổi BR breaking.
+   - **minor** (x.Y → x.Y+1): làm rõ, thêm edge case, tinh chỉnh wording AC/BR.
+3. Tính chuỗi version mới.
+4. Cập nhật metadata PRD:
    - `| **Version** | {new_version} |`
    - `| **Updated**  | {today YYYY-MM-DD} |`
-   - `| **Status**   | draft |` ← reset to draft, must be re-approved
-5. Prepend a new row to `## Changelog` at the bottom of the PRD:
+   - `| **Status**   | draft |` ← reset về draft, phải được duyệt lại
+5. Thêm một row mới lên đầu `## Changelog` ở cuối PRD:
    ```
-   | {new_version} | {today} | {concise summary of all applied changes} |
+   | {new_version} | {today} | {tóm tắt súc tích mọi thay đổi đã áp dụng} |
    ```
 
 ### Phase 4 — Report
 
 ```
-/refine-prd Applied — {PRD name}
+/refine-prd Đã áp dụng — {PRD name}
 Version  : {old_version} → {new_version}
 Applied  : {N} findings ({critical} critical, {major} major, {minor} minor)
 Changes  :
   - {change 1}
   - {change 2}
 
-⚠️  BDD may be outdated. Run:
-    /review-context {prd-file}   ← verify PRD quality first
+⚠️  BDD có thể đã lỗi thời. Chạy:
+    /review-context {prd-file}   ← kiểm tra chất lượng PRD trước
     → /generate-bdd {prd-file}
 ```