@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/commands/qc-analyze.tmpl

@@ -1,112 +0,0 @@
----
-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)
-```