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

package/commands/qc-analyze.tmpl

@@ -6,12 +6,12 @@ ported_from: ai-automation-qc-base
 
 # /qc-analyze — QC Requirement Analysis
 
-> Stage 1 of the native QC automation pipeline (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Ported from the QC team's qa-analyst. Markdown-first: no scripts here.
+> Stage 1 của QC automation pipeline native (qc-analyze → qc-plan → qc-design-test → qc-review → qc-run-test → qc-report). Port từ qa-analyst của team QC. Markdown-first: không có script ở đây.
 
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a UC-ID or a feature/PRD file. Read the official spec for that UC — the `.feature` (carrying `@trace.id={UC-ID}` and per-scenario `@trace.scenario={UC-ID}-SC{N}`), the PRD, and the design-spec — from the feature package `{paths.specs_dir}/{domain}/{prd-slug}/` (the `.feature` under `bdd/`, the `prd.md`, and the design-spec under `design-spec/`). The framework spec IS the source of truth; do not re-derive requirements that already exist there.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID hoặc file feature/PRD. Đọc spec chính thức của UC đó — file `.feature` (mang `@trace.id={UC-ID}` và mỗi scenario `@trace.scenario={UC-ID}-SC{N}`), PRD, và design-spec — từ feature package `{paths.specs_dir}/{domain}/{prd-slug}/` (file `.feature` dưới `bdd/`, file PRD `{TICKET-ID}-{prd-slug}.md` ở gốc folder, và design-spec dưới `design-spec/`). Spec của framework CHÍNH LÀ source of truth; đừng suy lại các requirement đã có ở đó.*
 
 ## Context
 {{include:steps/context-loader.md}}
@@ -20,67 +20,66 @@ ported_from: ai-automation-qc-base
 
 ## Role
 
-You are the **QC Analyst** — the first stage of the QC automation pipeline. Take the
-official requirement (PRD + BDD `.feature` + design-spec) and break it into a STRUCTURED
-requirement description: functions, business rules, data flow, acceptance criteria. You do
-**not** write detailed test cases or Python (those are qc-design-test / qc-run-test).
+Bạn là **QC Analyst** — stage đầu tiên của QC automation pipeline. Lấy requirement
+chính thức (PRD + BDD `.feature` + design-spec) và phân rã thành một mô tả requirement
+CÓ CẤU TRÚC: function, business rule, data flow, acceptance criteria. Bạn **không**
+viết test case chi tiết hay Python (đó là qc-design-test / qc-run-test).
 
-Boundary vs `/qc-plan`: you answer *"what is the requirement?"*; qc-plan answers *"where is
-the risk, what to ask dev?"*. When something is ambiguous/missing, record it as a gap and
-hand off to qc-plan — never invent an answer.
+Ranh giới với `/qc-plan`: bạn trả lời *"requirement là gì?"*; qc-plan trả lời *"rủi ro ở đâu,
+hỏi dev gì?"*. Khi có gì mơ hồ/thiếu, ghi nó thành gap và bàn giao cho qc-plan — đừng bao giờ bịa câu trả lời.
 
 ## Skills (`{paths.qc_skills_dir}/qa-analyst/`)
 
-Load only the file for the step you are doing (each is self-contained):
-- `spec-breakdown.md` — break a spec/PRD/user story into structure.
-- `business-rules.md` — extract business rules, conditions, constraints (code `BR-xx`).
-- `data-flow.md` — input/output, data flow, integration/failure points.
-- `acceptance-criteria.md` — Given/When/Then acceptance criteria (code `AC-xx`).
+Chỉ nạp file cho bước đang làm (mỗi file tự đủ):
+- `spec-breakdown.md` — phân rã spec/PRD/user story thành cấu trúc.
+- `business-rules.md` — trích business rule, điều kiện, ràng buộc (code `BR-xx`).
+- `data-flow.md` — input/output, data flow, điểm tích hợp/thất bại.
+- `acceptance-criteria.md` — acceptance criteria Given/When/Then (code `AC-xx`).
 
-Typical order: spec-breakdown → business-rules / data-flow → acceptance-criteria.
+Thứ tự điển hình: spec-breakdown → business-rules / data-flow → acceptance-criteria.
 
-## Trace mapping (mandatory)
+## Trace mapping (bắt buộc)
 
-The official `.feature` already defines scenarios as `@trace.scenario={UC-ID}-SC{N}` with
-`@trace.business_rules`. Map every `BR-xx` / `AC-xx` you produce to its owning
-`{UC-ID}-SC{N}` and record the mapping — qc-design-test and qc-run-test need it to tag
-tests with `@trace.verifies` and write `qc_status` per scenario.
+File `.feature` chính thức đã định nghĩa scenario là `@trace.scenario={UC-ID}-SC{N}` với
+`@trace.business_rules`. Map mọi `BR-xx` / `AC-xx` bạn tạo ra tới `{UC-ID}-SC{N}` sở hữu nó
+và ghi lại mapping — qc-design-test và qc-run-test cần nó để gắn tag
+`@trace.verifies` cho test và ghi `qc_status` theo từng scenario.
 
-## DOC_GAPS (mandatory)
+## DOC_GAPS (bắt buộc)
 
-Always produce a gaps file following `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`:
-- Each gap `GAP-xx`, classified MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION / OPEN QUESTION, with severity (🔴 Blocker → 🟢 Low) and the affected function/BR/AC.
-- Never fabricate answers; mark assumptions as `ASSUMPTION` for PO/dev to confirm.
-- Any `🔴 Blocker` still `Open` ⇒ the UC is not ready for qc-design-test — hand off to qc-plan.
-- **Push genuine SPEC defects to the PO (not just keep them local).** A blocker that is a real
-  flaw in the official spec — `AMBIGUOUS` / `CONTRADICTORY` / `MISSING` in PRD/BDD — must reach
-  the PO via the feedback flow, not sit only in `DOC_GAPS.md`: file `/report-bug {UC-ID} {desc}`
-  (its BUG_FLOW classifies PRD vs BDD), or `/propose-scenario {UC-ID}` if the gap is missing test
-  coverage. `ASSUMPTION` / `OPEN QUESTION` gaps are confirmed via qc-plan's questions-for-dev — not filed as bugs.
+Luôn tạo một file gaps theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`:
+- Mỗi gap `GAP-xx`, phân loại MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION / OPEN QUESTION, với severity (🔴 Blocker → 🟢 Low) và function/BR/AC bị ảnh hưởng.
+- Không bao giờ bịa câu trả lời; đánh dấu giả định là `ASSUMPTION` để PO/dev confirm.
+- Bất kỳ `🔴 Blocker` nào còn `Open` ⇒ UC chưa sẵn sàng cho qc-design-test — bàn giao cho qc-plan.
+- **Đẩy các defect spec thực sự lên PO (không chỉ giữ local).** Một blocker là lỗi thật
+  trong spec chính thức — `AMBIGUOUS` / `CONTRADICTORY` / `MISSING` trong PRD/BDD — phải tới
+  PO qua feedback flow, không chỉ nằm trong `DOC_GAPS.md`: tạo `/report-bug {UC-ID} {desc}`
+  (BUG_FLOW của nó phân loại PRD vs BDD), hoặc `/propose-scenario {UC-ID}` nếu gap là thiếu test
+  coverage. Gap `ASSUMPTION` / `OPEN QUESTION` được confirm qua questions-for-dev của qc-plan — không file thành bug.
 
 ## Output
 
-Write **exactly TWO files** under `{paths.qc_dir}/{UC-ID}/` — do **not** split the analysis
-into one-file-per-step (no separate spec-breakdown / business-rules / data-flow / AC files):
+Ghi **đúng HAI file** dưới `{paths.qc_dir}/{UC-ID}/` — **đừng** tách phân tích
+thành một-file-mỗi-bước (không có file spec-breakdown / business-rules / data-flow / AC riêng):
 
-1. **`{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`** — the single consolidated analysis.
-   Sections in order: requirement breakdown → business-rule table (`BR-xx`) → data-flow →
-   acceptance-criteria (`AC-xx`), each `BR`/`AC` mapped to its owning `{UC-ID}-SC{N}`.
-2. **`{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`** — the gaps file (per `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`).
+1. **`{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`** — bản phân tích hợp nhất duy nhất.
+   Section theo thứ tự: phân rã requirement → bảng business-rule (`BR-xx`) → data-flow →
+   acceptance-criteria (`AC-xx`), mỗi `BR`/`AC` map tới `{UC-ID}-SC{N}` sở hữu nó.
+2. **`{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`** — file gaps (theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`).
 
-`{paths.qc_dir}` is a VISIBLE top-level folder in the QC repo (default `docs/`, **not** the
-hidden `.agent/review/`) so the QC team can open and process the output easily. The official
-spec stays in the PO spec submodule — do not write analysis there.
+`{paths.qc_dir}` là folder top-level NHÌN THẤY trong QC repo (mặc định `docs/`, **không** phải
+`.agent/review/` ẩn) để team QC mở và xử lý output dễ dàng. Spec chính thức ở lại
+spec submodule của PO — đừng ghi phân tích vào đó.
 
 ## Report
 
 {{include:steps/report-footer.md}}
 
 ```
-/qc-analyze Complete — {UC-ID}
+/qc-analyze Hoàn tất — {UC-ID}
 Files: {paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md + DOC_GAPS.md   (2 files)
-Gaps: {N} ({blockers} blocker)   ← spec-defect blocker? → /report-bug {UC-ID}  | coverage gap → /propose-scenario {UC-ID}
-SC mapping: {M} BR/AC mapped to {K} scenarios
+Gaps: {N} ({blockers} blocker)   ← blocker là spec-defect? → /report-bug {UC-ID}  | coverage gap → /propose-scenario {UC-ID}
+SC mapping: {M} BR/AC map tới {K} scenario
 Next: /qc-plan {UC-ID}   ← risk / what-if / questions-for-dev
-      (resolve 🔴 Blocker gaps with PO/Dev first)
+      (giải quyết các gap 🔴 Blocker với PO/Dev trước)
 ```