# /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
```