@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/commands/refine-prd.tmpl

@@ -1,281 +0,0 @@
-# /refine-prd — Phân tích PRD qua 3 lăng kính review
-
-## Gate
-
-*Checkpoint: **chặn CỨNG** — --resume áp findings trực tiếp vào PRD. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
-
-{{include:steps/gate.md}}
-
-*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.*
-
-### Bước 0-C — Resume mode routing *(riêng /refine-prd, chạy ngay sau Bước 0 của Gate)*
-
-Nếu `$ARGUMENTS` chứa `--resume`:
-- Tách `--resume` ra, phần còn lại là `raw_target` (file path hoặc prd-slug).
-- **Nạp minimal context:** đọc `.agent/project-context.yaml`, trích xuất `paths.refinement_dir`
-  (default: `.agent/review` nếu không có hoặc file không tồn tại).
-- Chạy **Bước 1** với `raw_target` để phân giải `prd-slug` và `target_file`.
-  Nếu `raw_target` rỗng → liệt kê các file `*.yaml` trong `{paths.refinement_dir}/` và hỏi user chọn findings file nào.
-- **Bỏ qua Bước 0-B, 2, 3** — apply findings là tác vụ cơ học, không cần model check hay load full context.
-- → Nhảy thẳng tới **Resume Mode** ở cuối lệnh này.
-
-Nếu `$ARGUMENTS` không chứa `--resume` → tiếp tục luồng review bình thường bên dưới.
-
-## Context
-{{include:steps/context-loader.md}}
-
----
-
-## Ngôn ngữ nghiệp vụ *(áp khi viết/áp fix — gồm cả Resume Mode Phase 2)*
-{{include:steps/business-language.md}}
-
----
-
-## Quy trình Review
-{{include:steps/review-fanout.md}}
-
----
-
-## Phân tích — 3 lăng kính (fan out cả ba, rồi hội tụ)
-
-Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
-
-**Tham số truyền vào Quy trình Review:**
-- `GRANULARITY = per-uc` — LUÔN fan-out theo từng UC (bỏ ngưỡng cả-file), để **ngay lần đầu đã lòi phần nhiều issue**, không dồn sang lần sau.
-- `CHANGED_SCOPE` — xác định theo chế độ full/delta ngay dưới đây.
-
-**Chọn full vs delta** *(mặc định: lần đầu FULL, lần sau DELTA)*:
-1. Tách `--full` khỏi `$ARGUMENTS` nếu có.
-2. Kiểm tra `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
-   - **Không tồn tại** (lần đầu review PRD này) → **FULL**: KHÔNG truyền `CHANGED_SCOPE`.
-   - **Tồn tại** + có `--full` → **FULL**: bỏ qua findings cũ, không truyền `CHANGED_SCOPE` (ép quét lại toàn bộ).
-   - **Tồn tại** + KHÔNG có `--full` → so `prd_version` trong findings cũ với `| **Version** |` của PRD hiện tại:
-     - **Bằng nhau** (PRD chưa đổi từ lần review trước) → DỪNG, báo: `"PRD chưa đổi từ v{X} (lần review gần nhất). Không có gì để review lại — dùng --full nếu vẫn muốn quét toàn bộ."`
-     - **Khác** → kiểm tra `applied_to_version` trong findings cũ (version mà lần `--resume` gần nhất của CHÍNH lệnh này đã bump PRD tới) để biết ai gây ra thay đổi:
-       - **`applied_to_version` có mặt VÀ `==` version PRD hiện tại** → PRD đổi đúng bằng phần lệnh này tự áp, không actor khác động vào → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
-       - **`applied_to_version` vắng mặt HOẶC `≠` version hiện tại** → PRD đã bị sửa bởi **actor khác** (lệnh `/review-context`, sửa tay…) sau lần resume này → KHÔNG tin được phạm vi hẹp → **FULL** (KHÔNG truyền `CHANGED_SCOPE`), kèm cảnh báo: `"PRD đổi ngoài tầm theo dõi của findings (applied_to_version={A} ≠ hiện tại={C}); quét lại toàn bộ để khỏi sót UC do người/lệnh khác sửa."`
-
-**DIMENSIONS** = 3 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ó:
-
-<!-- ─────────────────────────────────────────────────────────────────────────────
-  LĂNG KÍNH BỊ TẮT (DISABLED — KHÔNG dùng, KHÔNG fan-out agent cho lăng kính này):
-
-  - **Lăng kính QA (tầng nghiệm thu)**: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
-
-  CÁCH THÊM LẠI QA (khi cần bật lại giai đoạn sau):
-    1. Chuyển bullet QA ở trên ra khỏi block comment này, đặt lên đầu danh sách DIMENSIONS.
-    2. Đổi "3 lăng kính"/"cả ba" → "4 lăng kính"/"cả bốn" ở: dòng tiêu đề (# /refine-prd),
-       heading "## Phân tích", câu "DIMENSIONS = N lăng kính", và steps/review-fanout.md.
-    3. Thêm "QA" lại vào enum của `lens:` trong FINDINGS SCHEMA + vào `by_lens`.
-    4. Thêm "QA" lại vào ghi chú "phán đoán DEV/SA/PO" ở LƯU Ý của schema.
-    5. Rebuild: node bin/build.js
-───────────────────────────────────────────────────────────────────────────── -->
-
-> **Nguyên tắc chung cho DEV & SA — đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ.**
-> Hai lăng kính này dùng con mắt kỹ thuật để **phát hiện chỗ nghiệp vụ mô tả thiếu/mơ hồ/mâu thuẫn đến mức sẽ chặn triển khai** — mục tiêu là **làm rõ vấn đề nghiệp vụ để sau này xử lý được về mặt kỹ thuật**. **KHÔNG** đưa góc nhìn kỹ thuật vào PRD, **KHÔNG** đề xuất giải pháp/cơ chế kỹ thuật. Mọi `finding` và `suggestion` phải **thuần nghiệp vụ** (tuân Business Language Guard): mô tả *cái nghiệp vụ còn thiếu/chưa rõ* và *hỏi cần làm rõ gì*, chứ không nói *làm thế nào về kỹ thuật*.
-
-- **Lăng kính DEV (tầng cơ chế nghiệp vụ)**: Đọc luồng như một dev sắp build — BR (WHAT) + Business Logic (HOW nghiệp vụ) đã **đủ & không mơ hồ để triển khai mà không phải đoán** chưa? Soi: nhánh nghiệp vụ còn thiếu, điều kiện biên chưa nói, đường xử lý khi có lỗi/ngoại lệ bị bỏ ngỏ (vd: "khi thanh toán bị từ chối thì đơn hàng được xử lý ra sao?"), business rule mâu thuẫn hoặc mơ hồ. Diễn đạt gap bằng **ngôn ngữ nghiệp vụ + đặt câu hỏi làm rõ** — **KHÔNG** đề xuất cơ chế kỹ thuật (số lần thử lại, timeout, cấu trúc dữ liệu, API, thư viện) và **KHÔNG** nhồi chi tiết kỹ thuật vào PRD.
-- **Lăng kính SA (tính thông suốt & nhất quán nghiệp vụ)**: Đọc như một architect — toàn bộ luồng nghiệp vụ có **thông suốt & nhất quán** trên cả feature/domain không? Soi: tương tác nghiệp vụ giữa các UC/feature đã định nghĩa chưa, quan hệ giữa các thực thể nghiệp vụ (theo core-entities) có mâu thuẫn/bỏ trống không, trạng thái & vòng đời của đối tượng nghiệp vụ có nhất quán không, quy tắc **ai được làm gì / ai sở hữu gì** (nghiệp vụ đằng sau phân quyền) đã rõ chưa. **KHÔNG** phán về kiến trúc/security/mô hình dữ liệu kỹ thuật, **KHÔNG** đề xuất giải pháp kỹ thuật — chỉ nêu chỗ nghiệp vụ chưa nhất quán/chưa rõ bằng ngôn ngữ nghiệp vụ.
-- **Lăng kính PO**: Scope đã khoanh vùng? Priority rõ chưa? Success metric đã định nghĩa? Rủi ro scope creep?
-
-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.
-
-## File Output
-
-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`
-
-Trước khi ghi file, xác định `recommendation` từ findings đã dedup và sắp xếp:
-- `by_severity.critical ≥ 1` → `BLOCKED`
-- `by_severity.critical = 0` và `by_severity.major ≥ 1` → `NEEDS_REVISION`
-- `by_severity.critical = 0` và `by_severity.major = 0` → `APPROVED_WITH_MINOR_CHANGES`
-
-Đảm bảo `{paths.refinement_dir}/` tồn tại — tạo thư mục nếu chưa có trước khi ghi file.
-
-Ghi `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
-
-```yaml
-prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
-prd_version: "{đọc | **Version** | từ metadata PRD lúc sinh findings — dùng để chọn full/delta lần chạy sau}"
-applied_to_version: ""   # để trống lúc phân tích; --resume sẽ ghi version PRD vừa bump tới. Lần delta sau: nếu version PRD hiện tại ≠ giá trị này → PRD bị actor khác sửa → fallback FULL (xem "Chọn full vs delta")
-generated_at: "{ISO datetime}"
-status: "pending_review"
-
-findings:
-  - id: "F001"
-    lens: "DEV"          # DEV | SA | PO
-    severity: "major"    # critical | major | minor
-    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}"
-    resolution_edge_cases:   # CHỈ điền cho critical/major; minor → để [] (bỏ qua)
-      # Phân tích bậc-hai (advisory, KHÔNG chặn): nếu áp `suggestion` này thì có thể đẻ ra
-      # edge case / side-effect gì — path lỗi mới, va chạm với BR/UC khác, trạng thái biên,
-      # hệ luỵ cross-section. PO đọc để cân nhắc trước khi accept; nếu muốn xử lý → tạo finding mới.
-      - "{edge case có thể phát sinh nếu chốt phương án này}"
-    auto_fixable: false
-    # true  = AI tự tin cao vào suggestion này; Review Board có thể hiển thị nút "quick accept"
-    # false = cần human đọc kỹ và ghi quyết định trước khi accept
-    # Resume Mode luôn áp dụng theo status (accepted|modified), bất kể auto_fixable.
-    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 3 lăng kính
-    #   là phán đoán DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
-    #   quick-accept cho Board, KHÔNG để máy tự áp.
-    status: "pending"
-    applied_via: ""
-    # Vòng đời finding-level (CHUNG với /review-context — Review Board đọc cả hai loại file nên enum phải khớp):
-    #   pending          → finding mới, chưa được review
-    #   accepted         → reviewer chấp nhận suggestion gốc → Resume sẽ apply
-    #   modified         → reviewer đã sửa suggestion trong Review Board → Resume dùng suggestion đã sửa
-    #   rejected         → reviewer bác bỏ, không apply
-    #   needs_discussion → hai suggestion xung đột, CHẶN --resume (bỏ qua + cảnh báo) tới khi con người quyết
-    #   deferred         → cố ý hoãn (không chặn), bỏ qua lượt này, xem lại sau
-    #   applied          → đã áp vào PRD; applied_via ghi cách áp: "resume" (qua --resume) — /review-context còn dùng "fix" (qua --fix)
-
-summary:
-  total_findings: {N}
-  by_severity: { critical: {N}, major: {N}, minor: {N} }
-  by_lens: { DEV: {N}, SA: {N}, PO: {N} }
-  recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
-  # Rule: critical ≥ 1                       → BLOCKED
-  #       critical = 0, major ≥ 1            → NEEDS_REVISION
-  #       critical = 0, major = 0            → APPROVED_WITH_MINOR_CHANGES
-```
-
-> **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.
-
-> **`resolution_edge_cases` — phân tích bậc-hai (chỉ critical/major).**
-> Với mỗi finding `critical`/`major`, sau khi viết `suggestion`, nghĩ tiếp: *nếu PO chốt phương án này thì
-> đẻ ra edge case / side-effect gì?* (path lỗi mới, va chạm BR/UC khác, trạng thái biên, hệ luỵ cross-section).
-> Ghi vào `resolution_edge_cases` để PO **thấy trước khi accept**. Đây là **advisory** — KHÔNG chặn, KHÔNG tự
-> tạo finding; PO đọc rồi quyết. Finding `minor` → để `[]`.
-> *(Phần phản hồi cho phương án PO **tự sửa** (`modified`) đến ở vòng sau: sau `--resume`, lần `/refine-prd`
-> kế chạy delta sẽ quét lại UC đã đổi + critic toàn-doc → tự lòi edge case mà phương án đó tạo ra.)*
-
-## Report
-
-{{include:steps/report-footer.md}}
-
-Dùng footer chuẩn với hai field bổ sung `Findings` và `Review` đặt ngay sau `Status`:
-
-```
----
-Status   : {badge}
-Findings : {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
-Review   : {paths.refinement_dir}/{prd-slug}-findings.yaml
-Output Artifacts:
-  created {paths.refinement_dir}/{prd-slug}-findings.yaml (findings từ 3-lens review)
-Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-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
-           → khi sạch critical, PO đặt | **Status** | approved | → /generate-bdd {prd-file}
-```
-
-Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau footer:
-
-```
-⚠️  {N} finding(s) cần quyết định của bạn trước khi --resume:
-   Mở {paths.refinement_dir}/{prd-slug}-findings.yaml
-   Với mỗi finding có status "needs_discussion":
-     1. Đọc cả hai phương án trong `suggestion`
-     2. Chọn một (hoặc viết phương án khác) vào `suggestion`
-     3. Đổi `status` → "accepted"
-   Sau đó chạy: /refine-prd {prd-file} --resume
-```
-*(Bỏ warning block này nếu không có `needs_discussion` finding nào.)*
-
----
-
-## Resume Mode — Áp dụng Findings & Bump Version
-
-*Được route tới từ Bước 0-C — Resume mode routing. `prd-slug` và `target_file` đã được phân giải ở Bước 1 trước khi nhảy vào đây.*
-
-### Phase 1 — Đọc các finding được chấp nhận
-
-1. Kiểm tra `{paths.refinement_dir}/{prd-slug}-findings.yaml` có tồn tại không.
-   Nếu không → báo lỗi rõ ràng và dừng:
-   ```
-   ❌ Không tìm thấy findings file tại {paths.refinement_dir}/{prd-slug}-findings.yaml
-      Hãy chạy /refine-prd {prd-file} trước để tạo findings, rồi mới --resume.
-   ```
-2. Đọc file findings.
-3. Gom tất cả finding có `status: "accepted"` hoặc `status: "modified"`.
-4. Nếu không có finding nào được chấp nhận → báo "No accepted findings. PRD unchanged." và dừng.
-5. Nếu còn finding nào có `status: "needs_discussion"` → cảnh báo (không dừng):
-   ```
-   ⚠️  {N} finding(s) chưa được giải quyết (needs_discussion) — sẽ bị bỏ qua lần apply này.
-      Giải quyết chúng trong Review Board rồi chạy lại --resume để apply.
-   ```
-
-### Phase 2 — Áp dụng thay đổi vào PRD
-
-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.
-- **Giữ ĐÚNG TẦNG + gọn khi áp fix (altitude):** AC = **outcome quan sát được + ref BR**, KHÔNG chứa cơ chế. Nếu fix là **chi tiết cơ chế/rule** (retry N, timeout, tên/chủ cờ, nhánh lỗi) → **ghi vào bảng BR/BL của UC** (hoặc tạo BR mới), AC chỉ **ref**; KHÔNG inline vào câu AC. Nếu fix làm rõ **≥2 điều kiện/nhánh** ở đúng tầng của nó → **tách bullet con** (mỗi ý một dòng `  - …`) hoặc **AC/BR mới**, đừng nối mệnh đề vào câu cũ. Một AC = một tiêu chí kiểm chứng; đừng để AC lặp lại nội dung BR.
-- **Chạy Business Language Guard trên text mới TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ"): diễn đạt lại / gỡ thuật ngữ kỹ thuật-UI để fix không tự kéo theo term kỹ thuật vào PRD.
-- 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 — Cập nhật file findings
-
-Với mỗi finding đã áp dụng (status là `accepted` hoặc `modified`):
-- Đặt `status: "applied"` + `applied_via: "resume"` trong `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
-
-Cập nhật `status: "applied"` ở **root level** của file findings (không phải `summary.status`).
-# Lifecycle file-level: pending_review → applied | partially_applied
-# partially_applied khi có finding bị rejected hoặc needs_discussion còn sót lại.
-
-### Phase 3 — Bump version & ghi entry changelog
-
-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 về draft, phải được duyệt lại
-5. Cập nhật `# Change Log` của PRD — **bảng phẳng 1 dòng/version, cửa sổ trượt 5 entry** (nếu gặp format cũ `### v{X}` block → chuẩn hoá sang bảng phẳng khi cập nhật):
-   - Thêm row mới lên **đầu** bảng:
-     ```
-     | {new_version} | {today} | {tóm tắt — KÈM UC/AC/BR bị ảnh hưởng, vd "UC2: sửa BR5; thêm AC7"} |
-     ```
-     *(Nêu rõ UC/AC/BR giúp `/generate-bdd` Version Check biết scenario nào cần cập nhật.)*
-   - Cập nhật dòng đầu section: `> Hiện tại: **v{new_version}** ({today}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET-ID}-{prd-slug}.changelog.md)`
-   - **Rollover (giữ PRD gọn — đây là chuẩn chung, /review-context cũng theo):** nếu bảng `# Change Log` có **> 5 row** → chuyển **mọi row vượt 5** (cũ nhất) sang **đầu** bảng của file kho `{paths.specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md` (giữ thứ tự mới→cũ); PRD chỉ giữ **5 row gần nhất**. Tạo thư mục `changelog/` + file kho nếu chưa có, theo skeleton:
-     ```
-     # Change Log (lịch sử) — {TICKET-ID}
-     > PRD: [../{TICKET-ID}-{prd-slug}.md](../{TICKET-ID}-{prd-slug}.md) — 5 version gần nhất nằm trong PRD; đây là phần cũ hơn.
-
-     | Version | Date | Changes |
-     |---------|------|---------|
-     ```
-6. Ghi `applied_to_version: "{new_version}"` ở **root level** của findings — đóng dấu "PRD đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt được thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
-
-### Phase 4 — Report
-
-```
-/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}
-
-💡 Vừa áp {N} phương án (gồm bản PO tự sửa) → chạy lại /refine-prd {prd-file}
-   (delta tự động) để lòi edge case mà các phương án vừa áp có thể tạo ra.
-⚠️  Status đã reset về draft (sửa rồi phải duyệt lại). BDD có thể đã lỗi thời. Chạy:
-    /review-context {prd-file}   ← kiểm tra chất lượng PRD trước
-    → PO đặt | **Status** | approved | khi hài lòng → /generate-bdd {prd-file}
-```

package/commands/report-bug.md

@@ -1,305 +0,0 @@
-# /report-bug — File một Bug có trace-spec (cho Tester & QC)
-
-Dành cho **tester và QC** — gồm cả **product-gap** lòi ra từ pipeline `/qc-*`
-(`/qc-run-test` FAIL phân loại product-gap, hoặc một spec-defect blocker `DOC_GAPS` từ
-`/qc-analyze`). Sinh một bug report có cấu trúc với đầy đủ spec context, phân loại layer
-khả nghi, và lưu lại để handoff cho team dev.
-
-**READ-ONLY trên spec và code.** Lệnh này không bao giờ sửa PRD, BDD, tech-docs, hay source.
-Fix là việc của dev (`/fix-bug`); viết scenario là `/propose-scenario`.
-
-Usage: `/report-bug {UC-ID hoặc TICKET} {mô tả ngắn}`
-Ví dụ: `/report-bug FT-001 tài khoản khoá sau 6 lần login fail, spec nói 5`
-
-## Gate
-# Gate — Quy trình vào chuẩn cho mọi lệnh
-
-Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
-
-## Bước 0 — Kiểm tra chế độ Sub-Agent
-
-Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
-
-1. Thử parse `$ARGUMENTS` dưới dạng JSON.
-2. Nếu parse thành công **và** chứa `"_agent_mode": true`:
-   - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.**
-   - Đặt target file = `payload.target_file`
-   - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
-   - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
-   - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
-   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
-   - Đi thẳng tới phần logic riêng của lệnh.
-3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
-
-## Bước 0-B — Ghi nhận Model *(KHÔNG chặn)*
-
-*Bỏ qua nếu `_agent_mode: true` (sub-agent — orchestrator đã ghi nhận rồi).*
-
-Ghi lại **model mà bạn — agent đang chạy lệnh này — thực sự đang dùng**, rồi mang nó vào
-dòng `Model:` của report cuối (xem `report-footer`). Nếu bạn biết mình **không** phải một
-model Opus, gắn thêm cảnh báo ngay ở dòng đó.
-
-**KHÔNG hỏi người dùng. KHÔNG chờ. KHÔNG dừng.**
-
-> **Vì sao bước này từng là prompt chặn, và vì sao bỏ (GAPS-v3 G41):** bản cũ hiện khối
-> `⚙️ MODEL CHECK` rồi chờ `Y/S/N`. Ba vấn đề cùng chỉ một hướng:
-> **(1)** nó hỏi người dùng thứ mà **agent đã biết chính xác**;
-> **(2)** câu trả lời **không kiểm chứng được** — gõ `Y` xong vẫn đang chạy Haiku thì không
-> gì phát hiện;
-> **(3)** **cả `Y` lẫn `S` đều đi tiếp** — cách duy nhất để nó dừng là tự nguyện gõ `N`.
-> Tức nó **không chặn được ai**, mà tốn một lần chặn ở **mọi** lệnh. Một feature đi hết
-> pipeline dùng 20 lệnh; 30/32 lệnh chạy gate. Hai mươi lần bấm cho một tín hiệu tự-khai
-> không kiểm chứng được — và chính cái giá đó làm mòn CHECKPOINT ở Bước 3, cổng có giá trị thật.
->
-> Khai báo trong report **mạnh hơn** hỏi: đúng nguồn (agent, không phải người), và nằm
-> **cạnh kết quả** để cân nhắc, thay vì nằm trước khi có kết quả để bấm cho xong.
-
-**Vẫn khuyến nghị Opus:** phân tích spec, review kiến trúc và sinh code đòi hỏi suy luận sâu;
-model nhỏ hơn dễ bỏ sót edge case và vi phạm kiến trúc. Đổi: `/model` → chọn Opus.
-
-## Bước 1 — Xác định Target File
-
-0. **Tách cờ trước khi resolve target.** `$ARGUMENTS` có thể lẫn các `--flag` (vd `--phase=integration`, `--comment`, `--fix`). **Loại bỏ mọi token bắt đầu bằng `--`** ra khỏi phần dùng để tìm target — chỉ giữ phần path/UC-ID/ticket. (Các flag đó do phần logic riêng của lệnh parse ở bước sau, KHÔNG phải tên file.)
-1. Nếu `$ARGUMENTS` (đã tách cờ) được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
-2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
-   - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
-   - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
-     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
-     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
-     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
-     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
-     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
-   - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
-
-   Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
-3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
-   - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
-   - Chờ người dùng chọn rồi mới tiếp tục.
-
-## Bước 2 — Chạy Context Loader
-
-Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`.
-Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh.
-
-## Bước 3 — CHECKPOINT
-
-*Bỏ qua nếu `_agent_mode: true`.*
-
-### 3a — Lệnh này có phải chặn không?
-
-| Mức | Lệnh nào | `--yes` bỏ qua được? |
-|---|---|:---:|
-| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
-| **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
-| **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
-
-`--yes` trong `$ARGUMENTS` → bỏ qua CHECKPOINT mức *chặn thường*. (Bước 1 đã tách mọi token
-`--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
-headless: `claude -p "/generate-code UC1 --yes"`.
-
-> **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
-> ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
-> **nghĩa là gì**.
-> Nguồn máy đọc: `bin/trace-schema.json` → `gate.checkpoint_levels`; `self-check` **R11** fail
-> build nếu nhãn trong file lệnh lệch với schema, hoặc nếu một lệnh `hard`/`none` thiếu nhãn.
-> *(Lệnh không có dòng nào = mức **chặn thường**, mặc định.)*
-
-> **Mức *không chặn* là thực thi đúng miễn trừ mà `rules/workflow.md` đã cấp từ trước** —
-> trước G41 file đó viết *"read-only commands may skip CHECKPOINT"* còn gate thì luôn đòi.
-> Hai file cùng được nạp vào mọi lệnh mà nói ngược nhau; agent theo cái nào là tuỳ lúc.
-
-### 3b — In gì
-
-**KHÔNG lặp lại những gì `[CTX LOADED]` vừa in.** Recap của context-loader (Bước 7) đã hiện
-Stack · Platform · Layers · CLAUDE.md · Dict · Entities · Lessons · Service · Status ngay phía
-trên. CHECKPOINT chỉ thêm **một** thông tin mới là `Target`.
-
-**Mọi thứ sạch** — recap báo `Status: FULL`, không cờ nào bật → in đúng hai dòng:
-
-```
-CHECKPOINT — Target: {resolved file path}
-Tiếp tục? (Y/N)
-```
-
-**Có bất thường** → thêm một dòng cho **mỗi** trạng thái, nặng nhất lên đầu:
-
-```
-CHECKPOINT
-🔴 Service  : unresolved — {lý do context-loader đã ghi}
-⚠️ CLAUDE.md: service overlay THIẾU — dùng root (code sinh ra có thể sai stack)
-⚠️ Target   : resolve bằng wildcard — {n} file khớp, chọn {file}
-⚠️ Module   : not configured — code sinh ra sẽ dùng default
-   Status   : PARTIAL — thiếu: {danh sách}
-   Target   : {resolved file path}
-Tiếp tục? (Y/N)
-```
-
-### 3c — Cờ nào bật, cờ nào KHÔNG
-
-Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader đã tính rồi** — không phát minh
-điều kiện mới, chỉ mang thứ đang bị giấu lên chỗ người dùng phải quyết định:
-
-| Bật cờ khi | Nguồn | Mức |
-|---|---|:---:|
-| `active_service = unresolved` | context-loader Bước 2b/2c/Fallback | 🔴 |
-| `Status = MINIMAL` | recap Bước 7 | 🔴 |
-| `Status = PARTIAL` | recap Bước 7 | ⚠️ |
-| CLAUDE.md thiếu, hoặc service overlay thiếu | context-loader Bước 3 | ⚠️ |
-| Target resolve qua wildcard, hoặc nhiều file khớp mà lệnh tự chọn | Bước 1 ở trên | ⚠️ |
-| `module` không cấu hình | recap Bước 7 | ⚠️ |
-
-**KHÔNG bật cờ cho:** `Lessons: chưa có` · `Dict: missing` · `Entities: missing`. Đó là
-*"dự án chưa điền"*, không phải *"có gì đó sai"* — chúng ở lại trong recap.
-
-> **Nguyên tắc một câu:** cờ dành cho thứ **framework không chắc chắn hoặc đã phải đoán**,
-> không dành cho thứ **người dùng chưa làm**. Đẩy hết mọi thứ lên thì CHECKPOINT lại đầy như
-> cũ, và ta quay về đúng chỗ xuất phát: một cổng luôn giống nhau thì bị lướt qua.
-
-### 3d — Chờ trả lời
-
-- "Y" → tiếp tục sang các bước riêng của lệnh.
-- "N" → dừng, hỏi người dùng muốn thay đổi gì.
-- Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
-  🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
-
-
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID / TICKET từ `$ARGUMENTS`. Phân giải file `.feature` khớp nếu có; nếu không, tiếp tục — bug vẫn file được.*
-
-## Context
-**BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
-rồi mới tiếp tục phần bên dưới.
-
-Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ
-`project-lessons`, và routing service (chế độ umbrella) đều **chưa được phân giải** — mọi
-placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
-
----
-
-## Step 1 — Phân giải Spec Context
-
-Định vị chuỗi spec cho UC/TICKET của bug. Ưu tiên `spec-manifest.yaml` (setup umbrella/tester) nếu có; else dùng `paths` đã phân giải.
-
-Thu thập và lưu:
-- `prd_path` + `Version` hiện tại của PRD
-- `bdd_path` (file `.feature` của UC này) + tiêu đề **scenario fail** cụ thể, nếu có cái khớp
-- `tech_doc_path` (nếu có)
-- `service` / domain
-
-Nếu không có scenario `.feature` nào khớp behavior báo cáo → set `coverage_gap = true` (behavior chưa được BDD test).
-
-## Step 2 — Thu thập chi tiết Bug
-
-Nếu chưa có trong `$ARGUMENTS`, hỏi tester (một prompt gọn):
-
-```
-File một bug — trả lời những gì bạn biết:
-  1. Xảy ra ở đâu? (endpoint / screen / flow)
-  2. Các bước tái hiện?
-  3. Expected (theo spec) vs Actual?
-  4. Error / log / status code?
-  5. Environment? (staging / prod / local)
-```
-
-## Step 3 — Xác định AC bị vi phạm
-
-Đọc PRD acceptance criteria cho UC này. Khớp bug với **AC** cụ thể nó vi phạm
-(vd `AC3: "5 lần login fail → khoá 30m"`). Trích nguyên văn. Nếu behavior không map AC nào →
-ghi "No AC covers this" và coi như một PRD gap khả dĩ.
-
-## Step 4 — Phân loại Layer khả nghi (BUG_FLOW)
-
-Áp dụng bảng quyết định BUG_FLOW để gợi ý root cause khả năng ở đâu — cái này route bug:
-
-| Nếu… | Layer khả nghi | Route tới |
-|------|-------------|----------|
-| Code mâu thuẫn một BDD scenario | **Code bug** (Case 1) | Dev → `/fix-bug` |
-| BDD scenario mâu thuẫn PRD AC | **BDD bug** (Case 2) | Dev/PO fix BDD |
-| PRD AC mơ hồ / im lặng | **PRD ambiguity** (Case 3) | PO làm rõ PRD |
-| Behavior đúng nhưng **không scenario nào phủ** | **BDD coverage gap** | Tester → `/propose-scenario` |
-| UI ≠ Design Spec | **Design Spec bug** (Case 5) | Dev/Designer |
-| Chỉ Env / data | **Environment** (Case 6) | DevOps |
-
-Nêu phân loại như một gợi ý (dev confirm trong `/fix-bug`).
-
-## Step 5 — Ghi Report
-
-Gán `BUG-{today YYYYMMDD}-{NN}` (NN = sequence kế tiếp trong các report có sẵn).
-Ghi vào `{paths.bug_reports_dir}/{BUG-ID}.md` (phân giải về `{spec_source}/feedback/bug-reports/` ở umbrella mode; tạo dir nếu cần) theo cấu trúc trong Output block, và cũng in nó ra để dán vào Jira/Slack.
-
-## Step 5.5 — Backfill trace (link pending-view)
-
-Nếu Step 1 khớp một scenario fail cụ thể `{UC-ID}-SC{N}`, xác định **sổ platform** cần cập nhật (trace tách theo platform: `{UC-ID}-{platform}.tsv`):
-- `{platform}` = platform mà bug xảy ra (từ ngữ cảnh test/feature fail — `web`/`app`/`system`). Nếu biết → dùng thẳng.
-- Nếu **không rõ platform**: glob `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-*.tsv` tìm sổ nào có `sc_id` = `{UC-ID}-SC{N}`. Khớp đúng **một** sổ → dùng nó. Khớp **nhiều** sổ (cùng số SC ở nhiều platform, là 2 scenario khác nhau) → **hỏi tester bug thuộc platform nào** rồi mới ghi.
-
-Nếu tìm được đúng row trong sổ `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv`, cập nhật **chỉ** row đó để view "waiting-on" của PO/PM trỏ
-tới bug này — giữ nguyên mọi cột khác (gồm `qc_status`):
-- `qc_blocked_by` = `{BUG-ID}`
-- `qc_owner` = `dev` nếu layer khả nghi ∈ {Code, BDD, Design Spec, Env} · `po` nếu layer khả nghi = PRD ambiguity
-
-Skip âm thầm nếu không SC nào khớp hoặc không có file/row trace (bug vẫn file được). Đây là
-lần ghi duy nhất lệnh này làm tới operational state — nó vẫn **không bao giờ** sửa PRD/BDD/code.
-
-## Step 6 — Handoff (để PO/Dev thực sự thấy)
-
-Report chỉ tới PO/Dev nếu được **commit và push lên spec repo dùng chung**. File local là dead drop.
-
-Xác định repo sở hữu `{paths.bug_reports_dir}`:
-- Umbrella mode → spec submodule tại `{spec_source}`
-- Single-service → repo hiện tại
-
-Rồi commit + push **repo đó**:
-
-```bash
-cd {spec_source}              # umbrella: spec submodule; single-service: bỏ
-git add feedback/bug-reports/{BUG-ID}.md
-git commit -m "qa(bug): {BUG-ID} — {short description}"
-git push                      # → PO/Dev thấy nó ở lần /sync tiếp theo
-```
-
-- Nếu tester không có quyền push spec repo → mở PR / MR thay vì, hoặc đưa file cho người sở hữu. In fallback này.
-- In chính xác các lệnh nếu bạn không tự chạy chúng.
-
-> PO/Dev được thông báo qua routine bình thường: `/sync` liệt kê các bug report vừa pull về.
-
----
-
-## Output
-
-**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
-Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
-
-```
-🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (trong spec repo dùng chung)
-
-Feature  : {UC-ID} — {feature name}   |  Service: {service}   |  Severity: {Critical|Major|Minor}
-State    : 🟢 Open   (lifecycle: Open → Fixed → Closed — set `Fixed` bởi /fix-bug, `Closed` sau khi /qc-run-test re-verify pass)
-
-Spec context
-  PRD      : {prd_path} (v{prd_version})
-  BDD      : {bdd_path} → Scenario: "{scenario title}"   {hoặc: ⚠️ no scenario covers this}
-  Tech Doc : {tech_doc_path}
-
-AC bị vi phạm
-  {AC-N}: "{AC text}"
-
-Expected (theo spec) : {expected}
-Actual               : {actual}
-Steps to reproduce   : {1..N}
-Environment          : {env}
-
-Layer khả nghi : {Code | BDD | PRD | Design Spec | Env}  →  {route}
-
-Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}
-
----
-Status : ✅ Complete (read-only trên specs/code — chỉ ghi file feedback)
-Output Artifacts: created {paths.bug_reports_dir}/{BUG-ID}.md (pushed to shared spec repo)
-Next   :
-  - PO/Dev sẽ thấy nó ở lần /sync tiếp theo
-  - Code bug      → dev chạy /fix-bug {BUG-ID}
-  - PRD ambiguity → PO (BUG_FLOW Case 3)
-  - Coverage gap  → /propose-scenario {UC-ID}
-```