@longph2102/v-flow 1.5.0

package/skills/understand/ba-docs-scanner/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: ba-docs-scanner
+description: "Hướng dẫn Import BA Docs Agent đọc sâu tài liệu BA để generate Module Card drafts có giá trị. Agent PHẢI đọc skill này trước khi generate bất kỳ draft nào."
+trigger: "Khi /v.import-ba-docs cần generate AI drafts (Bước 5)"
+phase: "U.0d"
+used_by:
+  - /v.import-ba-docs
+---
+
+# BA Docs Scanner — Chiến Lược Đọc Sâu Tài Liệu BA
+
+> ⚠️ Đây là **Skill bắt buộc** cho Import BA Docs Agent khi generate module card drafts.
+> Đọc trước khi generate bất kỳ draft nào. Không có chiến lược đọc → output chỉ paraphrase, vô giá trị.
+>
+> → Xem `gotchas.md` cho Anti-patterns (output vô giá trị) và Quality Gate.
+
+---
+
+## Nguyên tắc chung: Deep Document Reading
+
+Đọc tài liệu BA **KHÁC HOÀN TOÀN** đọc code:
+
+| Đọc Code (U.0b) | Đọc BA Docs (U.0d) |
+|---|---|
+| Grep `if`, `throw`, `validate` | Tìm câu "phải", "bắt buộc", "không được" |
+| Enum definitions → states | Flowchart, bảng trạng thái trong doc |
+| Controller → Service → DB | Actor → Action → Result |
+| Code là truth | Doc có thể outdated — luôn gắn `[❓ CẦN BA VERIFY]` |
+
+**5 nguyên tắc đọc BA docs:**
+
+1. **Đọc TOÀN BỘ fulltext** — Không chỉ overview. Business rules thường nằm giữa hoặc cuối tài liệu.
+2. **Tìm patterns ngôn ngữ** — Dùng bảng keywords bên dưới để nhận diện thông tin có giá trị.
+3. **Cross-reference giữa sources** — Nhiều sources nói cùng 1 topic → merge + phát hiện mâu thuẫn.
+4. **Trích dẫn nguyên văn** — Quote đoạn gốc, kèm tên source file. KHÔNG paraphrase.
+5. **Chuyển text → structured data** — Đoạn văn mô tả → bảng, diagram, danh sách có cấu trúc.
+
+---
+
+## Thứ tự đọc Raw Materials
+
+Đọc theo thứ tự ưu tiên để xây dựng understanding dần dần:
+
+```
+1. overview.md (briefing doc)     → Bức tranh tổng thể, hiểu module làm gì
+2. domain-map.json (mind map)     → Hierarchy concepts, relationships giữa entities
+3. study-guide.md (nếu có)        → Key concepts, Q&A giúp validate understanding
+4. sources/*.txt (fulltext)        → Chi tiết: business rules, constraints, exceptions
+```
+
+**Cross-reference checklist:**
+- [ ] Entities trong mind-map có match với entities mô tả trong fulltext?
+- [ ] Q&A trong study-guide có bổ sung info nào mà fulltext không nói rõ?
+- [ ] Có mâu thuẫn giữa các sources? → Gắn `[⚠️ CONFLICTING SOURCES: source_A vs source_B]`
+
+---
+
+## Bảng Keywords — Nhận Diện Thông Tin Có Giá Trị
+
+> Dùng bảng này để scan fulltext. Khi gặp keywords → ĐỌC KỸ đoạn xung quanh → trích xuất structured data.
+
+| Mục tiêu trích xuất | Keywords tiếng Việt | Keywords tiếng Anh | Extract thành |
+|---|---|---|---|
+| **Business Rules** | "phải", "bắt buộc", "không được", "chỉ khi", "nếu...thì", "quy định", "điều kiện", "ràng buộc" | "must", "required", "shall", "only if", "condition", "constraint" | → BR-xx trong use-cases.md |
+| **States / Transitions** | "trạng thái", "chuyển sang", "sau khi", "trước khi", "quy trình", "bước", "luồng", "flow" | "status", "state", "transition", "workflow", "step", "after", "before" | → state-diagram.md |
+| **Actors / Roles** | "người dùng", "quản lý", "admin", "nhân viên", "phê duyệt", "tạo bởi", "vai trò" | "user", "manager", "admin", "role", "approver", "creator" | → permissions.md |
+| **Permissions** | "quyền", "được phép", "không được", "chỉ", "cấm", "hạn chế", "phân quyền" | "permission", "access", "deny", "restrict", "authorize" | → permissions.md |
+| **Data / Entities** | "thông tin", "dữ liệu", "trường", "bảng", "danh sách", "mã", "ID", "thuộc tính" | "field", "table", "entity", "attribute", "data", "record" | → db.md |
+| **SLAs / Constraints** | "trong vòng", "tối đa", "tối thiểu", "deadline", "thời hạn", "KPI", "SLA" | "within", "maximum", "minimum", "deadline", "SLA", "KPI" | → SKILL.md (Constraints) |
+| **Exceptions** | "ngoại lệ", "trường hợp đặc biệt", "trừ khi", "tuy nhiên", "nhưng", "ngoại trừ" | "exception", "special case", "unless", "however", "except" | → BR-xx (Exceptions) |
+| **Integrations** | "kết nối", "tích hợp", "đồng bộ", "gửi", "nhận", "API", "hệ thống khác" | "integrate", "sync", "send", "receive", "API", "external" | → cross-service.md |
+| **UI / Screens** | "màn hình", "form", "nút", "giao diện", "hiển thị", "nhập", "chọn" | "screen", "form", "button", "UI", "display", "input", "select" | → ui-flows.md |
+| **Glossary** | "viết tắt", "thuật ngữ", "định nghĩa", "gọi là", "tức là", "ký hiệu" | "abbreviation", "term", "definition", "aka", "means" | → SKILL.md (Glossary) |
+
+---
+
+## Scan Strategy cho từng file Module Card
+
+### SKILL.md — Entry Point + Domain Glossary
+
+**Cách đọc BA docs:**
+1. Đọc `overview.md` → rút **mục đích module** (module tồn tại để giải quyết vấn đề gì cho business).
+2. Scan tất cả sources → tìm **thuật ngữ đặc thù** (viết tắt, từ chuyên ngành, định nghĩa riêng).
+3. Tìm **business constraints** — SLA, KPI, deadline, limits (số lượng tối đa, thời gian tối đa).
+4. Tìm **stakeholders** — ai liên quan, vai trò gì, quyết định gì.
+5. Đọc `domain-map.json` → entities chính và mối quan hệ.
+
+**Output phải có:**
+- **description**: KHÔNG phải "Module quản lý X". Phải mô tả GIÁ TRỊ NGHIỆP VỤ — VD: "Module xử lý vòng đời Phiếu công tác (Work Order) từ tạo mới → phê duyệt → thực hiện → hoàn thành, phục vụ quy trình bảo trì thiết bị tại các chi nhánh".
+- **Quick Summary**: 3-4 câu tóm tắt từ góc BA — actors chính, luồng chính, hệ thống liên quan.
+- **Key Business Rules**: Trích xuất TỪ TÀI LIỆU CỤ THỂ. Mỗi rule phải kèm **trích dẫn gốc** + tên source file.
+  ```
+  VD: BR-01: WO phải được Manager duyệt trước khi thực hiện
+    - Trích dẫn: "Mọi phiếu công tác phải có sự phê duyệt của Trưởng bộ phận trước khi giao cho kỹ thuật viên"
+    - Source: WO-spec.pdf, trang 12
+    - [⚠️ AI-inferred from NotebookLM]
+  ```
+- **Key Entities**: Rút từ mind-map + fulltext, kèm description nghiệp vụ (không phải technical).
+- **Domain Glossary**: Bảng thuật ngữ — Thuật ngữ, Định nghĩa, Viết tắt, Ghi chú.
+- **Business Constraints & SLAs**: Bảng ràng buộc — Constraint, Mô tả, Giá trị, Source.
+- **No-Go Zones**: `[❓ CẦN CODE SCAN — U.0d chỉ có tài liệu BA]`
+
+---
+
+### use-cases.md — Logic & Flow
+
+**Cách đọc BA docs:**
+1. Tìm **mô tả quy trình / workflow** — tài liệu BA thường mô tả luồng nghiệp vụ dạng text hoặc flowchart.
+2. Với mỗi luồng: xác định **Trigger** (ai/cái gì kích hoạt), **Steps** (các bước tuần tự), **Result** (kết quả).
+3. Tìm **business rules** bằng keywords: "phải", "bắt buộc", "không được", "chỉ khi" → trích xuất nguyên văn.
+4. Tìm **exceptions / edge cases**: "trừ khi", "ngoại lệ", "trường hợp đặc biệt".
+5. Tìm **mô tả trạng thái / state**: "trạng thái", "chuyển sang", "bước tiếp theo".
+
+**Output phải có:**
+- **E2E Flows**: Mô tả LUỒNG NGHIỆP VỤ (không phải code flow vì chưa có code). Format:
+  ```
+  ### Flow 1: Tạo Work Order mới
+  
+  **Trigger**: Kỹ thuật viên phát hiện thiết bị cần bảo trì
+  **Actor chính**: Kỹ thuật viên (USER role)
+  
+  **Các bước nghiệp vụ:**
+  1. Kỹ thuật viên mở hệ thống, chọn "Tạo phiếu công tác mới"
+  2. Điền thông tin: tiêu đề, mô tả lỗi, thiết bị, mức ưu tiên
+     - Trường bắt buộc: tiêu đề, thiết bị, mức ưu tiên (Source: WO-spec.pdf)
+  3. Hệ thống tạo phiếu với trạng thái DRAFT, sinh mã tự động WO-YYYYMMDD-SEQ
+  4. Kỹ thuật viên "Gửi duyệt" → hệ thống chuyển trạng thái sang PENDING_APPROVAL
+  5. Gửi thông báo cho Manager cùng chi nhánh
+  
+  **Kết quả**: Phiếu công tác được tạo, Manager nhận thông báo duyệt
+  **SLA**: [❓ CẦN BA BỔ SUNG — có thời hạn duyệt không?]
+  [⚠️ AI-inferred from NotebookLM — Source: WO-flow.docx]
+  ```
+
+- **Business Rules**: TRÍCH DẪN NGUYÊN VĂN từ tài liệu, kèm phân tích:
+  ```
+  ### BR-01: Chỉ cho phép sửa WO ở trạng thái DRAFT
+  
+  - **Trích dẫn gốc**: "Phiếu công tác chỉ được chỉnh sửa khi ở trạng thái Bản nháp. 
+    Sau khi gửi duyệt, mọi thay đổi phải thông qua quy trình từ chối và tạo lại."
+  - **Source**: WO-spec.pdf, mục 3.2 "Quy định chỉnh sửa"
+  - **Điều kiện**: status === DRAFT
+  - **Hành động**: Cho phép sửa tất cả fields
+  - **Ngoại lệ**: Admin có thể sửa ở mọi trạng thái? [❓ CẦN BA VERIFY — tài liệu không đề cập]
+  - [⚠️ AI-inferred from NotebookLM]
+  ```
+
+- **State Machine**: Vẽ mermaid stateDiagram-v2 NẾU tài liệu BA mô tả trạng thái. Ghi rõ trạng thái nào lấy từ doc, trạng thái nào suy luận.
+
+---
+
+### state-diagram.md — State Machine (NẾU BA docs mô tả)
+
+**Cách đọc BA docs:**
+1. Tìm **danh sách trạng thái** — bảng, bullet list, hoặc mô tả trong text.
+2. Tìm **quy tắc chuyển đổi** — "sau khi duyệt, chuyển sang...", "nếu từ chối, quay lại..."
+3. Tìm **ai được phép** trigger transition — "Manager duyệt", "Admin hủy".
+4. Tìm **side-effects** — "sau khi duyệt, gửi email", "khi hoàn thành, đồng bộ SAP".
+5. Tìm **trạng thái cuối** (terminal states) — "đã hoàn thành", "đã hủy".
+
+**Output phải có:**
+- Mermaid stateDiagram-v2 với states từ tài liệu (KHÔNG BỊA).
+- Bảng States: Mã, Tên hiển thị, Ý nghĩa — lấy nguyên văn từ BA docs.
+- Bảng Transitions: Từ → Sang, Event, Guards, Actor — kèm source reference.
+- Side-Effects: Liệt kê từ tài liệu (email, notification, sync...).
+- `[⚠️ AI-inferred from NotebookLM — CẦN CODE SCAN VERIFY enum values]`
+
+**Khi nào KHÔNG tạo**: Nếu tài liệu BA không đề cập trạng thái → bỏ qua, KHÔNG bịa.
+
+---
+
+### permissions.md — Roles & Permissions (NẾU BA docs mô tả)
+
+**Cách đọc BA docs:**
+1. Tìm **danh sách vai trò** — "người dùng", "quản lý", "admin", bảng phân quyền.
+2. Tìm **ma trận quyền** — "được phép xem/tạo/sửa/xóa", "chỉ truy cập data..."
+3. Tìm **phạm vi dữ liệu** — "chỉ xem data chi nhánh mình", "chỉ data do mình tạo".
+4. Tìm **quy tắc phê duyệt** — "cần Manager duyệt", "Admin có toàn quyền".
+
+**Output phải có:**
+- Bảng Roles: Mã, Tên, Phạm vi, Mô tả — từ tài liệu BA.
+- Ma trận Role × Chức năng: ✅/❌ kèm điều kiện bổ sung.
+- Data Scope: Mô tả cách phân quyền data (VPS, owner, global).
+- `[⚠️ AI-inferred from NotebookLM — CẦN CODE SCAN VERIFY guards/decorators]`
+
+**Khi nào KHÔNG tạo**: Nếu tài liệu BA không đề cập vai trò/quyền → bỏ qua.
+
+---
+
+### db.md — Database / Data Model (NẾU BA docs mô tả)
+
+**Cách đọc BA docs:**
+1. Tìm **ERD, data dictionary, bảng dữ liệu** — BA docs thường có mô tả entity/fields.
+2. Tìm **mô tả entities** — "thông tin phiếu công tác gồm: mã, tiêu đề, mô tả, trạng thái..."
+3. Tìm **relationships** — "mỗi phiếu có nhiều items", "phiếu thuộc 1 chi nhánh".
+4. Tìm **constraints** — "mã phiếu không trùng", "tiêu đề bắt buộc".
+
+**Output phải có:**
+- Bảng Entities: Tên, Mô tả nghiệp vụ — từ góc BA không phải kỹ thuật.
+- Fields chính: Tên field (nghiệp vụ), Mô tả, Bắt buộc?, Ghi chú.
+- Relationships: Entity A → Quan hệ → Entity B — bằng ngôn ngữ nghiệp vụ.
+- ER Diagram (mermaid) nếu đủ thông tin.
+- `[⚠️ AI-inferred from NotebookLM — CẦN CODE SCAN VERIFY schema thực tế]`
+
+**Khi nào KHÔNG tạo**: Nếu tài liệu BA không mô tả data model → bỏ qua.
+
+---
+
+### ui-flows.md — UI / Screens (NẾU BA docs mô tả)
+
+**Cách đọc BA docs:**
+1. Tìm **wireframes, mockups** — hình ảnh, mô tả giao diện.
+2. Tìm **mô tả màn hình** — "màn hình danh sách", "form tạo mới", "trang chi tiết".
+3. Tìm **user flow** — "user mở app → chọn menu → thấy danh sách → tap vào 1 item".
+4. Tìm **form fields** — "trường tiêu đề", "dropdown chọn loại", "nút submit".
+
+**Output phải có:**
+- Danh sách màn hình: Tên, Mô tả chức năng — từ tài liệu BA.
+- User Flow: Step-by-step thao tác người dùng.
+- Form Fields: Tên field, Loại input, Bắt buộc?, Validation rules — từ BA docs.
+- `[⚠️ AI-inferred from NotebookLM — CẦN CODE SCAN VERIFY component thực tế]`
+
+**Khi nào KHÔNG tạo**: Nếu tài liệu BA không mô tả giao diện → bỏ qua.
+
+---
+
+### cross-service.md — Integrations
+
+**Cách đọc BA docs:**
+1. Tìm **hệ thống liên quan** — "đồng bộ với SAP", "gửi email", "kết nối hệ thống nhân sự".
+2. Tìm **data exchange** — "gửi thông tin WO sang ERP", "nhận danh sách nhân viên từ HR".
+3. Tìm **triggers** — "khi duyệt xong, tự động sync".
+4. Tìm **fallback / error handling** — "nếu đồng bộ thất bại..."
+
+**Output phải có:**
+- Bảng integrations: System, Direction (gửi/nhận), Mục đích, Trigger.
+- Payload mô tả (nếu BA docs có chi tiết): fields gửi đi / nhận về.
+- Error handling / SLA (nếu có).
+- `[⚠️ AI-inferred from NotebookLM]`

package/skills/understand/ba-docs-scanner/config.json

@@ -0,0 +1,47 @@
+{
+  "name": "ba-docs-scanner",
+  "version": "1.0",
+  "description": "Import và trích xuất tài liệu BA từ NotebookLM hoặc raw sources",
+  "agent": "understand",
+  "phase": ["U.0d"],
+  "triggers": ["import_ba_docs", "import_ba_docs_refresh"],
+  "dependencies": ["understand/codebase-scanner"],
+  "config": {
+    "source_types": ["notebooklm", "pdf", "markdown", "html"],
+    "output_dir": ".v-flow/modules/{domain}/raw/",
+    "merge_strategy": "append_with_dedup",
+    "extraction_fields": ["business_rules", "domain_concepts", "user_stories", "acceptance_criteria", "glossary_terms"]
+  },
+  "setup_questions": [
+    {
+      "id": "source_type",
+      "question": "Nguồn tài liệu BA?",
+      "options": ["notebooklm", "pdf", "markdown", "html", "mixed"],
+      "default": "mixed",
+      "description": "mixed = auto-detect. notebooklm = dùng notebooklm-py (unofficial, có thể fail)."
+    },
+    {
+      "id": "auto_glossary",
+      "question": "Tự động extract domain glossary từ tài liệu?",
+      "type": "boolean",
+      "default": true,
+      "description": "Extract thuật ngữ nghiệp vụ → append vào knowledge/domain-glossary.md"
+    },
+    {
+      "id": "conflict_resolution",
+      "question": "Khi tài liệu mới conflict với module cards hiện có?",
+      "options": ["overwrite", "merge", "flag"],
+      "default": "flag",
+      "description": "flag = highlight conflict, để human quyết định. merge = ưu tiên tài liệu mới."
+    }
+  ],
+  "hooks": {
+    "pre_import": "Check source files exist → validate format → check dependency (notebooklm-py nếu cần)",
+    "post_import": "Generate AI drafts cho Module Cards → mark [⚠️ AI-inferred] → suggest BA review"
+  },
+  "memory": {
+    "file": "ba-import-history.log",
+    "format": "[date] | [source_type] | [files_imported] | [glossary_terms] | [conflicts] | [modules_updated]",
+    "purpose": "Track BA doc imports — detect stale modules cần refresh"
+  }
+}

package/skills/understand/ba-docs-scanner/examples/good/work-order-br-extract.md

@@ -0,0 +1,28 @@
+# Good Example — BA Docs Scanner Output cho `work-order` module
+
+> Mẫu extract từ tài liệu BA (không phải code scan).
+> Chú ý: MỌI thông tin kèm trích dẫn source + AI-inferred tag.
+
+## Business Rule trích xuất
+
+```markdown
+### BR-01: Chỉ cho phép sửa WO ở trạng thái DRAFT
+
+- **Trích dẫn gốc**: "Phiếu công tác chỉ được chỉnh sửa khi ở trạng thái
+  Bản nháp. Sau khi gửi duyệt, mọi thay đổi phải thông qua quy trình
+  từ chối và tạo lại."
+- **Source**: WO-spec.pdf, mục 3.2 "Quy định chỉnh sửa"
+- **Điều kiện**: status === DRAFT
+- **Hành động**: Cho phép sửa tất cả fields
+- **Ngoại lệ**: Admin có thể sửa ở mọi trạng thái?
+  [❓ CẦN BA VERIFY — tài liệu không đề cập]
+- [⚠️ AI-inferred from NotebookLM]
+```
+
+## Điểm đáng chú ý
+
+✅ **Trích dẫn nguyên văn** — không paraphrase
+✅ **Source file + section** — truy xuất được
+✅ **Ngoại lệ ghi rõ** — [❓ CẦN BA VERIFY] khi thiếu info
+✅ **AI-inferred tag** — mọi thông tin từ NotebookLM
+❌ **KHÔNG nên**: "BR-01: Không cho sửa WO đã gửi" — quá ngắn, thiếu source

package/skills/understand/ba-docs-scanner/gotchas.md

@@ -0,0 +1,44 @@
+# Gotchas — BA Docs Scanner
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Rule of thumb: Nếu Agent mắc cùng một lỗi 2 lần → bắt buộc phải có gotcha.
+
+---
+
+## Anti-patterns — Output VÔ GIÁ TRỊ từ BA Docs
+
+| Anti-pattern | Ví dụ BAD | Ví dụ GOOD |
+|---|---|---|
+| Paraphrase overview | "Module này quản lý Work Order theo quy trình nghiệp vụ" | "Module xử lý vòng đời WO: DRAFT→duyệt→thực hiện→hoàn thành. 3 roles: User tạo, Manager duyệt, Admin toàn quyền. Tích hợp SAP khi duyệt." |
+| Business rule không trích dẫn | "BR-01: Phải validate input [⚠️ AI-inferred]" | "BR-01: 'Mọi PCT phải có ít nhất 1 item công việc' (Source: WO-spec.pdf, mục 2.3) [⚠️ AI-inferred from NotebookLM]" |
+| Liệt kê entities không mô tả | "Entities: WorkOrder, WoItem, User" | "WorkOrder — Phiếu công tác bảo trì, fields chính: mã (tự sinh), tiêu đề, mô tả lỗi, mức ưu tiên (4 cấp), trạng thái (7 states)" |
+| State diagram bịa | "Có 3 trạng thái: Mới, Xử lý, Xong" | "Theo WO-flow.docx mục 4: 7 trạng thái — Bản nháp, Chờ duyệt, Đã duyệt, Từ chối, Đang thực hiện, Hoàn thành, Đã hủy" |
+| Chỉ tóm tắt, không structured | "BA docs mô tả quy trình tạo và duyệt WO" | Bảng E2E Flow 5 bước + Bảng BR-xx 8 rules + Mermaid state diagram |
+
+---
+
+## Quality Gate — Tự kiểm tra trước khi output BA drafts
+
+| Tiêu chí | Câu hỏi tự kiểm | Nếu KHÔNG → |
+|---|---|---|
+| **Depth** | "Tôi đã đọc TOÀN BỘ fulltext, hay chỉ đọc overview?" | Đọc lại tất cả sources/*.txt |
+| **Extraction** | "Mỗi business rule có kèm TRÍCH DẪN NGUYÊN VĂN + source file?" | Thêm quote + source ref |
+| **Structure** | "Tôi đã convert text mô tả → bảng/diagram chưa?" | Convert sang structured format |
+| **Value-add** | "BA đọc draft thấy info ĐÃ ĐƯỢC TỔ CHỨC LẠI, hay chỉ là copy-paste?" | Phân tích, nhóm, cross-ref |
+| **Completeness** | "Tôi đã cross-reference GIỮA các sources? Có source nào chưa đọc?" | Đọc thêm sources |
+| **Actionability** | "Spec writer đọc xong có ĐỦ CONTEXT để viết spec không cần mở tài liệu gốc?" | Bổ sung chi tiết |
+| **Honesty** | "Tôi có bịa? Mọi suy luận đã gắn [⚠️ AI-inferred]?" | Gắn nhãn, thêm [❓] |
+
+---
+
+## Gotchas phổ biến
+
+1. ❌ ĐỪNG chỉ đọc overview.md rồi tóm tắt — phải đọc TOÀN BỘ fulltext trong sources/
+2. ❌ ĐỪNG paraphrase tài liệu BA — phải TRÍCH DẪN NGUYÊN VĂN kèm source reference
+3. ❌ ĐỪNG bịa state diagram — chỉ vẽ states thực sự được mô tả trong tài liệu
+4. ❌ ĐỪNG tạo permissions.md nếu BA docs không đề cập roles/quyền → tạo placeholder
+5. ❌ ĐỪNG quên cross-reference giữa overview, mind-map, study-guide và fulltext
+6. ✅ Luôn gắn `[⚠️ AI-inferred from NotebookLM]` cho mọi suy luận
+7. ✅ Gắn `[❓ CẦN BA VERIFY]` khi thiếu thông tin — không suy diễn
+8. ✅ Chuyển text mô tả → bảng/diagram — đây là VALUE-ADD chính
+9. ✅ Khi phát hiện mâu thuẫn giữa sources → gắn `[⚠️ CONFLICTING SOURCES]`

package/skills/understand/ba-docs-scanner/merge-rules.md

@@ -0,0 +1,47 @@
+# Merge Rules — U.0d (BA Docs) ↔ U.0b (Code Scan)
+
+> Khi chạy `/v.understand --module {tên}` trên module đã có U.0d data,
+> Agent PHẢI tuân thủ merge rules dưới đây để tránh ghi đè nội dung BA.
+
+---
+
+## Bảng Merge
+
+| File | U.0d đã tạo? | U.0b hành động |
+|------|-------------|---------------|
+| SKILL.md | ✅ Có draft (+ Glossary, Constraints) | **Merge**: giữ business rules + glossary từ U.0d, bổ sung tech info từ code scan |
+| use-cases.md | ✅ Có draft (trích dẫn nguyên văn) | **Merge**: giữ BA content + quotes, bổ sung code references (`Source code: file:line`) |
+| api-specs.md | ⏳ Placeholder | **Fill**: Generate từ code scan |
+| tech-context.md | ⏳ Placeholder | **Fill**: Generate từ code scan |
+| state-diagram.md | ✅ Có draft / ⏳ Placeholder | **Merge**: giữ states từ BA docs, verify + bổ sung enum values từ code. Nếu placeholder → **Fill** |
+| permissions.md | ✅ Có draft / ⏳ Placeholder | **Merge**: giữ role matrix từ BA docs, verify + bổ sung guards/decorators từ code. Nếu placeholder → **Fill** |
+| db.md | ✅ Có draft / ⏳ Placeholder | **Merge**: giữ entity descriptions từ BA, verify + bổ sung schema chi tiết từ code. Nếu placeholder → **Fill** |
+| ui-flows.md | ✅ Có draft / ⏳ Placeholder | **Merge**: giữ user flows từ BA, verify + bổ sung component mapping từ code. Nếu placeholder → **Fill** |
+| cross-service.md | ✅ Có draft | **Merge**: giữ BA context, bổ sung code-level dependencies |
+
+---
+
+## Merge Rules
+
+1. **Giữ nguyên nội dung BA**: Nội dung có tag `[⚠️ AI-inferred from NotebookLM]` → giữ nguyên, bổ sung code evidence bên dưới.
+
+2. **Conflict resolution**:
+   - Nếu code **mâu thuẫn** với BA docs → gắn `[⚠️ CONFLICT: code vs BA doc — CẦN BA VERIFY]`
+   - Nếu code **xác nhận** BA docs → xóa tag `[⚠️ AI-inferred]`, thay bằng `[✅ Verified by code scan]`
+
+3. **Placeholder → Fill**: Nếu file U.0d là placeholder → U.0b generate đầy đủ (không cần merge).
+
+4. **Human-verified content**: Nội dung đã được BA xóa tag `[⚠️ AI-inferred]` → KHÔNG ghi đè. Chỉ bổ sung code references bên dưới.
+
+---
+
+## Detect U.0d Data
+
+Cách nhận biết module đã có U.0d data:
+
+```
+Nếu tồn tại .v-flow/modules/{module}/raw/sources/*.txt
+  → Module có U.0d data → áp dụng Merge rules
+Nếu không
+  → Module chưa có U.0d → U.0b generate bình thường
+```