@educa-corp/sdd-framework 0.2.3 → 0.2.5

package/docs/05-reference/trace-schema.md

@@ -1,154 +0,0 @@
-[📚 Docs](../README.md) › [Reference](README.md) › Trace TSV Schema
-
-# Trace TSV Schema
-
-> Schema chuẩn của `.trace/{UC-ID}-{platform}.tsv` — file trace state per **use-case × platform**. Mỗi UC có một sổ riêng cho `system` / `web` / `app`: 1 header row + 1 data row mỗi scenario. Tách theo platform vì `sc_id` = `{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) (mỗi platform tự đánh số SC từ 1) — gộp một sổ sẽ khiến scenario các platform đè/xoá nhau. Đây là nguồn dữ liệu cho `/validate-traces` và panel Living Docs.
-
----
-
-## Mục lục
-
-- [Canonical TSV header](#canonical-tsv-header)
-- [Column reference](#column-reference)
-- [Two independent signals: dev_selftest vs qc_status](#two-independent-signals-dev_selftest-vs-qc_status)
-- [Status computation (validate-traces)](#status-computation-validate-traces)
-- [@trace tags across artifacts](#trace-tags-across-artifacts)
-- [trace-report.json](#trace-reportjson)
-
----
-
-## Canonical TSV header
-
-Tab-separated, một header row + một data row mỗi scenario. Header chính xác (từ `generate-bdd.tmpl`):
-
-```
-sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selftest	dev_selftest_at	qc_status	qc_run_at	qc_owner	qc_blocked_by	prd_version	bdd_version	tech_doc_revision	fe_tech_doc_revision	prd_status	uc_status	fe_phase	status	last_updated
-```
-
-22 cột, theo đúng thứ tự trên.
-
----
-
-## Column reference
-
-| # | Column | Ý nghĩa | Giá trị khởi tạo (`/generate-bdd`) | Ai ghi |
-|---|--------|---------|------------------------------------|--------|
-| 1 | `sc_id` | `{UC-ID}-SC{N}` — khóa chính của row | `{UC-ID}-SC{N}` | generate-bdd |
-| 2 | `sc_title` | Scenario title text | từ `.feature` | generate-bdd |
-| 3 | `spec_ver` | `@trace.sc_version` hiện tại của scenario | từ `.feature` | generate-bdd / validate-traces (reconcile) |
-| 4 | `gen_ver` | Version tại thời điểm code được sinh | `—` | generate-code |
-| 5 | `implemented_by` | `ClassName.method` cài đặt scenario | `—` | generate-code |
-| 6 | `test_count` | Số test verify scenario | `—` | dev-gen-test |
-| 7 | `test_classes` | Danh sách test class | `—` | dev-gen-test |
-| 8 | `dev_selftest` | Kết quả dev self-check: `pass` / `fail` / `not_run` | `—` | **dev-run-test** |
-| 9 | `dev_selftest_at` | Ngày chạy dev self-check (`YYYY-MM-DD`) | `—` | **dev-run-test** |
-| 10 | `qc_status` | Kết quả QC chính thức: `pass` / `fail` / `skip` / `not_run` | `—` | **qc-run-test** |
-| 11 | `qc_run_at` | Ngày chạy QC (`YYYY-MM-DD`) | `—` | **qc-run-test** |
-| 12 | `qc_owner` | **Đang chờ ai** (PM view) khi SC chưa pass: `dev` / `po` / `—` | `—` | **qc-run-test** / **report-bug** |
-| 13 | `qc_blocked_by` | Artifact liên quan: `BUG-{id}` / `GAP-{id}` / `—` | `—` | **qc-run-test** / **report-bug** |
-| 14 | `prd_version` | `@trace.prd_version` từ `.feature` header | từ `.feature` | generate-bdd |
-| 15 | `bdd_version` | `@trace.bdd_version` từ `.feature` header | từ `.feature` | generate-bdd |
-| 16 | `tech_doc_revision` | Revision tech-doc gộp `{TICKET-ID}-tech-design.md` (§4 backend) tại thời điểm codegen | `—` | generate-code / review-tech-docs |
-| 17 | `fe_tech_doc_revision` | Revision **cùng** tech-doc gộp, ghi khi FE `--phase=integration` wire adapter theo §4.5.4 (drift-detect riêng cho FE) | `—` | generate-code `--phase=integration` |
-| 18 | `prd_status` | `\| **Status** \|` từ PRD metadata | từ PRD | generate-bdd |
-| 19 | `uc_status` | Trạng thái duyệt BDD của UC — **gương của `@trace.status`** (`.feature`): `draft` / `approved` | `draft` (UC mới) | generate-bdd (init) · validate-traces (sync ← `@trace.status`) · review-context (reset draft khi `--fix`/`--resume`) |
-| 20 | `fe_phase` | FE phase khi implement (`ui` / `integration`) | `—` | generate-code `--phase` |
-| 21 | `status` | Trạng thái tổng hợp: `OK` / `DRIFT` / `GAP` / `UNTRACKED` | `UNTRACKED` | validate-traces |
-| 22 | `last_updated` | Ngày update gần nhất (`YYYY-MM-DD`) | today | mọi command ghi row |
-
-> **`qc_owner` / `qc_blocked_by` (PM "waiting-on" view):** dành cho PO kiêm PM xem **case nào đang chờ ai**. `/qc-run-test` set khi ghi `qc_status`: product-gap FAIL → `qc_owner=dev`; `skip`/`not_run` do `DOC_GAPS` 🔴 Blocker mở → `qc_owner=po` + `qc_blocked_by=GAP-{id}`; `pass` → cả hai về `—`. `/report-bug` backfill `qc_blocked_by=BUG-{id}` (+ `qc_owner` theo layer) cho SC khớp. `/validate-traces` tổng hợp `waiting_dev` / `waiting_po` cho dashboard.
-
-> **Re-generation rules (generate-bdd):** SC đã có trong TSV & `spec_ver` không đổi → chỉ update `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Nếu `spec_ver` đổi → thêm `spec_ver` và set `status = DRIFT` ngay. SC mới → append với `gen_ver`/`implemented_by`/`test_count`/`test_classes`/`dev_selftest`/`dev_selftest_at`/`qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by`/`tech_doc_revision`/`fe_tech_doc_revision` = `—`. SC bị xóa khỏi `.feature` → xóa row.
-
-> **Backward-compat:** TSV cũ thiếu cột mới ở header → `/validate-traces` đọc thành giá trị rỗng, không lỗi: `qc_owner`/`qc_blocked_by` (trước 19 cột) → `null`; `fe_tech_doc_revision` (trước 22 cột) → `0`. Lần `/generate-bdd` re-gen kế tiếp tự nâng header lên 22 cột.
-
----
-
-## Two independent signals: dev_selftest vs qc_status
-
-Trace TSV mang **hai cột tín hiệu độc lập** — không bao giờ trộn:
-
-| | `dev_selftest` (+ `dev_selftest_at`) | `qc_status` (+ `qc_run_at`) |
-|---|--------------------------------------|------------------------------|
-| Ghi bởi | `/dev-run-test` | `/qc-run-test` |
-| Ý nghĩa | Dev tự smoke-check code mình vừa sinh | Kết quả QC automation **chính thức** |
-| Giá trị | `pass` / `fail` / `not_run` | `pass` / `fail` / `skip` / `not_run` |
-| Stack | Dev implementation module | `qc-playwright` module |
-| Coverage chính thức? | **KHÔNG** — chỉ là dev self-check | **CÓ** — official QC result |
-| Keyed by | `@trace.verifies={UC-ID}` | `@trace.verifies={UC-ID}-SC{N}` |
-
-`/validate-traces` chỉ **đọc** hai cột này cho report — không bao giờ ghi đè (mỗi cột do command sở hữu nó quản lý). Living Docs hiển thị cả hai cạnh nhau.
-
----
-
-## Status computation (validate-traces)
-
-`/validate-traces` tính cột `status` theo thứ tự ưu tiên (rule đầu tiên khớp thì dừng):
-
-| Rule | Status | Điều kiện |
-|------|--------|-----------|
-| 1 | `UNTRACKED` | `implemented_by == —` (chưa sinh code) |
-| 2 | `GAP` | `implemented_by != —` AND (`test_count == —` OR `test_count == 0`) |
-| 3 | `DRIFT` | `spec_ver != gen_ver` (scenario đổi sau lần codegen gần nhất) |
-| 4 | `OK` | tất cả: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |
-
-Ngoài ra `/validate-traces` còn flag **`PRD_DRIFT`** (PRD version trong code/TSV trễ hơn PRD file hiện tại), **`TECHDOC_DRIFT`** (code BE sinh từ revision cũ của tech-doc gộp — so `tech_doc_revision`), và **`FE_TECHDOC_DRIFT`** (FE integration wire theo §4.5.4 ở revision cũ của cùng doc — so `fe_tech_doc_revision`).
-
----
-
-## @trace tags across artifacts
-
-Mọi artifact link với nhau qua `@trace.*` tags.
-
-**`.feature` files:**
-```gherkin
-# @trace.id: FEAT-001-UC1
-# @trace.service: web-admin
-# @trace.module: react
-# @trace.status: draft          # draft/approved — người đặt approved sau review-context BDD sạch; mirror → uc_status
-# @trace.prd_version: 1.2
-# @trace.bdd_version: 3
-# @trace.api_source: existing   # brownfield: API đã tồn tại, contract lấy từ PRD
-```
-Per-scenario trong file: `# @trace.scenario: {UC-ID}-SC{N}`, `# @trace.sc_version: 1.0`, `# @trace.business_rules: ...`.
-
-**Code:**
-```java
-// @trace.implements=FEAT-001-UC1-SC2
-// @trace.prd_version=1.2
-// @trace.bdd_version=3
-// @trace.tech_doc_revision=2
-```
-
-**Dev self-check tests:**
-```java
-// @trace.verifies=FEAT-001-UC1
-// @trace.service=api-backend
-// @trace.test_type=integration
-```
-
-**QC tests** (`qc-playwright`, drive `qc_status`):
-```python
-# @trace.verifies={UC-ID}-SC{N}
-# @trace.source=<official .feature path>
-# @trace.test_type=functional|integration|e2e|non-functional
-```
-
----
-
-## trace-report.json
-
-`/validate-traces` ghi `{paths.trace_dir}/trace-report.json` — single source of truth cho web dashboards. Cấu trúc rút gọn:
-
-- `generated_at`, `domain`
-- `summary` — aggregates: `total_prds`, `approved_prds`, `total_ucs`, `approved_ucs`, `draft_ucs`, `total_scs`, `coded_scs`, `tested_scs`, `code_coverage_pct`, `test_coverage_pct`, `drift_count`, `gap_count`, `untracked_count`, `dev_selftest_passing/failing/not_run`, `qc_passing/failing/skipped/not_run`, `waiting_dev`, `waiting_po`, `tech_docs_count`
-- `prds[]` → `ucs[]` → `scenarios[]` — mỗi scenario có đầy đủ các trường của TSV row (gồm `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`)
-- `issues` — phân loại: `drift`, `gap`, `untracked`, `prd_version_drift`, `techdoc_drift`, `fe_techdoc_drift` (kèm `platform`), mỗi entry kèm `fix` command gợi ý
-
-**TSV `"—"` → JSON mapping:** `implemented_by: "—"` → `null` · `test_count: "—"` → `0` · `test_classes: "—"` → `[]` · `tech_doc_revision: "—"` → `0` · `fe_tech_doc_revision: "—"` → `0` · `dev_selftest: "—"` → `"not_run"` · `dev_selftest_at: "—"` → `null` · `qc_status: "—"` → `"not_run"` · `qc_run_at: "—"` → `null`.
-
-> **Umbrella mode:** khi `spec_source` set, `.trace/*.tsv` authoritative nằm **một chỗ** ở `{spec_source}/.trace/` (committed — PM quản lý tập trung; mỗi scenario mang `@trace.service`). `/validate-traces` (hoặc `/sync`) sinh `trace-report.json` vào `{spec_source}/.living-docs/` + mirror `./.trace/trace-report.json` ở workspace hiện tại — cả hai generated, gitignore. (Không có `spec_source` → `.trace` per-service.)
-
----
-
-*Xem thêm:* [Command Reference](commands.md) (`/validate-traces`, `/qc-run-test`, `/dev-run-test`) · [03 · Concepts](../03-concepts/) (traceability system).

package/docs/06-commands/README.md

@@ -1,75 +0,0 @@
-[📚 Docs](../README.md) › Commands (Dễ Hiểu)
-
-# 06 · Commands — Giải Thích Dễ Hiểu
-
-> Mỗi trang giải thích **luồng chạy của một slash command** bằng ngôn ngữ dễ hiểu + ví von đời thường. Bổ sung cho đặc tả chính thức ở [05 · Reference](../05-reference/) — mục này ưu tiên *trực giác*, giúp bạn hình dung "lệnh làm gì, theo trình tự nào, vì sao" trước khi đọc chi tiết.
-
-Đủ **30 lệnh**, gom theo phase pipeline. Mỗi trang có một ví von + các bước + vị trí trong dây chuyền + một câu chốt.
-
----
-
-## Discovery & PRD (PO/BA)
-
-| Trang | Ví von |
-|-------|--------|
-| [/setup-ai-first](explain-setup-ai-first.md) | Dựng khung xưởng một-lần (thư mục + nội quy + config + từ điển) |
-| [/define-product](explain-define-product.md) | Buổi phỏng vấn 8 chặng moi ý tưởng thành hồ sơ |
-| [/generate-prd](explain-generate-prd.md) | Thư ký biến biên bản phỏng vấn thành hồ sơ chuẩn |
-| [/refine-prd](explain-refine-prd.md) | Tổ soi bài 3 lăng kính nâng chất nội dung PRD |
-| [/review-context](explain-review-context.md) | Cửa kiểm định chất lượng cuối (PRD & BDD) |
-
-## Design & BDD
-
-| Trang | Ví von |
-|-------|--------|
-| [/generate-design-spec](explain-generate-design-spec.md) | Bản thiết kế màn hình bám Figma thật, 2 tầng ngôn ngữ |
-| [/generate-bdd](explain-generate-bdd.md) | Biến yêu cầu thành kịch bản kiểm thử (web/app/system) |
-
-## Tech Design & Code (Dev)
-
-| Trang | Ví von |
-|-------|--------|
-| [/generate-tech-docs](explain-generate-tech-docs.md) | Bản vẽ thi công (BE contract / FE client design) |
-| [/review-tech-docs](explain-review-tech-docs.md) | Hội đồng nghiệm thu bản vẽ + cổng chữ ký liên team |
-| [/generate-code](explain-generate-code.md) | Thợ thi công bám bản vẽ, làm đúng một hạng mục |
-| [/review-code](explain-review-code.md) | Giám sát công trình soi code 4 mặt |
-| [/map-testids](explain-map-testids.md) | Dán nhãn tên cố định lên element FE tái dùng/đã-có |
-
-## Dev Test & Fix
-
-| Trang | Ví von |
-|-------|--------|
-| [/dev-gen-test](explain-dev-gen-test.md) | Sinh bộ tự-kiểm nhanh của dev |
-| [/dev-run-test](explain-dev-run-test.md) | Bấm nút chạy tự-kiểm + chẩn lỗi theo platform |
-| [/dev-smoke-test](explain-dev-smoke-test.md) | Thử máy tại chỗ trên service/app đang chạy |
-| [/debug](explain-debug.md) | Hỏi nhanh đồng nghiệp — phân tích lỗi, không sửa |
-| [/fix-bug](explain-fix-bug.md) | Xử lý sự cố có hồ sơ (truy gốc → sửa → test hồi quy) |
-
-## QC Automation (dây chuyền 6 trạm)
-
-| Trang | Ví von |
-|-------|--------|
-| [/qc-analyze](explain-qc-analyze.md) | Trạm 1 — QC Analyst: phân rã yêu cầu + gap |
-| [/qc-plan](explain-qc-plan.md) | Trạm 2 — QC Planner: rủi ro + câu hỏi cho dev |
-| [/qc-design-test](explain-qc-design-test.md) | Trạm 3 — QC Designer: viết test case Markdown |
-| [/qc-review](explain-qc-review.md) | Trạm 4 — cổng review hai chiều (case & script) |
-| [/qc-run-test](explain-qc-run-test.md) | Trạm 5 — QC Runner: chạy Playwright, ghi `qc_status` chính thức |
-| [/qc-report](explain-qc-report.md) | Trạm 6 — report + evidence, đẩy product-gap về PO/Dev |
-
-## Feedback & Vận hành
-
-| Trang | Ví von |
-|-------|--------|
-| [/report-bug](explain-report-bug.md) | Phiếu sự cố có hồ sơ spec (tester/QC) |
-| [/propose-scenario](explain-propose-scenario.md) | Hòm góp ý kịch bản test mới |
-| [/learn](explain-learn.md) | Dán tờ nhắc guardrail lên tường xưởng |
-| [/validate-traces](explain-validate-traces.md) | Đợt kiểm kê độ phủ spec↔code↔test |
-| [/generate-spec-manifest](explain-generate-spec-manifest.md) | Lập sổ mục lục spec cho agent ngoài |
-| [/sync](explain-sync.md) | Nghi thức đầu ngày đồng bộ umbrella |
-| [/update-framework](explain-update-framework.md) | Thay bộ đồ nghề framework lên bản npm mới |
-
----
-
-*Muốn giải thích dễ hiểu cho một lệnh khác → thêm một trang `explain-{command}.md` vào thư mục này và một dòng ở bảng phù hợp.*
-
-*Xem thêm:* [05 · Reference › Commands](../05-reference/commands.md) (đặc tả đầy đủ) · [03 · Concepts › Cơ chế (dễ hiểu)](../03-concepts/mechanisms-explained.md) (giải thích cơ chế framework).

package/docs/06-commands/explain-debug.md

@@ -1,32 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /debug
-
-# `/debug` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Phân tích nhanh một lỗi/hành vi lạ — **chỉ phân tích, không sửa, không cần ticket**. Khác `/fix-bug` (workflow đầy đủ). Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/debug` như **hỏi nhanh một đồng nghiệp rành việc**: bạn đưa lỗi (stack trace, test fail, hoặc câu hỏi code), nó chỉ ra *nguyên nhân gốc* và *cách sửa gợi ý* — gọn, không lôi cả quy trình ra.
-
----
-
-## Cách chạy
-
-Đầu tiên nó hỏi **tình huống của bạn là gì**:
-1. Đã có stack trace/log → dán vào.
-2. Cần tái hiện trước → nó chỉ lệnh chạy service (từ `service_run`).
-3. Test đang fail → nó chỉ lệnh test, bạn dán output fail.
-4. Câu hỏi code (không cần chạy) → hỏi thẳng.
-
-Rồi nó phân tích:
-- **Stack trace:** đọc từ **dưới lên** (`Caused by:` mới là gốc thật).
-- Đối chiếu **bảng lỗi thường gặp** theo platform (BE / web / mobile / AI-LLM) để đoán nguyên nhân + hướng fix.
-- **Test fail:** so Expected vs Actual, kiểm mock setup, kiểm assertion.
-
-Ra một báo cáo: Lỗi · Nguyên nhân gốc · Vị trí (file/dòng/layer) · Cách sửa · Rule liên quan (CLAUDE.md) · Bước kế (`/fix-bug` nếu muốn sửa trọn vẹn).
-
-Nếu nguyên nhân là **lỗi AI hay lặp khi sinh code** → hỏi có ghi thành *lesson* không.
-
-## Vị trí trong dây chuyền
-
-`/debug` là công cụ **cầm tay dùng bất cứ lúc nào** — không gắn cứng vào một chặng. Thường gọi khi `/dev-run-test` hoặc `/dev-smoke-test` báo lỗi.
-
-> **Một câu chốt:** `/debug` là "hỏi nhanh đồng nghiệp" — phân loại tình huống, đọc lỗi từ gốc, tra bảng lỗi theo platform, ra nguyên nhân + cách sửa; chỉ phân tích, muốn sửa trọn vẹn thì sang `/fix-bug`.

package/docs/06-commands/explain-define-product.md

@@ -1,43 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /define-product
-
-# `/define-product` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Bước **đầu tiên** của cả dây chuyền: biến một ý tưởng tính năng trong đầu PO thành một **hồ sơ khám phá** (product-definition) đủ rõ để sau này viết PRD. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/define-product` như một **buổi phỏng vấn khai thác ý tưởng có người dẫn**. AI đóng vai người phỏng vấn: hỏi bạn từng câu, ghi biên bản, và **chốt từng chặng** trước khi đi tiếp.
-
----
-
-## Ví von: một buổi phỏng vấn 8 chặng, mỗi chặng có "chốt"
-
-Bạn tới với một ý tưởng còn mơ hồ. AI dẫn bạn qua 8 chặng, hỏi **từng câu một** (không dồn một lúc), và sau mỗi chặng quan trọng phải nghe bạn nói "✅ đúng rồi" mới đi tiếp (gọi là **CHECKPOINT**):
-
-1. **Chặng 0 — Tự tra bối cảnh:** AI tự quét dự án xem có khái niệm/rule/feature liên quan nào (không cần bạn trả lời). Nếu thấy thuật ngữ lạ lặp lại → để dành hỏi ở Chặng 3.
-2. **Chặng 1 — Định nghĩa tính năng:** vì sao cần, giải quyết vấn đề gì, mong muốn kết quả gì, ai dùng, làm gì / không làm gì, user story.
-3. **Chặng 2 — Luồng người dùng:** vào từ đâu, đi qua các bước nào, có những màn hình chính nào, ra khỏi ra sao, các tình huống lỗi.
-4. **Chặng 3 — Hỏi cho hết mơ hồ:** AI tự thấy chỗ nào còn hổng thì hỏi thêm, lặp tới khi **không còn mục tồn đọng**.
-5. **Chặng 4 — Business Rules:** rút ra các luật "hệ thống PHẢI / KHÔNG được làm gì".
-6. **Chặng 5 — Business Logic:** mỗi luật chạy theo logic nghiệp vụ nào (rẽ nhánh, công thức).
-7. **Chặng 6 — Acceptance Criteria:** tiêu chí nghiệm thu, mỗi cái phải kiểm được pass/fail.
-8. **Chặng 7 — Tự kiểm độ phủ:** AI tự lập bảng "mỗi hành động có đủ Rule + Logic + AC chưa?", còn thiếu (GAP) thì cảnh báo.
-
-### Nói bằng lời nghiệp vụ
-Suốt buổi phỏng vấn, AI tránh hỏi chuyện kỹ thuật (API, database…) — chỉ khai thác **WHAT** (cần gì), không phải **HOW** (làm bằng gì).
-
----
-
-## Bỏ dở cũng không sao — resume được
-
-Sau mỗi chặng được chốt, AI ghi lại "đã xong tới chặng mấy" vào file. Nếu buổi phỏng vấn bị ngắt, lần sau chạy lại **đi tiếp từ chặng kế** — không phải làm lại từ đầu.
-
----
-
-## Kết quả & vị trí trong dây chuyền
-
-Ra một file `product-definition/{TICKET-ID}-{slug}.md`. Cái **slug** (tên rút gọn của feature) sinh ở đây và **dùng nguyên xuyên suốt** PRD, BDD, tech-docs, design-spec sau này.
-
-```
-[ define-product ◀ bạn ở đây ] → generate-prd → design-spec → generate-bdd → …
-```
-
-> **Một câu chốt:** `/define-product` là buổi phỏng vấn có người dẫn để **moi ý tưởng ra thành hồ sơ rõ ràng** — hỏi từng câu, chốt từng chặng, tự kiểm độ phủ; PRD chỉ được sinh khi buổi này xong hẳn (đủ 7 chặng).

package/docs/06-commands/explain-dev-gen-test.md

@@ -1,28 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /dev-gen-test
-
-# `/dev-gen-test` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Sinh **test tự-kiểm của dev** (smoke) từ các kịch bản BDD — để dev tự tin code chạy trước khi review. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/dev-gen-test` như **bộ tự-kiểm nhanh của thợ**: nhìn từng kịch bản BDD của một UC + code đã viết, rồi sinh các bài test tương ứng (unit / component / widget / e2e tuỳ platform) để dev tự chạy.
-
-> **Quan trọng — đây KHÔNG phải bộ test chính thức của QC.** Nó là *dev self-check*: một tín hiệu lên Living Docs cho QC biết "dev đã tự chạy kiểm rồi". Bộ test authoritative có flow riêng của QC.
-
----
-
-## Cách chạy
-
-- **Nhận diện platform** từ `@trace.module` (backend / web-frontend / mobile) để chọn đúng khuôn test (java-spring, golang, react, flutter, swift…).
-- Hiện **plan** (bao nhiêu scenario, file impl nào) → chờ Y.
-- Sinh test, mỗi test gắn nhãn `@trace.verifies={UC-ID}`, mỗi scenario BDD có ≥1 test.
-- Cập nhật trace `.tsv`: `test_count`, `test_classes`, và `dev_selftest = not_run` (đã có test nhưng chưa chạy — `/dev-run-test` mới set pass/fail).
-
-Có quy tắc chất lượng theo platform: BE mock đúng layer, FE/Mobile không hardcode delay, dùng accessible query…
-
-## Vị trí trong dây chuyền
-
-```
-generate-code → [ dev-gen-test ◀ bạn ở đây ] → dev-run-test → review-code
-```
-
-> **Một câu chốt:** `/dev-gen-test` sinh bộ tự-kiểm nhanh cho dev (theo platform, bám từng scenario BDD) — một tín hiệu self-check, không phải bộ test QC chính thức.

package/docs/06-commands/explain-dev-run-test.md

@@ -1,24 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /dev-run-test
-
-# `/dev-run-test` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> **Chạy** các test do `/dev-gen-test` sinh ra, phân tích lỗi, và ghi kết quả pass/fail vào trace. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/dev-run-test` như **bấm nút chạy bộ tự-kiểm** rồi đọc kết quả: chạy test, cái nào fail thì tra bảng "lỗi thường gặp → nguyên nhân → cách sửa" theo đúng platform, và ghi lại "lần chạy gần nhất của dev: pass hay fail".
-
----
-
-## Cách chạy
-
-- **Chọn đúng lệnh test** theo module (`mvn test`, `go test`, `vitest`, `flutter test`…). Ở chế độ umbrella thì `cd` vào đúng service submodule trước (mỗi service có runner riêng).
-- **Chạy** (có thể thu hẹp theo class cho nhanh).
-- **Phân tích lỗi:** với mỗi test fail, đối chiếu bảng lỗi theo platform (vd BE "Expected 200 got 401 → thiếu setup auth"; FE "Unable to find role → element chưa render, bọc waitFor"; Flutter "pumpAndSettle timed out"…).
-- **Ghi trace:** cập nhật `dev_selftest = pass/fail/not_run` + `dev_selftest_at`. **Không bao giờ** đụng `qc_status` — đó là tín hiệu QC chính thức, tách riêng.
-
-## Vị trí trong dây chuyền
-
-```
-dev-gen-test → [ dev-run-test ◀ bạn ở đây ] → (pass) → review-code   |   (fail) → fix-bug / sửa test
-```
-
-> **Một câu chốt:** `/dev-run-test` chạy bộ tự-kiểm của dev, chẩn lỗi theo bảng-lỗi-từng-platform, và ghi kết quả `dev_selftest` — một tín hiệu riêng, độc lập với kết quả QC chính thức.

package/docs/06-commands/explain-dev-smoke-test.md

@@ -1,25 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /dev-smoke-test
-
-# `/dev-smoke-test` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Kiểm nhanh một UC trên **service/app đang chạy thật**. Khác `/dev-run-test` (không cần server sống). Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/dev-smoke-test` như **thử máy tại chỗ**: service/app đã bật sẵn, ta gọi thẳng endpoint (BE) hoặc bấm thử luồng trên màn (FE/App) để xem "chạy thật có ra đúng không".
-
----
-
-## Cách chạy (tuỳ platform)
-
-- **Backend:** kiểm service đã chạy chưa (curl health endpoint) → tìm endpoint của UC (theo `@trace.implements`) → lấy token nếu cần → gọi `curl` GET/POST → đọc mã trạng thái (200 OK, 200-nhưng-sai-data → lỗi logic, 401/403/500 → theo bảng).
-- **Web:** kiểm dev server → chạy E2E smoke (Playwright/Cypress lọc theo UC), hoặc thử tay trên browser.
-- **Mobile:** cài build lên device/emulator → đi qua màn của UC, làm hành động chính (When) → xác nhận kết quả (Then) → hốt log nếu crash.
-
-Kết quả là một bảng ✅ (ổn) / ⚠️ (chạy nhưng sai data → lỗi logic) / ❌ (lỗi/chưa chạy). Có vấn đề → dán vào `/debug` hoặc mở `/fix-bug`.
-
-## Vị trí trong dây chuyền
-
-```
-generate-code → dev-gen-test → dev-run-test → [ dev-smoke-test ◀ thử máy thật ] → PR
-```
-
-> **Một câu chốt:** `/dev-smoke-test` là "thử máy tại chỗ" trên service/app đang chạy thật — gọi endpoint hoặc bấm luồng để xác nhận kết quả thực, khác với `/dev-run-test` chạy test không cần server sống.

package/docs/06-commands/explain-fix-bug.md

@@ -1,28 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /fix-bug
-
-# `/fix-bug` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Workflow **fix bug đầy đủ**: tìm nguyên nhân → sửa → test hồi quy → build → commit → đóng bug. Khác `/debug` (chỉ phân tích). Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/fix-bug` như **quy trình xử lý sự cố có hồ sơ**: không chỉ vá, mà còn truy nguyên nhân gốc, thêm test chống tái phát, build kiểm, commit đúng nhánh, và đóng phiếu bug.
-
----
-
-## Sáu chặng
-
-1. **Gom thông tin:** nhận ticket / một `{BUG-ID}` đã file (từ `/report-bug` — đọc luôn spec context, AC bị vi phạm) / hoặc mô tả (hỏi: xảy ra ở đâu, tái hiện sao, expected vs actual, log).
-2. **Truy nguyên nhân gốc:** tra bảng "loại bug → chỗ hay gặp → cách kiểm" theo platform. Ra **CHECKPOINT** (root cause, file ảnh hưởng, fix đề xuất, mức rủi ro hồi quy) → chờ Y.
-3. **Sửa:** tạo branch `fix/...` (umbrella thì `cd` vào service submodule), áp fix, gắn nhãn `@trace.fixes`.
-4. **Test hồi quy:** thêm một test tái hiện bug (chống tái phát), chạy tới khi xanh (tối đa 3 vòng).
-5. **Build & commit:** build kiểm, commit; umbrella thì **push 2 tầng** (service submodule → bump pointer umbrella).
-6. **Đóng bug (nếu fix một `{BUG-ID}`):** đặt `State: Fixed` + ghi Resolution. **Chưa Closed** — QC sở hữu việc verify: khi `/qc-run-test` chạy lại pass thì mới `Closed`.
-
-Cuối cùng có thể hỏi ghi *lesson* nếu nguyên nhân là lỗi AI hay lặp.
-
-> **Ranh giới:** `/fix-bug` chỉ sửa **code**, không bao giờ sửa PRD/BDD (đổi spec là việc PO/Dev theo bug-flow).
-
-## Vị trí trong dây chuyền
-
-`/fix-bug` gọi khi review/test/QC phát hiện bug thật (từ `/review-code`, `/dev-run-test`, hoặc `/report-bug` của QC).
-
-> **Một câu chốt:** `/fix-bug` là xử lý sự cố có hồ sơ — truy gốc, sửa code (không đụng spec), thêm test hồi quy, build + commit 2 tầng, và chuyển bug sang Fixed để QC verify đóng.

package/docs/06-commands/explain-generate-bdd.md

@@ -1,45 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /generate-bdd
-
-# `/generate-bdd` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Biến **PRD đã duyệt** (+ Design Spec) thành các **kịch bản kiểm thử** viết bằng ngôn ngữ nghiệp vụ (file `.feature` — Gherkin Given/When/Then). Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/generate-bdd` như một người **biến yêu cầu thành kịch bản diễn thử**: đọc PRD, viết ra từng tình huống "cho trạng thái này → khi làm hành động kia → thì kết quả phải thế này". Mỗi AC/BR đều phải có ít nhất một kịch bản phủ.
-
----
-
-## Trước khi viết, hỏi/kiểm mấy điều
-
-- **PRD duyệt chưa?** Chưa duyệt (draft) → cảnh báo mềm, hỏi có làm tiếp không (cho phép prototype).
-- **Cho platform nào?** web / app / **system** (BDD tầng hệ thống). Từ vựng viết kịch bản đổi theo: web "clicks", app "taps", system "the system returns" (không dùng từ UI).
-- **Có Design Spec chưa?** (chỉ FE/App) — nếu có và đã approved → rút thêm các **Screen State** (loading/error/empty) và **AC-UI** để phủ; chưa sẵn sàng → cảnh báo mềm.
-
----
-
-## Nét đặc thù: 3 cơ chế đáng nhớ
-
-**1. Việc lớn thì chia cho "thợ phụ" (orchestration).** PRD lớn (> 3 UC hoặc > 300 dòng) → session chính thành "sếp", **giao mỗi UC cho một sub-agent** làm song song cho nhanh và đỡ sót. PRD nhỏ thì làm một mình.
-
-**2. System BDD = tổng hợp từ web + app.** Khi làm platform *system*, nó **đọc lại BDD web & app đã có** rồi gộp thành hợp đồng tầng hệ thống. Nếu web và app **mong đợi khác nhau** (vd web muốn A, app muốn B) → dừng ở CHECKPOINT bắt bạn chọn cách hoà giải (gộp chung / tách endpoint / theo header…). Nếu PRD là brownfield (API có sẵn) thì dùng thẳng contract trong PRD, khỏi tổng hợp.
-
-**3. PRD đổi thì bắt kịp (version drift).** Nếu BDD cũ sinh từ PRD v1.0 mà PRD giờ v1.2 → đọc Change Log, hỏi cập nhật phần ảnh hưởng (Y) hay làm lại toàn bộ (F). Không chắc đổi ở đâu → khuyên làm lại toàn bộ cho an toàn.
-
----
-
-## Luật viết kịch bản (giữ chất lượng)
-
-Có bộ luật R1–R10 (mỗi kịch bản đủ Given/When/Then, một hành vi mỗi kịch bản, dùng ngôn ngữ nghiệp vụ không dùng selector/API, tên kịch bản là *kết quả nghiệp vụ*…) và bộ tuân thủ C.1–C.5 (mỗi thành phần Wireframe/AC/BR đều phải có kịch bản phủ, 0 thuật ngữ cấm…).
-
-Trước khi sinh, nó trình **outline** các kịch bản cho bạn xác nhận (thêm/bớt) → rồi mới viết.
-
----
-
-## Kết quả & vị trí trong dây chuyền
-
-Ra các file `.feature` + cập nhật **trace `.tsv`** (bảng theo dõi mỗi kịch bản: version, ai implement, trạng thái test…).
-
-```
-PRD duyệt → [ generate-bdd ◀ bạn ở đây ] (web → app → system) → review-context(BDD) → generate-tech-docs → …
-```
-
-> **Một câu chốt:** `/generate-bdd` biến yêu cầu thành kịch bản kiểm thử nghiệp vụ; chia việc cho thợ phụ khi PRD lớn, tổng hợp System BDD từ web+app (chặn lại khi hai bên mâu thuẫn), và bám version PRD để không lệch.

package/docs/06-commands/explain-generate-code.md

@@ -1,53 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /generate-code
-
-# `/generate-code` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Từ **BDD + tech-design đã duyệt**, sinh **code thật**. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/generate-code` như một **thợ thi công theo bản vẽ**: đọc kịch bản (BDD) + bản vẽ kỹ thuật (tech-design), rồi viết code đúng theo đó, có gắn "nhãn truy vết" để sau này biết dòng code nào phục vụ kịch bản nào.
-
----
-
-## Kỷ luật số 1: chỉ làm đúng một hạng mục (Scope Lock)
-
-Thợ này **chỉ đọc và implement đúng một file feature** được giao — **không** ngó sang các `.feature` khác cùng folder, kể cả khi dùng chung entity. Tránh làm lan man ngoài phạm vi.
-
----
-
-## Có thể làm "phần thô" trước, "đường ống thật" sau (Phase)
-
-Với FE/App, code chia 2 pha để không phải đợi backend:
-
-- **`--phase=ui`** — dựng UI + một **lớp mock** (giả lập API) dựa trên hợp đồng/System BDD. Tester test được ngay, không cần BE deploy.
-- **`--phase=integration`** — thay mock bằng **lời gọi API thật** theo bản vẽ FE (§4). Giữ lại mock cho unit test.
-- *(không flag)* — làm đầy đủ (thường cho BE).
-
-**Bám Figma thật khi dựng UI:** nếu bật được **Figma Dev Mode MCP local** (app desktop), thợ đọc layout/token/component thật để code chính xác hơn nhiều link web trần; chưa bật thì gợi ý bật, hoặc skip (fallback text spec).
-
----
-
-## Trước khi gõ code
-
-- **Guard:** BDD/Design Spec chưa duyệt → cảnh báo mềm.
-- **Đọc trace:** xem scenario nào chưa có code (UNTRACKED), scenario nào đã đổi (DRIFT) cần làm lại, cái nào bỏ qua.
-- **File Scan:** phân loại mỗi file cần **CREATE** (mới) / **EXTEND** (chỉ thêm method, không viết lại code cũ) / **SKIP**.
-- Hiện **plan** + chờ Y, rồi tạo **branch** riêng.
-
----
-
-## Khi gõ code
-
-- Viết theo **đúng thứ tự layer** trong CLAUDE.md (DTO → Entity → Repository → Service → Facade → Controller).
-- Gắn **nhãn `@trace.implements`** ở layer entry-point (Controller/handler) kèm version PRD/BDD/tech-doc — để `/validate-traces` bắt được drift sau này.
-- **(UI FE/App)** phát **test-id ổn định** cho mỗi element có action (theo §4.5.6 của tech-doc gộp) để QC định vị.
-- Tự review 3 vòng, **build thử** (tối đa 3 lần retry), cập nhật trace `.tsv`, rồi commit.
-
----
-
-## Vị trí trong dây chuyền
-
-```
-tech-docs approved → [ generate-code ◀ bạn ở đây ] → review-code → dev-gen-test → dev-run-test → QC
-```
-
-> **Một câu chốt:** `/generate-code` là thợ thi công bám bản vẽ — chỉ làm đúng một feature, có thể dựng UI-với-mock trước rồi lắp API thật sau, gắn nhãn truy vết từng dòng, và luôn build thử trước khi commit.

package/docs/06-commands/explain-generate-design-spec.md

@@ -1,54 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /generate-design-spec
-
-# `/generate-design-spec` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Từ PRD, sinh **bản đặc tả thiết kế màn hình** cho FE/App — bám **Figma thật**. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/generate-design-spec` như một người **biên soạn bản thiết kế màn hình**: đọc PRD để biết có những màn nào, rồi với **mỗi màn** mở đúng frame Figma tương ứng để tả layout, thành phần, các trạng thái (bình thường / đang tải / lỗi / trống) — dựa trên **thiết kế thật**, không bịa.
-
----
-
-## Nét đặc thù: bắt buộc bám Figma theo từng màn
-
-Đây là lệnh gen **duy nhất cần "vật liệu ngoài"** (Figma). AI **không đọc được link file Figma trần** — nó cần link **node-level tới từng frame** (URL có `?node-id=`). Nên nó thu **một link cho mỗi màn**, rồi fetch layout/component/token thật của frame đó về mà tả.
-
-- Màn nào có link đọc được → tả dựa trên frame thật.
-- Màn nào **chưa có link** → vẫn sinh nhưng đánh dấu ❌ Missing, và giữ **draft** (chưa cho ký duyệt) tới khi đủ link.
-
----
-
-## Các bước kiểm trước khi sinh
-
-- **PRD duyệt chưa?** Chưa → cảnh báo mềm (cho làm song song).
-- **Platform nào?** backend → **dừng** (BE không có design spec). web / app / app-ios / app-android.
-- **PRD đổi chưa (drift)?** Nếu design-spec cũ dựng từ PRD v cũ mà PRD đã đổi → hỏi cập nhật phần ảnh hưởng hay làm lại.
-- **Chốt danh sách màn** với bạn, rồi thu link Figma từng màn, rồi CHECKPOINT xác nhận.
-
----
-
-## Hai tầng ngôn ngữ (Design Language Guard)
-
-Design Spec là **cầu nối PRD → code**, nên có hai loại bề mặt, ngôn ngữ khác nhau:
-
-- **Tầng A — bề mặt đọc** (danh mục màn, mô tả layout, mô tả các trạng thái, hành động, AC-UI): **thuần nghiệp vụ/UX** — "thanh tiến độ", "nút chính", "trạng thái chưa chọn". KHÔNG nhét tên layer/variant Figma, mã màu hex, số đo px, hay ẩn dụ dữ liệu ("cờ").
-- **Tầng B — cột/phụ lục kỹ thuật** (Component Inventory với tên code + import path, cột link Figma, bảng Design Token): **được giữ code/token** — vì đây là ngăn dành cho FE/Designer.
-
-Nguyên tắc: **không xoá chi tiết kỹ thuật, dồn về đúng tầng.** (Xem thêm [Cơ chế · Business Language Guard](../03-concepts/mechanisms-explained.md).)
-
----
-
-## Cổng tự-rà trước khi ghi
-
-Trước khi ghi file, nó chạy một **checklist bắt buộc**: mọi màn có đủ đặc tả + 3 trạng thái tối thiểu, component đã map hoặc gắn cờ `[NEW]`, chỉ sinh phần đúng platform, AC-UI kiểm được, ngôn ngữ Tầng A sạch. Mục nào fail → ghi cảnh báo vào "Giả định AI" + giữ draft.
-
----
-
-## Kết quả & vị trí trong dây chuyền
-
-Ra `design-spec/{TICKET-ID}-design-spec-{platform}-{slug}.md`. Ký duyệt (PO + Designer đặt approved) **chỉ khi 0 màn Missing**.
-
-```
-PRD duyệt → [ generate-design-spec ◀ bạn ở đây ] → PO+Designer ký duyệt → generate-bdd (đọc AC-UI cho kịch bản FE)
-```
-
-> **Một câu chốt:** `/generate-design-spec` tả màn hình bám Figma thật (mỗi màn một link node-id), phân tầng ngôn ngữ (bề mặt đọc thuần nghiệp vụ, code/token dồn về cột kỹ thuật), và giữ draft cho tới khi đủ frame để ký duyệt.

package/docs/06-commands/explain-generate-prd.md

@@ -1,45 +0,0 @@
-[📚 Docs](../README.md) › [Commands (Dễ Hiểu)](README.md) › /generate-prd
-
-# `/generate-prd` — Giải Thích Luồng Chạy (Ngôn Ngữ Dễ Hiểu)
-
-> Biến **biên bản phỏng vấn** (product-definition) thành một **hồ sơ yêu cầu chuẩn** (PRD) — tài liệu chính thức để cả team dựa vào. Ưu tiên trực giác — đặc tả đầy đủ xem [Reference › Commands](../05-reference/commands.md).
-
-Hình dung `/generate-prd` như một **thư ký biên tập**: nhận biên bản buổi khám phá, sắp xếp lại thành một hồ sơ đúng khuôn (Metadata, Use Case, AC, Business Rule, Wireframe…), đúng thuật ngữ chuẩn, thuần ngôn ngữ nghiệp vụ.
-
----
-
-## Trước khi viết, thư ký kiểm mấy điều
-
-- **Biên bản đã xong chưa?** Nếu product-definition chưa chốt đủ 7 chặng → **dừng**, bảo bạn chạy lại `/define-product` cho xong. PRD là hồ sơ ký duyệt, không dựng từ nguồn còn dang dở.
-- **API thuộc loại nào?** Hỏi **một** câu để chốt loại nguồn API (bạn chỉ chọn loại, không gõ chi tiết):
-  - *existing* — API đã chạy production (AI trích contract as-is vào Appendix, không bịa).
-  - *greenfield* — tự thiết kế sau (ở tech-docs).
-  - *partner* — đối tác làm song song, chưa có contract.
-- **Có link ticket thật không?** AI không tự bịa URL Jira — hỏi bạn, có thì đặt link cạnh mã ticket, không thì để mã trơn.
-- **Tên PO** lấy từ biên bản; thiếu thì hỏi.
-
----
-
-## Viết PRD — kỷ luật quan trọng nhất: "đúng tầng"
-
-Thư ký này rất kỹ về việc **cái gì viết ở đâu** (gọi là *altitude*):
-
-- **AC** (nghiệm thu) = chỉ ghi *kết quả quan sát được* + trỏ số hiệu BR. KHÔNG nhồi cơ chế (số lần thử lại, timeout, nhánh lỗi chi tiết).
-- **BR / Business Logic** = nơi chứa cơ chế "chạy thế nào".
-- **Scope** = ranh giới (làm gì / không làm gì), không định nghĩa thuật ngữ.
-
-Và **thuần nghiệp vụ**: chi tiết kỹ thuật (API, token, DB) → thuộc Tech Docs; chi tiết hình ảnh (màu, animation, pixel) → thuộc Design Spec. PRD chỉ giữ Wireframe ở mức nghiệp vụ (màn có gì, bấm ra kết quả gì).
-
-Ngoài ra thư ký còn giữ **liên kết truy vết**: mỗi AC trỏ về ≥1 BR, mỗi UC liệt kê "AC liên quan", và hai chiều phải khớp nhau — lệch là lỗi, phải sửa trước khi ghi.
-
----
-
-## Kết quả & vị trí trong dây chuyền
-
-Ra file PRD `specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` ở **version 1.0, trạng thái draft**.
-
-```
-define-product → [ generate-prd ◀ bạn ở đây ] → refine-prd → review-context → PO duyệt → generate-bdd
-```
-
-> **Một câu chốt:** `/generate-prd` là thư ký biến biên bản khám phá thành **hồ sơ chuẩn thuần nghiệp vụ**, canh đúng tầng AC/BR và giữ truy vết — rồi chuyển cho `refine-prd`/`review-context` soi lại trước khi PO duyệt.