spec-lite 1.0.1 → 1.1.0

package/skills/spec-tech/SKILL.md

@@ -28,14 +28,22 @@ Tạo `tech.md` cho một integration trong `specs/integrations/{slug}/`.
 
 ### Bước 1: Xác định integration
 
-Quét thư mục `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `tech.md`:
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
+- Quét `specs/integrations/*/spec.md`, tìm integration khớp với argument
+- Nếu không tìm thấy → báo lỗi:
+  > Không tìm thấy integration khớp với "{argument}". Kiểm tra lại tên hoặc số thứ tự.
+- Nếu tìm thấy → dùng integration đó, bắt đầu luôn
+
+**Nếu không có ARGUMENT:**
+
+Quét `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `tech.md`:
 
 ```
 Integrations:
 
-  [1] f001-authentication       — User Authentication
-  [2] f003-app-browsing         — App Browsing & Opt-in         ✓ có tech.md
-  [3] f004-credit-system        — Credit System
+  [1] 001-implement-auth    — Implement Auth             spec✓ tech✓
+  [2] 002-implement-todo    — Implement Todo Management  spec✓ tech—
 
 Chọn số integration:
 ```
@@ -43,8 +51,6 @@ Chọn số integration:
 Nếu không có integration nào → thông báo:
 > Chưa có integration nào. Hãy chạy `/spec-new` trước.
 
-**Nếu có ARGUMENT** → đây là số thứ tự trong danh sách trên (ví dụ `1`, `2`, hoặc `001`). Parse thành số nguyên, bỏ qua leading zeros, map vào integration tương ứng — không cần hiển thị danh sách, chọn luôn.
-
 Nếu integration đã có `tech.md` → hỏi trước khi tiếp tục:
 > `tech.md` đã tồn tại cho integration này. Tiếp tục sẽ ghi đè. Tiếp tục không?
 
@@ -54,18 +60,24 @@ Nếu integration đã có `tech.md` → hỏi trước khi tiếp tục:
 
 Load các file sau:
 
-- `specs/integrations/{slug}/spec.md` — đọc toàn bộ: Problem Statement, Requirements, Acceptance Criteria, Out of Scope
+- `specs/integrations/{slug}/spec.md` — đọc toàn bộ + frontmatter (`features`, `components`)
 - `specs/main/sad.md` — đọc Tech Stack và Architectural Guardrails
-- `specs/main/domain.md` — đọc Entities và Business Rules
+- `specs/main/domain.md` — đọc Glossary và Shared Entities
+- `specs/main/component/{C-XXX}-{slug}/cdd.md` — cho mỗi component trong frontmatter `components` (nếu cdd.md tồn tại)
+- `specs/main/feature/{F-XXX}-{slug}/fdd.md` — cho mỗi feature trong frontmatter `features` (nếu fdd.md tồn tại)
 
 Tóm tắt context và surface assumptions:
 
 ```
 TỪ SPEC & SAD TÔI HIỂU:
 - Integration: {title}
+- Features liên quan: {từ frontmatter — F-XXX, ...}
+- Components bị touched: {từ frontmatter — C-XXX, ...}
 - Yêu cầu chính: {tóm tắt requirements từ spec.md}
 - Tech stack: {từ sad.md}
-- Entities liên quan: {từ domain.md}
+- Shared entities liên quan: {từ domain.md}
+- Component design hiện tại: {tóm tắt từ cdd.md(s) — bỏ qua nếu chưa tồn tại}
+- Inter-component flow hiện tại: {tóm tắt từ fdd.md(s) — bỏ qua nếu chưa tồn tại}
 - Guardrails cần tuân theo: {list GUARD-XXX từ sad.md}
 
 ASSUMPTIONS TÔI ĐANG ĐẶT RA:
@@ -113,29 +125,56 @@ Tổng hợp và viết draft `tech.md`:
 
 **Cấu trúc file**: dùng `.claude/templates/integrations/tech-template.md` làm skeleton, điền nội dung từ interview vào.
 
-**Cascade Proposals** — điền theo hướng dẫn sau:
+**Cascade Proposals** — agent đề xuất delta cho main artifacts theo các targets sau (chỉ điền nếu thực sự có thay đổi, không thì ghi "Không có thay đổi đề xuất."):
 
 ### sad.md
 
-{Đề xuất cập nhật nếu phát hiện quyết định kiến trúc mới, tech stack thay đổi, hoặc guardrail mới cần thêm. Hoặc "Không có thay đổi đề xuất."}
+Đề xuất cập nhật nếu integration này:
+- Thêm cross-cutting concern mới (logging strategy, caching, ...)
+- Thay đổi tech stack
+- Thêm guardrail mới
 
 ### domain.md
 
-{Đề xuất cập nhật nếu phát hiện entity hoặc business rule mới trong quá trình thiết kế. Hoặc "Không có thay đổi đề xuất."}
+Đề xuất cập nhật nếu integration này:
+- Thay đổi shared entity (entity được dùng bởi 2+ component)
+- Thêm shared entity mới phát sinh từ thiết kế kỹ thuật
+
+### component/{C-XXX}-{component-name}/cdd.md
+
+Liệt kê **tất cả** components bị touched trong frontmatter và đánh giá từng cái:
+
+| Component | cdd.md | Đề xuất |
+| --- | --- | --- |
+| C-001 — auth | tồn tại | **Cập nhật** — thêm module RateLimiter, đổi storage strategy cho session |
+| C-003 — payment | chưa có | **Tạo mới** — full cdd skeleton |
+
+Với từng component có đề xuất:
+
+**Tạo mới** `specs/main/component/{C-XXX}-{component-slug}/cdd.md`
+- Dùng khi component này được giới thiệu lần đầu trong integration (cascade từ spec.md đã đề xuất tạo crd, giờ tech.md đề xuất tạo cdd)
+- Nội dung: Module Structure, Internal Data Flow, Storage & Persistence, Internal Interfaces, Technical Decisions
+
+**Cập nhật** `specs/main/component/{C-XXX}-{component-slug}/cdd.md`
+- Khi cdd.md đã tồn tại và integration thay đổi internal design
+
+### feature/{F-XXX}-{feature-name}/fdd.md
 
-### fdd.md
+Liệt kê **tất cả** features liên quan trong frontmatter và đánh giá:
 
-{Một trong hai:}
+| Feature | fdd.md | Đề xuất |
+| --- | --- | --- |
+| F-001 — Checkout | tồn tại | **Cập nhật** — thêm sequence khi payment fail |
+| F-002 — Refund | chưa có | **Tạo mới** |
 
-**Tạo mới** `specs/main/features/{feature-id}-{feature-slug}/fdd.md`
-- Dùng khi feature chưa có fdd.md
-- Thư mục theo convention: `{number}-{feature-slug}` (ví dụ: `001-authentication`)
-- Nội dung đề xuất: {tóm tắt Module Structure, Data Flow, Interfaces từ tech.md}
+**Tạo mới** `specs/main/feature/{F-XXX}-{feature-slug}/fdd.md`
+- Khi feature gắn với integration nhưng chưa có fdd.md
+- Nội dung: Inter-component data flow, Orchestration, Cross-component invariants — từ tech.md (chỉ phần inter-component, không lặp internal design của component)
 
-**Cập nhật** `specs/main/features/{feature-id}-{feature-slug}/fdd.md`
-- Dùng khi fdd.md đã tồn tại, ghi rõ thay đổi cụ thể cần thêm/sửa
+**Cập nhật** `specs/main/feature/{F-XXX}-{feature-slug}/fdd.md`
+- Khi fdd.md đã tồn tại, ghi rõ thay đổi flow nào
 
-{Hoặc "Không liên quan" nếu integration không gắn với feature cụ thể nào trong prd.md.}
+Bỏ block fdd.md nếu integration không gắn với feature nào (`features: []`).
 ```
 
 Hiển thị draft cho user xem — **chưa ghi file**.
@@ -161,10 +200,10 @@ Thông báo kết quả:
 ✓ specs/integrations/{slug}/tech.md đã được tạo (status: draft)
 
 Bước tiếp theo:
-  - Review và approve tech.md
-  - Implement theo tech.md
-  - Sau khi done: đổi status F-XXX trong prd.md thành DONE
-  - Nếu Cascade Proposals có thay đổi → chạy /spec-domain hoặc /spec-sad
+  - Review tech.md và apply Cascade Proposals (nếu có) vào main artifacts thủ công
+  - Approve tech.md (đổi status: draft → approved)
+  - /plan → tạo plan.md và todo.md cho integration này
+  - Sau khi tất cả tasks done: đổi status F-XXX trong prd.md thành DONE
 ```
 
 ---

package/templates/integrations/plan-template.md

@@ -3,6 +3,7 @@ id: "{id}"
 slug: "{slug}"
 title: "{title}"
 features: []
+components: []
 status: draft
 created: {YYYY-MM-DD}
 referenced_by:
@@ -14,25 +15,74 @@ referenced_by:
 
 <!-- Mô tả ngắn những gì sẽ được implement trong integration này -->
 
+## Dependency Graph
+
+```
+<!-- ASCII diagram — bottom = foundations, top = UI. Ví dụ:
+
+Database schema
+    │
+    ├── Domain models
+    │       │
+    │       └── Services
+    │               │
+    │               └── API endpoints
+    │                       │
+    │                       └── UI components
+-->
+```
+
 ## Tasks
 
 ### Phase 1: {tên phase}
 
-- [ ] T001 — {mô tả task}
-- [ ] T002 — {mô tả task}
-- [ ] T003 — {mô tả task} (depends: T001)
+#### T001 · {task title — bắt đầu bằng động từ}
 
-### Phase 2: {tên phase}
+**Mục tiêu:** {One sentence: what this task delivers}
 
-- [ ] T004 — {mô tả task} (depends: T001, T002)
-- [ ] T005 — {mô tả task}
+**depends:** —
 
-<!-- Convention:
-  - ID tăng dần trong phạm vi integration: T001, T002...
-  - Dependency ghi rõ: (depends: T001, T003)
-  - Tasks trong cùng phase không có dependency → có thể xử lý song song
-  - Tasks across phases có dependency tuần tự
--->
+**Các bước:**
+1. {Concrete implementation step}
+2. {Concrete implementation step}
+
+**Verification:**
+- [ ] {specific test case hoặc observable result}
+
+---
+
+#### T002 · {task title}
+
+**Mục tiêu:** {One sentence}
+
+**depends:** T001
+
+**Các bước:**
+1. {Concrete implementation step}
+
+**Verification:**
+- [ ] {specific test case hoặc observable result}
+
+---
+
+### Phase N: Verification
+
+#### T00N · Integration tests — {flow name}
+
+**Mục tiêu:** {End-to-end flow being tested}
+
+**depends:** T001, T002, ...
+
+**Các bước:**
+1. {Test setup / seed data}
+2. {Execute happy path}
+3. {Execute error cases}
+
+**Verification:**
+- [ ] Happy path: {description}
+- [ ] Error case: {description}
+
+---
 
 ## Definition of Done
 

package/templates/integrations/spec-template.md

@@ -3,6 +3,7 @@ id: "{id}"
 slug: "{slug}"
 title: "{title}"
 features: []
+components: []
 status: draft
 created: {YYYY-MM-DD}
 referenced_by:
@@ -12,33 +13,54 @@ referenced_by:
 
 ## Context
 
-<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (prd.md, domain.md, frd.md), để file self-contained -->
+<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (prd.md, domain.md, frd.md, crd.md), để file self-contained -->
 
 ## Problem Statement
 
 <!-- Vấn đề cần giải quyết là gì, tại sao cần giải quyết -->
 
-## Features
+## Acceptance Criteria
 
-<!-- Lặp lại block Feature bên dưới cho mỗi feature thuộc spec này -->
+<!--
+Agent tự chọn cách tổ chức phù hợp với bản chất integration. Có thể mix nếu integration vừa thêm feature, vừa thay đổi component.
 
-### Feature: {feature-name}
+AC ID format:
+- AC liên quan feature: `AC-{F_ID}-{seq}` — feature-scoped, cascade vào frd.md
+- AC liên quan component: `AC-{C_ID}-{seq}` — component-scoped, cascade vào responsibilities/interface/rules của crd.md
+
+Format Given/When/Then. Bỏ block không dùng.
+-->
+
+### Feature: {feature-name} *(bỏ nếu integration không touch feature; lặp lại block cho mỗi feature)*
 
 **Feature-level AC:**
 
-- [ ] AC-F-001: GIVEN {precondition}
-               WHEN {action}
-               THEN {expected outcome}
+- [ ] `AC-{F_ID}-{seq}`
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
+
+#### US-{F_ID}-{seq}: {Story title}
+
+**{Persona}** muốn **{hành động}** để **{mục tiêu}**.
+
+**Priority:** Must / Should / Could
 
-<!-- Lặp lại block Story bên dưới cho mỗi user story thuộc feature này -->
+**Story AC:**
 
-**Story: {story-title}**
+- [ ] `AC-{F_ID}-{seq}`
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
-> {mô tả user story — As a {role}, I want to {action} so that {benefit}}
+### Component: `{C-XXX}-{component-name}` *(bỏ nếu integration không touch component; lặp lại block cho mỗi component)*
 
-- [ ] AC-S-001: GIVEN {precondition}
-               WHEN {action}
-               THEN {expected outcome}
+**AC theo responsibility / interface / rule:**
+
+- [ ] `AC-{C_ID}-{seq}` — {responsibility / interface / rule mô tả}
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 ## Out of Scope
 
@@ -61,8 +83,14 @@ Không có thay đổi đề xuất.
 
 Không có thay đổi đề xuất.
 
+### component/{C-XXX}-{component-name}/crd.md
+
+<!-- Lặp lại section này cho mỗi component liên quan đến spec. Bỏ nếu integration không touch component nào. -->
+
+Không có thay đổi đề xuất.
+
 ### feature/{F-XXX}-{feature-name}/frd.md
 
-<!-- Lặp lại section này cho mỗi feature liên quan đến spec -->
+<!-- Lặp lại section này cho mỗi feature liên quan đến spec. Bỏ nếu integration không gắn với feature nào. -->
 
 Không có thay đổi đề xuất.

package/templates/integrations/tech-template.md

@@ -3,6 +3,7 @@ id: "{id}"
 slug: "{slug}"
 title: "{title}"
 features: []
+components: []
 status: draft
 created: {YYYY-MM-DD}
 referenced_by:
@@ -12,7 +13,7 @@ referenced_by:
 
 ## Context
 
-<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (sad.md, domain.md, fdd.md, spec.md) -->
+<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (sad.md, domain.md, cdd.md, fdd.md, spec.md) -->
 
 ## Solution Overview
 
@@ -54,6 +55,14 @@ Không có thay đổi đề xuất.
 
 Không có thay đổi đề xuất.
 
+### component/{C-XXX}-{component-name}/cdd.md
+
+<!-- Lặp lại section này cho mỗi component bị touched. Bỏ nếu integration không touch component nào. -->
+
+Không có thay đổi đề xuất.
+
 ### feature/{F-XXX}-{feature-name}/fdd.md
 
+<!-- Lặp lại section này cho mỗi feature liên quan. Bỏ nếu integration không gắn feature nào. -->
+
 Không có thay đổi đề xuất.

package/templates/integrations/todo-template.md

@@ -3,6 +3,7 @@ id: "{id}"
 slug: "{slug}"
 title: "{title}"
 features: []
+components: []
 created: {YYYY-MM-DD}
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.6 todo.md > Cấu trúc

package/templates/main/component/cdd-template.md

@@ -0,0 +1,63 @@
+---
+id: cdd-{component}
+type: cdd
+status: draft
+owner: "{Tech Lead / Senior Dev}"
+component_id: "{Component ID, ví dụ C-001}"
+referenced_by:
+  - conventions.md > 3. Main Artifacts > 3.2 Component level > cdd.md > Cấu trúc
+  - skills/spec-tech/SKILL.md > Process > Cascade Proposals > component cdd.md
+---
+
+# Component Design: {Component Name}
+
+> File này mô tả **internal design** của component — cách nó được tổ chức bên trong.
+>
+> Vai trò, public interface, business rules nằm trong `crd.md`. Cross-cutting concerns (auth, logging, ...) nằm trong `sad.md`.
+
+## Module Structure
+
+Các module/sub-component bên trong component và responsibility của từng module.
+
+| Module | Responsibility |
+| --- | --- |
+| {module} | {mô tả} |
+
+## Internal Data Flow
+
+Luồng dữ liệu nội bộ component — từ input đến output, qua những module nào.
+
+```mermaid
+sequenceDiagram
+    ...
+```
+
+## Storage & Persistence
+
+Cách component lưu trữ data. Bỏ section nếu component stateless.
+
+### Tables / Collections
+
+| Name | Mục đích | Key columns / Indexes |
+| --- | --- | --- |
+| {table_name} | {mục đích} | PK: {cols}, Index: {cols} |
+
+### Cache Strategy *(bỏ nếu dùng global strategy từ SAD)*
+
+{Mô tả cache strategy nội bộ component nếu khác SAD.}
+
+## Internal Interfaces
+
+Contract giữa các module bên trong component. Public interface (ra ngoài) đã được mô tả trong `crd.md`.
+
+| Caller | Callee | Purpose |
+| --- | --- | --- |
+| {module A} | {module B} | {gọi để làm gì} |
+
+## Technical Decisions
+
+Các quyết định kỹ thuật đặc thù của component và lý do.
+
+| Quyết định | Lý do | Alternatives đã cân nhắc |
+| --- | --- | --- |
+| {decision} | {lý do cụ thể} | {option A vs B} |

package/templates/main/component/crd-template.md

@@ -0,0 +1,88 @@
+---
+id: crd-{component}
+type: crd
+status: draft
+owner: "{BA / Tech Lead}"
+component_id: "{Component ID từ PRD Component Index, ví dụ C-001}"
+referenced_by:
+  - conventions.md > 3. Main Artifacts > 3.2 Component level > crd.md > Cấu trúc
+  - skills/spec-new/SKILL.md > Process > Cascade Proposals > component crd.md
+---
+
+# Component: {Component Name}
+
+## Role
+
+{1-2 câu mô tả vai trò của component trong hệ thống. Component này là "nơi chịu trách nhiệm" cho cái gì?}
+
+## Responsibilities
+
+Trách nhiệm cụ thể của component — phải làm gì, **không** làm gì.
+
+### Does
+
+- {responsibility 1}
+- {responsibility 2}
+
+### Does NOT
+
+- {responsibility thuộc component khác — ghi rõ component nào sở hữu}
+- {responsibility nằm ngoài scope}
+
+## Owned Entities
+
+Entities mà component này sở hữu canonical definition. Nếu entity được dùng bởi 2+ component, định nghĩa chính sẽ ở `domain.md` (Shared Entities) thay vì ở đây — chỉ ghi reference.
+
+### {Entity Name}
+
+{Mô tả entity này đại diện cho cái gì.}
+
+**Attributes:**
+
+| Attribute | Type | Required | Validation |
+| --- | --- | --- | --- |
+| {tên} | {business type} | Yes/No | {rule} |
+
+**State Machine:** *(bỏ nếu entity không có lifecycle)*
+
+| From | To | Trigger | Guard |
+| --- | --- | --- | --- |
+| {state} | {state} | {sự kiện} | {điều kiện} |
+
+## Public Interface
+
+Các interface mà component expose ra ngoài — signature level, không bao gồm implementation.
+
+### API Endpoints *(bỏ nếu component không expose HTTP API)*
+
+| Method | Path | Purpose | Auth |
+| --- | --- | --- | --- |
+| {GET/POST/...} | {/path} | {mục đích} | required/public |
+
+### Events Published *(bỏ nếu không emit event)*
+
+| Event | Trigger | Payload chính |
+| --- | --- | --- |
+| {EventName} | {khi nào emit} | {fields chính} |
+
+### Events Consumed *(bỏ nếu không consume event)*
+
+| Event | Source Component | Action |
+| --- | --- | --- |
+| {EventName} | {C-XXX} | {component này làm gì khi nhận event} |
+
+## Business Rules
+
+Các quy tắc nghiệp vụ thuộc về component này. Rule cross-component thuộc về `fdd.md` của feature liên quan.
+
+| ID | Rule | Condition | Exception |
+| --- | --- | --- | --- |
+| {C-XXX-R01} | {mô tả rule} | {khi nào apply} | {ngoại lệ nếu có} |
+
+## Dependencies
+
+Các component khác mà component này phụ thuộc.
+
+| Component | Loại dependency | Cách dùng |
+| --- | --- | --- |
+| `{C-XXX}-{name}` | sync call / event subscription / shared entity | {cụ thể: gọi API nào, subscribe event nào} |

package/templates/main/domain-template.md

@@ -5,22 +5,35 @@ status: draft
 owner: "{BA/Domain Expert}"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.1 Product level > domain.md > Cấu trúc
-  - skills/spec-domain/SKILL.md > Process > Bước 1: Kiểm tra preconditions
-  - skills/spec-domain/SKILL.md > Process > Bước 3: Write — sinh draft
+  - skills/spec-prd/SKILL.md > Process > Bước 5: Save (scaffold domain.md skeleton)
+  - skills/spec-new/SKILL.md > Process > Cascade Proposals > domain.md
+  - skills/spec-tech/SKILL.md > Process > Cascade Proposals > domain.md
 ---
 
 # Domain
 
-## Terminology
+> File này mỏng — chỉ chứa **shared vocabulary** và **shared entities** (entities được dùng bởi 2+ component).
+>
+> Business rules, domain events, internal entities thuộc về component sở hữu — xem `specs/main/component/{C-XXX}-{component-name}/crd.md`.
 
-| Term | Definition |
-| --- | --- |
-| {term} | {definition chính xác, không mơ hồ} |
+## Glossary
 
-## Entities
+Định nghĩa các thuật ngữ business — đây là **nơi duy nhất** chứa glossary trong toàn dự án.
+
+| Term | Definition | Example / Context |
+| --- | --- | --- |
+| {term} | {định nghĩa chính xác, không mơ hồ} | {context hoặc ví dụ minh họa nếu cần} |
+
+## Shared Entities
+
+Chỉ liệt kê entity được dùng bởi **2 hoặc nhiều component**. Entity nội bộ một component không vào đây — chúng nằm trong `crd.md` của component đó.
 
 ### {Entity Name}
 
+**Owner:** `{C-XXX}-{component-name}` *(component sở hữu canonical definition)*
+
+**Used by:** `{C-XXX}`, `{C-YYY}` *(các component reference entity này)*
+
 {Mô tả entity này đại diện cho cái gì trong business context.}
 
 **Attributes:**
@@ -39,22 +52,10 @@ Type là business type (text, number, money, date, email, phone) — không ph
 
 ## Entity Relationships
 
+Quan hệ giữa các shared entities. Quan hệ giữa entity nội bộ component thuộc về `cdd.md` của component đó.
+
 ```mermaid
 erDiagram
     EntityA ||--o{ EntityB : ""
     EntityB }o--|| EntityC : ""
 ```
-
-## Business Rules
-
-| ID | Rule | Condition | Exception |
-| --- | --- | --- | --- |
-| {DOMAIN-R01} | {mô tả rule} | {khi nào apply} | {ngoại lệ nếu có} |
-
-## Domain Events
-
-*(Bỏ nếu không có event-driven behavior)*
-
-| Event | Trigger | Payload |
-| --- | --- | --- |
-| {EventName} | {khi nào xảy ra} | {data đi kèm} |

package/templates/main/feature/fdd-template.md

@@ -5,51 +5,48 @@ status: draft
 owner: "{Tech Lead / Senior Dev}"
 feature_id: "{Feature ID}"
 referenced_by:
-  - conventions.md > 3. Main Artifacts > 3.2 Feature level > fdd.md > Cấu trúc
+  - conventions.md > 3. Main Artifacts > 3.3 Feature level > fdd.md > Cấu trúc
   - skills/spec-tech/SKILL.md > Process > Bước 4: Write — sinh draft > Cascade Proposals > fdd.md
 ---
 
 # Feature Design: {Feature Name}
 
-## Module Structure
+> File này mỏng — chỉ mô tả **cách các component tương tác với nhau** để thực hiện feature.
+>
+> Internal design của từng component nằm trong `cdd.md` của component đó. Cross-cutting concerns nằm trong `sad.md`.
 
-{Mô tả các module/layer trong feature này và responsibility của từng module.}
+## Inter-Component Data Flow
 
-| Module | Responsibility |
-| --- | --- |
-| {module} | {mô tả} |
-
-## Data Flow
-
-{Mô tả data flow nội bộ feature — từ input đến output, qua những bước nào.}
+Luồng dữ liệu đi qua các component — sequence diagram là form chính, có thể bổ sung mô tả prose.
 
 ```mermaid
 sequenceDiagram
-    ...
+    participant User
+    participant {C-XXX} as ComponentA
+    participant {C-YYY} as ComponentB
+
+    User->>ComponentA: {request}
+    ComponentA->>ComponentB: {call}
+    ComponentB-->>ComponentA: {response}
+    ComponentA-->>User: {result}
 ```
 
-## Interfaces
-
-### API Endpoints
+{Mô tả ngắn các bước nếu sequence diagram chưa đủ rõ.}
 
-| Method | Path | Purpose | Auth |
-| --- | --- | --- | --- |
-| {GET/POST/...} | {/path} | {mục đích} | required/public |
+## Orchestration
 
-### Events *(bỏ nếu không dùng)*
+Logic ở cấp feature — không thuộc component nào riêng lẻ. Bỏ section nếu feature đơn giản (1-2 component, không cần retry/fallback đặc biệt).
 
-| Event | Direction | Payload chính |
-| --- | --- | --- |
-| {EventName} | emit/consume | {fields} |
-
-## Caching & Queue Strategy
-
-*(Bỏ nếu dùng global strategy từ SAD)*
+| Concern | Handling |
+| --- | --- |
+| Retry policy | {ví dụ: retry 3 lần với exponential backoff khi gọi component X} |
+| Timeout | {ví dụ: timeout tổng feature 5s; per-component 2s} |
+| Fallback | {ví dụ: nếu component X fail, dùng cached data} |
+| Error propagation | {ví dụ: lỗi từ component Y được map thành 503 cho user} |
 
-{Mô tả strategy riêng của feature nếu khác SAD.}
+## Cross-Component Invariants
 
-## Technical Decisions
+Các invariant cần đảm bảo xuyên component — consistency, transactional boundary, ordering. Bỏ section nếu không có.
 
-| Quyết định | Lý do | Alternatives đã cân nhắc |
-| --- | --- | --- |
-| {decision} | {lý do cụ thể} | {option A vs B} |
+- {ví dụ: Order chỉ được đánh dấu `paid` sau khi Payment component confirm thành công}
+- {ví dụ: Inventory phải được reserve trước khi Order được tạo, rollback nếu Payment fail}