@educa-corp/sdd-framework 0.1.0

package/commands/qc-analyze.tmpl

@@ -0,0 +1,112 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# /qc-analyze — QC Requirement Analysis
+
+> 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}}
+
+*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}}
+
+---
+
+## Guard — BDD đã duyệt chưa
+
+Đọc `# @trace.status:` từ header file `.feature` của UC target:
+- `approved` → tiếp tục bình thường.
+- `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
+  ```
+  ⚠️  BDD của {UC-ID} đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
+     Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
+     Vẫn chạy QC bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y.
+
+---
+
+## Platform Resolution *(thiết lập cho cả QC pass — mọi stage sau kế thừa)*
+
+`{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) — `web SC3` và `app SC3` là hai scenario khác nhau, và sổ trace tách theo `{UC-ID}-{platform}.tsv`. Nên **một QC pass khoá đúng MỘT platform**, và mọi artifact QC nằm dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/`.
+
+Phân giải `active_platform`:
+- Target ở Bước 1 là một file `.feature` → đọc `# @trace.platform` của nó.
+- `$ARGUMENTS` nêu platform (`web`/`app`/`system`) → dùng.
+- Ngược lại → hỏi: *"QC pass này cho platform nào? (web/app/system)"* và chờ chọn.
+
+Lưu `active_platform`. Đọc **đúng file `.feature` của platform đó** (`{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{UC-ID}*.feature`) làm nguồn SC — không trộn SC chéo platform.
+
+---
+
+## Role
+
+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).
+
+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/`)
+
+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`).
+
+Thứ tự điển hình: spec-breakdown → business-rules / data-flow → acceptance-criteria.
+
+## Trace mapping (bắt buộc)
+
+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 (bắt buộc)
+
+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
+
+Ghi **đúng HAI file** dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/` — **đừ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}/{active_platform}/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}` (của `.feature` platform này) sở hữu nó.
+2. **`{paths.qc_dir}/{UC-ID}/{active_platform}/DOC_GAPS.md`** — file gaps (theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`).
+
+`{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 Hoàn tất — {UC-ID}
+Files: {paths.qc_dir}/{UC-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md + DOC_GAPS.md   (2 files)
+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
+      (giải quyết các gap 🔴 Blocker với PO/Dev trước)
+```