@edupia-tutor/spec-driven-docs 0.14.0 → 0.14.2

package/templates/product-definition.template.md

@@ -1,14 +1,14 @@
 # {TICKET-ID} Product Definition — {Feature Name}
 
 <!--
-  This template is used by the /define-product workflow.
-  AI Agent fills each section through phased Q&A with PO.
-  Output is structured input for /generate-prd.
-
-  RULES:
-  - Each section corresponds to 1 phase in the workflow
-  - Incomplete section → keep placeholder, MUST NOT proceed to next phase
-  - PO confirmation status is recorded in each section
+  Template này được dùng bởi workflow /define-product.
+  AI Agent điền từng section qua Q&A theo từng phase với PO.
+  Output là input có cấu trúc cho /generate-prd.
+
+  QUY TẮC:
+  - Mỗi section tương ứng với 1 phase trong workflow
+  - Section chưa đủ → giữ placeholder, KHÔNG được sang phase tiếp theo
+  - Trạng thái xác nhận của PO được ghi trong mỗi section
 -->
 
 ---
@@ -18,151 +18,164 @@
 | Field              | Value                          |
 |--------------------|--------------------------------|
 | **Ticket**         | {TICKET-ID}                    |
-| **Feature**        | {Feature name}                 |
+| **Feature**        | {tên tính năng}                |
 | **Domain**         | {domain}                       |
-| **PO**             | {PO name}                      |
+| **PO**             | {tên PO}                       |
 | **Created**        | {YYYY-MM-DD}                   |
 | **Status**         | in-progress / completed        |
-| **Completed Phase**| {last completed phase number}  |
+| **Completed Phase**| {số phase hoàn thành gần nhất} |
 
 ---
 
-## Phase 0: Knowledge Sync
+## Phase 0: Đồng bộ tri thức (Knowledge Sync)
 
-> AI syncs system knowledge. No PO input needed.
+> ⚙️ AI tự thu thập — đây là **bối cảnh hệ thống**, KHÔNG phải yêu cầu nghiệp vụ do PO viết. Mục đích: chuẩn hoá thuật ngữ và nhận biết phần đã có để tái sử dụng. Không cần input từ PO.
 
-### Related Entities
-- {Entity 1} — {brief description}
-- {Entity 2} — {brief description}
+### Khái niệm / dữ liệu nghiệp vụ liên quan
+- {Khái niệm 1} — {mô tả ngắn}
+- {Khái niệm 2} — {mô tả ngắn}
 
-### Related Modules
-- {Module 1}
-- {Module 2}
+### Phần hệ thống / feature liên quan
+- {Phần 1}
+- {Phần 2}
 
-### Existing Rules / Logic
-- {Rule/logic from existing PRDs or domain knowledge}
+### Rule / Logic có sẵn
+- {Rule/logic từ các PRD có sẵn hoặc domain knowledge}
 
-### Terminology Normalization
-| Term in PO input | Canonical term (business-dictionary) |
-|-------------------|--------------------------------------|
-| {original term}   | {canonical term}                     |
+### Chuẩn hoá thuật ngữ
+| Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
+|--------------------------|---------------------------------------|
+| {thuật ngữ gốc}          | {thuật ngữ chuẩn}                     |
 
 ---
 
-## Phase 1: Feature Definition
+## Phase 1: Định nghĩa tính năng (Feature Definition)
 
-> ✅ PO Confirmed: {Yes/No}
+> ✅ PO xác nhận: {Có/Không}
 
-### Context
-{Business context leading to this feature}
+### Bối cảnh (Context)
+{Bối cảnh nghiệp vụ dẫn đến tính năng này}
 
-### Problem Statement
-{Problem to solve}
+### Tuyên bố vấn đề (Problem Statement)
+{Vấn đề cần giải quyết}
 
-### Goal
-{Feature objective}
+### Mục tiêu (Goal)
+{Mục tiêu của tính năng}
 
-### Actors
-| Actor    | Role               | Primary/Secondary |
-|----------|--------------------|-------------------|
-| {Actor}  | {Role description} | Primary           |
+### Actor
+| Actor    | Vai trò            | Chính/Phụ |
+|----------|--------------------|-----------|
+| {Actor}  | {mô tả vai trò}    | Primary   |
 
-### Scope (In Scope)
-- {Function 1}
-- {Function 2}
+### Phạm vi (In Scope)
+- {Chức năng 1}
+- {Chức năng 2}
+
+### Ngoài phạm vi (Out of Scope)
+- {Hạng mục KHÔNG làm trong ticket này — kèm lý do / để dành pha sau}
 
 ### User Story
-- **As a** {User role}
-- **I want to** {User goal}
-- **So that** {Business value}
+- **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ụ}
+
+### Phụ thuộc liên service *(mức nghiệp vụ)*
+
+> Feature này cần **dữ liệu/năng lực** gì từ feature/team khác — KHÔNG mô tả API/event/callback (đó là kỹ thuật, thuộc Tech-docs).
+
+- {Cần {dữ liệu/năng lực} từ {feature/team} — vì {lý do nghiệp vụ}} — hoặc "Không có"
 
 ---
 
-## Phase 2: User Flow Definition
+## Phase 2: Định nghĩa User Flow
+
+> ✅ PO xác nhận: {Có/Không}
 
-> ✅ PO Confirmed: {Yes/No}
+### Điểm vào (Entry Point)
+{Người dùng bắt đầu tương tác với tính năng như thế nào}
 
-### Entry Point
-{How user starts interacting with the feature}
+### Các bước của Flow
+| Bước | Hành động       | Trạng thái/Kết quả nghiệp vụ | Ghi chú    |
+|------|-----------------|------------------------------|------------|
+| 1    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
+| 2    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
 
-### Flow Steps
-| Step | Action          | Screen/State     | Notes       |
-|------|-----------------|------------------|-------------|
-| 1    | {User action}   | {Screen/State}   | {Notes}     |
-| 2    | {User action}   | {Screen/State}   | {Notes}     |
+### Điểm ra (Exit Point)
+{Kết quả cuối khi flow hoàn thành}
 
-### Exit Point
-{Final outcome when flow completes}
+### Edge Cases / Luồng lỗi & ngoại lệ
+> 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ịch bản: khi {điều kiện bất thường} → {kết quả nghiệp vụ kỳ vọng}}
 
 ---
 
-## Phase 3: Clarification Log
+## Phase 3: Nhật ký làm rõ (Clarification Log)
 
-> Records all questions and answers across rounds.
+> Ghi lại mọi câu hỏi và câu trả lời qua các vòng.
 
-### Round {N}
-| # | Category | Question   | PO Answer  |
+### Vòng {N}
+| # | Nhóm     | Câu hỏi    | PO trả lời |
 |---|----------|------------|------------|
-| 1 | Context  | {question} | {answer}   |
-| 2 | Flow     | {question} | {answer}   |
-| 3 | Logic    | {question} | {answer}   |
+| 1 | Context  | {câu hỏi}  | {trả lời}  |
+| 2 | Flow     | {câu hỏi}  | {trả lời}  |
+| 3 | Logic    | {câu hỏi}  | {trả lời}  |
 
-### Unresolved Items
-- {Unresolved item — if any remain, MUST NOT proceed to Phase 4}
+### Mục chưa giải quyết
+- {Mục chưa giải quyết — nếu còn tồn đọng, KHÔNG được sang Phase 4}
 
 ---
 
 ## Phase 4: Business Rules
 
-> ✅ PO Confirmed: {Yes/No}
+> ✅ PO xác nhận: {Có/Không}
 
-| Rule ID | Action/Trigger      | Rule                | Condition            |
-|---------|---------------------|---------------------|----------------------|
-| BR-1    | {Action from flow}  | {Business rule}     | {Applicable condition} |
-| BR-2    | {Action from flow}  | {Business rule}     | {Applicable condition} |
+| Rule ID | Hành động/Trigger   | Quy tắc             | Điều kiện              |
+|---------|---------------------|---------------------|------------------------|
+| BR-1    | {hành động từ flow} | {business rule}     | {điều kiện áp dụng}    |
+| BR-2    | {hành động từ flow} | {business rule}     | {điều kiện áp dụng}    |
 
 ---
 
 ## Phase 5: Business Logic
 
-> ✅ PO Confirmed: {Yes/No}
+> ✅ PO xác nhận: {Có/Không}
 
-| Rule ID | System Behavior                          | Data State Change    | UI Behavior          | Error Handling        |
-|---------|------------------------------------------|----------------------|----------------------|-----------------------|
-| BR-1    | {How system processes when rule triggers} | {Data changes}       | {enable/disable/...} | {Error message/action}|
-| BR-2    | {How system processes when rule triggers} | {Data changes}       | {enable/disable/...} | {Error message/action}|
+| 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 đủ"}           |
+| BR-2    | {logic nghiệp vụ khi rule kích hoạt}              | {…}                                 |
 
 ---
 
 ## Phase 6: Acceptance Criteria
 
-> ✅ PO Confirmed: {Yes/No}
+> ✅ PO xác nhận: {Có/Không}
 
-| AC ID | Description            | Expected Behavior         | Derived from |
+| AC ID | Mô tả                  | Hành vi kỳ vọng           | Bắt nguồn từ |
 |-------|------------------------|---------------------------|--------------|
-| AC-1  | {Criterion description} | {Expected behavior}       | BR-{N}       |
-| AC-2  | {Criterion description} | {Expected behavior}       | BR-{N}       |
+| AC-1  | {mô tả tiêu chí}       | {hành vi kỳ vọng}         | BR-{N}       |
+| AC-2  | {mô tả tiêu chí}       | {hành vi kỳ vọng}         | BR-{N}       |
 
 ---
 
-## Phase 7: Validation Report
+## Phase 7: Báo cáo kiểm chứng (Validation Report)
 
-### Coverage Matrix
-| Flow Action | Has Rule? | Has Logic? | Has AC? | Status |
-|-------------|-----------|------------|---------|--------|
-| {Action 1}  | ✅/❌     | ✅/❌      | ✅/❌   | OK/GAP |
+### Ma trận độ phủ (Coverage Matrix)
+| Hành động Flow | Có Rule? | Có Logic? | Có AC? | Status |
+|----------------|----------|-----------|--------|--------|
+| {Hành động 1}  | ✅/❌    | ✅/❌     | ✅/❌  | OK/GAP |
 
-### Conflicts Detected
-- {Conflict description — or "None"}
+### Xung đột phát hiện
+- {Mô tả xung đột — hoặc "None"}
 
-### Missing Items
-- {Missing rule/AC/logic — or "None"}
+### Mục còn thiếu
+- {Rule/AC/logic còn thiếu — hoặc "None"}
 
 ---
 
 <!--
   NEXT STEPS:
-  When Product Definition is complete (Status: completed), run:
+  Khi Product Definition hoàn tất (Status: completed), chạy:
   /generate-prd {path-to-this-file} --jira {TICKET-ID}
-  to generate a PRD from this Product Definition.
+  để sinh PRD từ Product Definition này.
 -->

package/templates/project-context.yaml

@@ -25,7 +25,7 @@ project:
 # All paths are relative to workspace root.
 paths:
   # Feature-Package Layout:
-  #   specs/{domain}/{prd-slug}/prd.md           — PRD document
+  #   specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  — PRD document
   #   specs/{domain}/{prd-slug}/bdd/             — BDD .feature files
   #   specs/{domain}/{prd-slug}/tech-docs/       — Technical design docs
   #   specs/{domain}/{prd-slug}/design-spec/     — Design specs (FE/App only)
@@ -39,7 +39,7 @@ paths:
   bdd_writing_guide: "specs/templates/bdd-writing-guide.md"
   trace_report: "specs/.trace/trace-report.md"
 
-  # PRD template (PRDs are now at specs/{domain}/{prd-slug}/prd.md)
+  # PRD template (PRDs are at specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md)
   prd_template: "specs/templates/prd.template.md"
   refinement_dir: ".agent/review"