@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/commands/define-product.tmpl

@@ -1,225 +0,0 @@
-# /define-product — Khám phá tính năng (Q&A 8 Phase)
-
-## Gate
-{{include:steps/gate.md}}
-
-*Lưu ý: Với lệnh này, không có file input cần phân giải ở Bước 1. Bỏ qua sang Bước 2 (nạp context) rồi hỏi: **"Ticket ID và tên feature? (vd: LOYAL-29 Loyalty Points)"***
-
-## Context
-{{include:steps/context-loader.md}}
-
----
-
-## Ngôn ngữ nghiệp vụ *(áp khi viết BR / AC / Business Logic / Scope)*
-{{include:steps/business-language.md}}
-
----
-
-## Discovery Contract *(đọc trước — quyết định cách xử lý input của PO)*
-
-Lệnh này là **khai vấn (discovery)**, KHÔNG phải thu thập dữ liệu. Giá trị nằm ở **quá trình hỏi** — nó ép PO nói ra những gì chưa viết (edge case, out-of-scope, phụ thuộc, rule mâu thuẫn). Vì vậy:
-
-> **Input của PO là NGUYÊN LIỆU THÔ, KHÔNG phải câu trả lời thay thế phỏng vấn.**
-> Dù PO dán tài liệu dày cỡ nào — **vẫn đi hết Phase 1→7, mọi CHECKPOINT vẫn phải nổ.** TUYỆT ĐỐI KHÔNG coi input là "đã trả lời" rồi nhảy phase. Đây là điểm khác biệt cốt lõi so với các lệnh thu thập dữ kiện (generate-code/architecture "vét nguồn rồi mới hỏi") — ở discovery, **không có luật skip-if-answered.**
-
-**Cơ chế Confirm-vs-Ask** *(áp cho mọi câu hỏi ở Phase 1–6)*:
-- **Item input ĐÃ phủ** → KHÔNG skip. Trình bản nháp đã trích, đánh dấu `🤖 trích từ input` và hỏi PO **xác nhận / sửa / bổ sung**:
-  ```
-  🤖 Trích từ input: "{nội dung AI hiểu được}"
-  → Đúng chưa? Cần sửa/bổ sung gì không?
-  ```
-  Chỉ khi PO chốt mới nâng dấu thành `✅ PO xác nhận` và đi tiếp.
-- **Item input CHƯA phủ** → hỏi mới bình thường.
-- **Nghịch lý độ dày:** input càng dày → GAP tiềm ẩn càng nhiều (đó là thứ PO *chưa nghĩ tới*), nên phần soi hở ở **Phase 3 càng phải sâu**, KHÔNG được rút ngắn. Input dày tạo *ảo giác đủ* — đừng mắc bẫy.
-
-**Phân biệt dấu (bắt buộc, để chống blitz):** trong file output, mỗi dữ kiện mang một trong hai dấu — `✅ PO xác nhận` (PO đã chốt trực tiếp) hoặc `🤖 AI trích — chờ PO chốt`. Một phase CHỈ được đóng khi mọi item của nó mang dấu `✅`. Không tự nâng `🤖`→`✅` thay PO.
-
----
-
-## Phase 0 — Knowledge Sync *(AI tự điền — bối cảnh hệ thống, KHÔNG phải yêu cầu nghiệp vụ; không cần input PO)*
-
-AI quét dự án và ghi:
-
-- **Khái niệm / dữ liệu nghiệp vụ liên quan** — liệt kê khái niệm từ các PRD/domain-knowledge có sẵn liên quan tới feature này.
-- **Phần hệ thống / feature liên quan** — liệt kê phần hệ thống/feature bị ảnh hưởng.
-- **Rule / Logic có sẵn** — các rule từ PRD có sẵn mà feature này phải tôn trọng.
-- **Chuẩn hoá thuật ngữ** — map mọi thuật ngữ trong input PO về thuật ngữ chuẩn từ business-dictionary.md.
-  - **NEW TERM DETECTION:** nếu một thuật ngữ trong input PO lặp ≥2 lần và KHÔNG có canonical tương ứng trong business-dictionary.md → KHÔNG để trống/bịa. Ghi nó thành một câu hỏi trong **Phase 3 (Clarification Log)** để hỏi PO ngay khi còn trong buổi discovery:
-    + Thuật ngữ đó nghĩa gì trong ngữ cảnh hệ thống?
-    + English canonical term nên dùng là gì?
-    + Có bổ sung vào business-dictionary.md không?
-    Sau khi PO chốt → cập nhật business-dictionary.md (nếu đồng ý) + điền vào bảng map. *(Phase 0 chỉ phát hiện; việc hỏi dồn vào Phase 3 để không phá tính chất "không cần input PO" của Phase 0.)*
-
-```
-| Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
-|--------------------------|---------------------------------------|
-| {thuật ngữ gốc}          | {thuật ngữ chuẩn}                     |
-```
-
-Lưu bản đồ thuật ngữ này vào file product-definition output dưới section `### Chuẩn hoá thuật ngữ` (trong Phase 0) — `/generate-prd` sẽ tham chiếu nó trong bước **Quy tắc thuật ngữ** để đảm bảo nhất quán.
-
----
-
-## Phase 1 — Feature Definition *(CHECKPOINT 1)*
-
-Hỏi **lần lượt từng câu một**, đợi PO trả lời rồi mới hỏi câu kế. Giữ giọng nghiệp vụ, thân thiện; nếu PO lúng túng, đưa một ví dụ ngắn để gợi ý. Tránh hỏi về giải pháp kỹ thuật ở phase này.
-
-> **Áp Confirm-vs-Ask (Discovery Contract):** với câu mà input PO đã phủ, ĐỪNG bỏ qua — trình bản nháp `🤖 trích từ input` rồi hỏi PO xác nhận/sửa/bổ sung; câu chưa phủ thì hỏi mới. Mọi câu 1–8 đều phải có một cú chạm xác nhận của PO trước khi tóm tắt.
-
-1. **Context**: Bối cảnh / lý do vì sao cần feature này?
-2. **Problem**: Vấn đề cụ thể cần giải quyết?
-3. **Goal**: Khi feature chạy ổn, kết quả nghiệp vụ bạn muốn thấy là gì? Mô tả *thành quả*, chưa cần cách làm.
-4. **Actors**: Những ai sẽ dùng feature này? Liệt kê từng vai trò, và đánh dấu ai là người dùng chính (Primary), ai phụ (Secondary).
-5. **In Scope**: Feature này làm gì? (mỗi dòng một chức năng — chỉ những gì thuộc ticket này)
-6. **Out of Scope**: Cái gì KHÔNG làm trong ticket này? Ghi rõ kèm lý do hoặc để dành pha/ticket sau — để tránh phình phạm vi.
-7. **User Story**: Xác nhận theo format (mỗi ý một bullet):
-   - **Là một (As a)** {vai trò}
-   - **Tôi muốn (I want to)** {mục tiêu}
-   - **Để (So that)** {giá trị nghiệp vụ}
-8. **Phụ thuộc liên service**: Để chạy được, feature có cần **dữ liệu hay năng lực** gì từ feature/team khác không? Mô tả ở mức nghiệp vụ (cần gì, từ ai, vì sao) — chưa cần nói API hay kỹ thuật. Nếu không có → trả lời "Không có".
-
-Sau câu 8 → **tóm tắt lại toàn bộ** cho PO → chờ xác nhận → ghi `✅ PO xác nhận: Có` → sang Phase 2.
-
----
-
-## Phase 2 — User Flow Definition *(CHECKPOINT 2)*
-
-> **Áp Confirm-vs-Ask (Discovery Contract):** input phủ bước nào → trình bản nháp `🤖 trích từ input` để PO xác nhận/sửa; bước nào input im lặng (đặc biệt Edge Cases) → hỏi mới, KHÔNG tự bịa cho đủ bảng.
-
-Hỏi:
-1. **Entry Point**: Người dùng bắt đầu tương tác với feature này ở đâu?
-2. **Flow Steps**: Mô tả từng bước (dùng bảng):
-   ```
-   | Bước | Hành động | Trạng thái/Kết quả nghiệp vụ | Ghi chú |
-   ```
-3. **Màn hình & thành phần chính** *(mức nghiệp vụ — KHÔNG pixel/layout/màu)*: Feature gồm những **màn hình / bước giao diện** chính nào? Mỗi màn có **thành phần & hành động chính** gì (vd: ô nhập, nút, danh sách → bấm ra kết quả gì)? Đây là nguồn cho Wireframe của PRD và độ phủ BDD — nếu PO không chắc, AI gợi ý rồi PO xác nhận.
-   ```
-   | Màn hình | Thành phần chính | Hành động → kết quả nghiệp vụ |
-   ```
-4. **Exit Point**: Kết quả cuối khi flow hoàn thành là gì?
-5. **Edge Cases**: Các kịch bản thất bại nghiệp vụ ngoài happy path? (input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng → kết quả nghiệp vụ kỳ vọng)
-
-Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
-
----
-
-## Phase 3 — Clarification Log *(CHECKPOINT 3)*
-
-Dựa trên Phase 1-2, AI xác định gap và hỏi các câu follow-up. Tiếp tục các vòng cho tới khi không còn Mục chưa giải quyết.
-
-> **BẮT BUỘC chạy ≥1 vòng — KHÔNG được bỏ qua kể cả khi input rất dày.** Đây là nơi bắt GAP mà PO *chưa nghĩ tới*, nên độ dày input KHÔNG làm giảm nhu cầu hỏi — mà **làm tăng**. AI phải chủ động thách thức các **vùng input im lặng**, tối thiểu soi 4 nhóm:
-> 1. **Edge case / luồng lỗi** chưa được nêu (input thiếu, điều kiện không thoả, thao tác đồng thời).
-> 2. **Out-of-scope mơ hồ** — ranh giới ticket chưa rõ, dễ phình phạm vi.
-> 3. **Phụ thuộc liên service** input ngầm giả định nhưng chưa xác nhận (dữ liệu/năng lực từ team khác).
-> 4. **Rule mâu thuẫn / chồng chéo** giữa các phát biểu trong input.
->
-> Với mỗi item `🤖 AI trích — chờ PO chốt` còn sót từ Phase 1–2 → gom vào đây để PO chốt dứt điểm. **Không được nâng dấu `🤖`→`✅` thay PO.**
-
-```
-### Vòng {N}
-| # | Nhóm           | Câu hỏi    | PO trả lời |
-|---|----------------|------------|------------|
-| 1 | Context/Flow/Logic | {câu hỏi} | {trả lời} |
-```
-
-**BLOCK**: Nếu còn Mục chưa giải quyết → KHÔNG được sang Phase 4.
-
-### Mục chưa giải quyết
-- {mục — hoặc "None"}
-
-Khi mọi Mục chưa giải quyết đã xử lý → ghi `✅ CHECKPOINT 3: Không còn mục tồn đọng` → sang Phase 4.
-
----
-
-## Phase 4 — Business Rules *(CHECKPOINT 4)*
-
-Suy ra từ Phase 1-3. Mỗi BR = một quy tắc (hệ thống PHẢI / KHÔNG được làm gì — WHAT):
-
-```
-| Rule ID | Hành động/Trigger   | Quy tắc                       | Điều kiện           |
-|---------|---------------------|-------------------------------|---------------------|
-| BR-1    | {hành động từ flow} | System MUST/MUST NOT...       | {điều kiện áp dụng} |
-```
-
-Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
-
----
-
-## Phase 5 — Business Logic *(CHECKPOINT 5)*
-
-Map mỗi BR sang **logic nghiệp vụ** thực thi nó (rẽ nhánh / công thức / điều kiện — KHÔNG mô tả thay đổi dữ liệu hay hành vi UI; đó là kỹ thuật/design):
-
-```
-| Rule ID | Logic nghiệp vụ (rẽ nhánh / công thức / điều kiện) | Thông báo/kết quả nghiệp vụ khi lỗi |
-|---------|---------------------------------------------------|-------------------------------------|
-| BR-1    | {logic nghiệp vụ khi rule kích hoạt}              | {vd: báo "Số dư không đủ"}           |
-```
-
-Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
-
----
-
-## Phase 6 — Acceptance Criteria *(CHECKPOINT 6)*
-
-Suy ra từ BR + User Story. Mỗi AC phải testable (pass/fail rõ ràng):
-
-```
-| AC ID | Mô tả                   | Hành vi kỳ vọng            | Bắt nguồn từ |
-|-------|-------------------------|----------------------------|--------------|
-| AC-1  | {mô tả tiêu chí}        | {hành vi hệ thống cần làm} | BR-{N}       |
-```
-
-Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
-
----
-
-## Phase 7 — Validation Report
-
-Tự sinh ma trận độ phủ:
-
-```
-| Hành động Flow | Có Rule? | Có Logic? | Có AC? | Status |
-|----------------|----------|-----------|--------|--------|
-| {Hành động 1}  | ✅/❌    | ✅/❌     | ✅/❌  | OK/GAP |
-```
-
-- **Xung đột phát hiện**: liệt kê các rule xung đột, hoặc "None".
-- **Mục còn thiếu**: liệt kê gap, hoặc "None".
-
-Nếu phát hiện GAP → cảnh báo PO và giải quyết trước khi đánh dấu completed.
-
----
-
-## Output
-
-Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/product-definition.template.md`.
-
-> **Quy ước `slug`:** `slug` = kebab-case của tên feature (vd "Loyalty Points" → `loyalty-points`),
-> viết thường, chỉ a-z 0-9 và dấu `-`. Đây là định danh feature-package dùng xuyên suốt pipeline —
-> PRD, BDD, tech-docs, design-spec, trace của feature này đều kế thừa **nguyên văn** `slug` này
-> (`/generate-prd` đặt `prd-slug = slug`). Sinh một lần ở đây, các bước sau KHÔNG tái sinh.
->
-> **Ranh giới tên file:** tên file = `{TICKET-ID}-{slug}.md`. TICKET-ID **được phép chứa `-`**
-> (vd Jira key `LOYAL-29` → `LOYAL-29-loyalty-points.md`). Khi tách lại slug, các bước sau strip
-> **đúng chuỗi TICKET-ID** ở đầu, KHÔNG tách theo dấu `-` đầu tiên.
-
-Điền tất cả section bằng dữ liệu thu thập qua các phase.
-
-**Cập nhật Metadata theo tiến độ (cho phép resume):**
-- Sau mỗi CHECKPOINT phase được chốt (`✅ PO xác nhận: Có`, hoặc với Phase 3 là `✅ CHECKPOINT 3: Không còn mục tồn đọng`) → cập nhật `Completed Phase` = số phase vừa xong và giữ `Status: in-progress`.
-- **Chống blitz:** một phase CHỈ được tính là chốt khi mọi item của nó mang dấu `✅ PO xác nhận` — nếu còn bất kỳ item `🤖 AI trích — chờ PO chốt` nào, phase đó CHƯA xong, KHÔNG được tăng `Completed Phase`.
-- Khi Phase 7 pass mà không còn GAP → đặt `Completed Phase: 7` và `Status: completed`.
-- Nếu discovery bị ngắt giữa chừng, file vẫn được ghi với `Completed Phase` phản ánh phase cao nhất đã xác nhận — buổi sau resume tiếp từ phase kế tiếp.
-
-{{include:steps/report-footer.md}}
-
-Ví dụ footer cho lệnh này:
-
-```
----
-Status   : ✅ Complete
-Output Artifacts:
-  created {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md (product definition, Phase 1-7)
-Pipeline : [Discovery ◀ bạn ở đây] → PRD → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-Next     : /generate-prd {paths.product_definitions_dir}/{TICKET-ID}-{slug}.md
-```