@educa-corp/sdd-framework 0.1.0

package/commands/define-product.tmpl

@@ -0,0 +1,191 @@
+# /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}}
+
+---
+
+## 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.
+
+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)*
+
+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.
+
+```
+### 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`.
+- 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
+```