@edupia-tutor/spec-driven-docs 0.14.0

package/commands/generate-prd.tmpl

@@ -0,0 +1,254 @@
+# /generate-prd — Generate Product Requirements Document
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target file in Step 1 is a product-definition file in `{paths.product_definitions_dir}/`. Resolve it from `$ARGUMENTS` or list the directory and ask.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+*Additional context for this command: Read the full product-definition file. Extract: **TICKET-ID**, **domain**, **feature name**, Phases 1-7 data.*
+
+CHECKPOINT before generating: "Generate PRD for **{TICKET-ID} — {feature}** (domain: {domain}). Continue? (Y/N)"
+
+---
+
+## Terminology Rules *(apply if business-dictionary.md exists)*
+
+- **Replace banned terms**: substitute every banned term with its canonical equivalent (see dictionary § Banned Terms).
+- **Use canonical terms**: only use terms defined in dictionary.
+- **NEW TERM DETECTION**: If a term from PO input appears ≥2 times and is NOT in dictionary → **STOP** and ask PO:
+  - What does that term mean in the system context?
+  - What should the English canonical term be?
+  - Should it be added to business-dictionary.md?
+  After PO confirms → update `business-dictionary.md` (if agreed) → continue generation.
+- If no banned terms found and all terms are canonical → proceed without interruption.
+
+## Cross-Reference Rule
+
+Any mention of another TICKET-ID anywhere in the PRD (pre-condition, BR, note, appendix) → **MUST** be an inline link:
+```
+[TICKET-ID](./TICKET-ID-slug.md)
+```
+Never leave TICKET-ID as plain text if a corresponding PRD file exists in `{paths.specs_dir}/{domain}/{prd-slug}/`.
+
+## UC and BR Numbering Convention
+
+- **UC ID**: `{TICKET-ID}-UC{N}` — N starts at 1, increments per use case.
+- **BR ID**: `{TICKET-ID}-UC{N}-BR{M}` — **M increments across the whole PRD** (does NOT reset per UC).
+  - Example: UC1 → BR1, BR2; UC2 → BR3, BR4 (NOT BR1, BR2 again).
+
+---
+
+## Platform Strategy — PRD is platform-agnostic (Option C)
+
+PRD mô tả **WHAT** (yêu cầu nghiệp vụ) — không phụ thuộc vào platform nào implement.
+Viết AC theo business outcome, không theo UI/API details:
+
+| ✅ Viết trong PRD (platform-agnostic) | ❌ Không viết trong PRD |
+|---|---|
+| "Đăng nhập thành công → truy cập được tính năng" | "Click button → show toast" ← Design Spec |
+| "Sai password 5 lần → khoá tài khoản 30 phút" | "API trả về JWT token" ← Tech Docs |
+| "Session hết hạn → yêu cầu xác thực lại" | "Hiển thị spinner khi loading" ← Design Spec |
+
+**Một PRD phục vụ tất cả platform:**
+- **FE/App team** → đọc PRD + Design Spec → `/generate-bdd` (UI-level scenarios)
+- **BE team** → đọc PRD trực tiếp → `/generate-bdd` (API-level scenarios)
+- Design Spec là tài liệu riêng cho FE/App — **không trộn vào PRD**
+
+Khi viết AC, nếu PO đề cập chi tiết UI (màu sắc, layout, animation) → nhắc nhở:
+*"Chi tiết UI này thuộc về Design Spec, không thuộc PRD. Ghi nhận lại để tạo Design Spec sau."*
+
+---
+
+## Generate
+
+Write `{paths.specs_dir}/{domain}/{prd-slug}/prd.md` using the structure below.
+
+---
+
+```markdown
+# {TICKET-ID} {Feature Name}
+
+---
+
+## Metadata
+
+| Field         | Value                            |
+|---------------|----------------------------------|
+| **PRD ID**    | {TICKET-ID}                      |
+| **Version**   | 1.0                              |
+| **Status**    | draft                            |
+| **Author**    | {PO name or "AI-assisted"}       |
+| **Domain**    | {domain}                         |
+| **Created**   | {YYYY-MM-DD}                     |
+| **Updated**   | {YYYY-MM-DD}                     |
+| **API Source** | *(bỏ trống nếu greenfield — thêm `existing` nếu API đã tồn tại trên hệ thống)* |
+
+---
+
+# Feature
+
+{Describe the capability or function this feature provides — 2-3 concise sentences.}
+
+---
+
+# 1. Overview
+
+## a. User Story
+
+- **As a** {User role}
+- **I want to** {User goal}
+- **So that** {Business value}
+
+## b. Scope
+
+**In Scope**
+
+- {Function 1}
+- {Function 2}
+
+---
+
+# 2. Acceptance Criteria
+
+- **AC1:** {Acceptance criterion — testable, observable, no UI details}
+- **AC2:** {Acceptance criterion}
+
+---
+
+# 3. Use Case
+
+#### {TICKET-ID}-UC1: {Use Case Name}
+
+- **Actor:** {User performing the action}
+- **Description:** {Business scenario description — 1 sentence}
+- **Pre-condition:** {Condition that must be true BEFORE use case begins}
+- **Post-condition:** {State / result AFTER use case completes}
+
+**Business Rule**
+
+| ID | Business Rule |
+|----|---------------|
+| {TICKET-ID}-UC1-BR1 | {Rule — WHAT the system must do} |
+| {TICKET-ID}-UC1-BR2 | {Rule} |
+
+**Business Logic**
+
+**{TICKET-ID}-UC1-BR1:**
+- Logic 1
+- Logic 2
+- Logic 3
+
+**{TICKET-ID}-UC1-BR2:**
+- Logic
+
+---
+
+# 4. UI/UX Guidelines
+
+## a. User Flow
+
+{Brief description of sequence and decision branches}
+
+```mermaid
+flowchart TD
+    A[Step 1: ...] --> B[Step 2: ...]
+    B --> C{Condition?}
+    C -->|Yes| D[Result A]
+    C -->|No| E[Result B]
+```
+
+## b. Wireframe
+
+**Screen 1: {Screen Name}**
+
+**Screen:** {Screen name}
+
+**Components:**
+- {Component 1}
+- {Component 2}
+- {Component 3}
+
+**Actions:**
+- {Action 1} → {Result}
+- {Action 2} → {Result}
+
+---
+
+# Appendix
+
+## Original PO Input
+
+> {Paste verbatim content from product-definition file — Context + Problem + Goal}
+
+## References
+
+- {[TICKET-ID](./TICKET-ID-slug.md) — relationship description}
+
+## Existing API Contract *(chỉ điền khi API Source = existing)*
+
+> API đã tồn tại trên hệ thống. PO ghi lại contract để BDD generation dùng trực tiếp —
+> không cần tổng hợp từ FE/App BDD, không cần T7 sign-off gate.
+
+| Method | Path | Auth | Request | Response |
+|--------|------|------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/path} | {Bearer / none} | `{ field: type }` | `{ field: type }` |
+
+**Error responses:**
+
+| HTTP Status | Error Code | Khi nào xảy ra |
+|-------------|------------|----------------|
+| {4xx/5xx} | {ERR_CODE} | {condition} |
+
+---
+
+## AI Assumptions
+
+> Assumptions AI made when information was incomplete. Needs PO review and confirmation.
+
+- {Assumption 1 — [AI DRAFT]}
+```
+
+---
+
+## Quality Checklist *(verify before writing)*
+
+- [ ] Every AC is testable (clear pass/fail), no UI details (colors, fonts, button positions)
+- [ ] Each UC has Actor / Description / Pre-condition / Post-condition
+- [ ] Business Rule (WHAT) is separate from Business Logic (HOW)
+- [ ] BR ID increments across whole PRD — does not reset per UC
+- [ ] Every TICKET-ID cross-reference is an inline link `[TICKET-ID](./file.md)`
+- [ ] No banned terms (if dictionary exists)
+- [ ] User Flow includes error path / exception path
+- [ ] Wireframe covers all screens related to Use Cases
+- [ ] **Định dạng (readability)**: User Story / AC / các field của UC (Actor, Description, Pre/Post-condition) viết dạng bullet `- **Label:** …` — mỗi ý MỘT dòng, KHÔNG viết các dòng liền nhau (sẽ bị dồn thành 1 đoạn khi render); có một dòng trống trước và sau mỗi bảng
+
+## Changelog Section (append at end of PRD)
+
+Every PRD must end with this section. Start at v1.0:
+
+```markdown
+---
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | {YYYY-MM-DD} | Initial version |
+```
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/generate-prd Complete — {TICKET-ID}
+---
+Status : ✅ Complete
+Output Artifacts:
+  created {paths.specs_dir}/{domain}/{prd-slug}/prd.md  (PRD v1.0)
+Next   : /refine-prd {paths.specs_dir}/{domain}/{prd-slug}/prd.md
+         → then /review-context {prd-file}   ← verify PRD quality before generating BDD
+```