@educa-corp/sdd-framework 0.1.0

package/core/modules/react/module.yaml

@@ -0,0 +1,14 @@
+name: "React"
+version: "1.0.0"
+description: "React 18 SPA with hooks, React Query, and Zustand"
+language: "TypeScript"
+framework: "React"
+stack_type: "frontend"
+default_layer_order:
+  - Types / interfaces
+  - API client (React Query hooks)
+  - State store (Zustand)
+  - Custom hooks (business logic)
+  - UI components (presentational)
+  - Page / feature components (container)
+test_framework: "Vitest + React Testing Library"

package/core/modules/react/stack-profile.yaml

@@ -0,0 +1,63 @@
+build:
+  compile: "npm run build"
+  test: "npm test"
+  run: "npm run dev"
+  lint: "npm run lint"
+
+architecture:
+  style: "Feature-based (components → hooks → queries → store)"
+  key_rules:
+    - "Business logic lives in custom hooks, not in components"
+    - "Server state managed by React Query (useQuery / useMutation)"
+    - "Client-only UI state managed by Zustand or useState"
+    - "Components must be pure functions — no direct API calls inside JSX"
+    - "Shared UI primitives in components/ui/, feature logic in features/{name}/"
+    - "Never fetch data directly in a component — use a custom hook"
+  folder_structure: |
+    src/
+    ├── api/              ← axios instance, interceptors
+    ├── components/
+    │   └── ui/           ← reusable primitives (Button, Modal, Table...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── components/   ← feature-specific UI
+    │       ├── hooks/        ← useOrderList, useCreateOrder...
+    │       ├── queries/      ← React Query definitions
+    │       ├── store/        ← Zustand slice (if needed)
+    │       └── types.ts
+    ├── pages/            ← route-level page components
+    └── lib/              ← utilities, formatters, constants
+
+coding_standards:
+  naming:
+    components: "PascalCase (e.g., OrderList, CreateOrderModal)"
+    hooks: "camelCase with 'use' prefix (e.g., useOrderList, useCreateOrder)"
+    query_keys: "SCREAMING_SNAKE_CASE array (e.g., ['ORDER_LIST', customerId])"
+    stores: "camelCase + Store suffix (e.g., useCartStore)"
+    files:
+      component: "{Feature}.tsx"
+      hook: "use{Feature}.ts"
+      query: "{feature}.queries.ts"
+      store: "{feature}.store.ts"
+      types: "{feature}.types.ts"
+  patterns:
+    data_fetching: "React Query (TanStack Query v5)"
+    global_state: "Zustand slices"
+    forms: "React Hook Form + Zod validation"
+    api_client: "Axios with interceptors for auth + error handling"
+    error_boundary: "React ErrorBoundary wraps each feature route"
+
+testing:
+  unit: "Vitest + React Testing Library"
+  e2e: "Playwright or Cypress"
+  patterns:
+    - "Test behavior, not implementation — query by role/label, not className"
+    - "Mock React Query with a QueryClient wrapper in test setup"
+    - "Use MSW (Mock Service Worker) to mock API calls in tests"
+    - "renderWithProviders() helper wraps component with QueryClient + Router"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"

package/core/modules/react-native/module.yaml

@@ -0,0 +1,14 @@
+name: "React Native"
+version: "1.0.0"
+description: "Cross-platform mobile (iOS + Android) with React Native / Expo"
+language: "TypeScript"
+framework: "React Native"
+stack_type: "mobile"
+default_layer_order:
+  - Types / interfaces
+  - API client (React Query hooks)
+  - State store (Zustand)
+  - Custom hooks (business logic)
+  - UI components (presentational)
+  - Screen / feature components (container)
+test_framework: "Jest + React Native Testing Library"

package/core/modules/react-native/stack-profile.yaml

@@ -0,0 +1,56 @@
+build:
+  compile: "npx expo export / npx react-native build-android"
+  test: "jest"
+  run: "npx expo start / npx react-native run-ios"
+  lint: "eslint . && tsc --noEmit"
+
+architecture:
+  style: "Feature-based (screens → hooks → queries → store)"
+  key_rules:
+    - "Business logic lives in custom hooks, not in screen components"
+    - "Server state managed by React Query (TanStack Query)"
+    - "Navigation state managed by React Navigation"
+    - "Native modules wrapped in a service layer — never called directly in components"
+    - "Shared UI primitives in src/components/ui/, feature screens in src/features/{name}/"
+  folder_structure: |
+    src/
+    ├── api/              ← axios instance, interceptors
+    ├── components/
+    │   └── ui/           ← reusable primitives (AppButton, AppInput...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── components/
+    │       ├── hooks/
+    │       ├── queries/
+    │       └── screens/
+    ├── navigation/       ← React Navigation stacks/tabs
+    ├── store/            ← Zustand slices
+    └── lib/              ← utils, formatters, constants
+
+coding_standards:
+  naming:
+    components: "PascalCase (e.g., OrderListScreen, CreateOrderForm)"
+    hooks: "camelCase with 'use' prefix (e.g., useOrderList)"
+    screens: "PascalCase + Screen suffix (e.g., OrderDetailScreen)"
+    files:
+      screen: "{Feature}Screen.tsx"
+      component: "{Feature}.tsx"
+      hook: "use{Feature}.ts"
+  patterns:
+    state_management: "Zustand + React Query"
+    navigation: "React Navigation v6 (Stack + Tab + Drawer)"
+    networking: "Axios"
+    forms: "React Hook Form + Zod"
+    storage: "MMKV or AsyncStorage"
+
+testing:
+  unit: "Jest + React Native Testing Library"
+  e2e: "Detox or Maestro"
+  patterns:
+    - "Test by accessibility label or testID — never by style/className"
+    - "Mock native modules in jest setup"
+    - "Use renderWithProviders() with NavigationContainer + QueryClient"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"

package/core/modules/vue/module.yaml

@@ -0,0 +1,14 @@
+name: "Vue"
+version: "1.0.0"
+description: "Vue 3 SPA with Composition API, Pinia, and Vue Query"
+language: "TypeScript"
+framework: "Vue 3"
+stack_type: "frontend"
+default_layer_order:
+  - Types / interfaces
+  - API client (Vue Query / composables)
+  - State store (Pinia)
+  - Composables (business logic)
+  - UI components (presentational)
+  - Page / feature components (container)
+test_framework: "Vitest + Vue Test Utils"

package/core/modules/vue/stack-profile.yaml

@@ -0,0 +1,65 @@
+build:
+  compile: "npm run build"
+  test: "npm run test"
+  run: "npm run dev"
+  lint: "npm run lint"
+
+architecture:
+  style: "Feature-based (components → composables → queries → store)"
+  key_rules:
+    - "Business logic lives in composables, not in component setup()"
+    - "Server state managed by Vue Query (@tanstack/vue-query)"
+    - "Client-only UI state managed by Pinia stores"
+    - "Components must be pure — no direct API calls inside <template> or setup()"
+    - "Shared UI primitives in components/ui/, feature logic in features/{name}/"
+    - "Never fetch data directly in a component — use a composable"
+    - "Props defined with defineProps<{}>(), emits with defineEmits<{}>()"
+  folder_structure: |
+    src/
+    ├── api/              ← axios instance, interceptors
+    ├── components/
+    │   └── ui/           ← reusable primitives (BaseButton, BaseInput...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── components/   ← feature-specific UI
+    │       ├── composables/  ← useOrderList, useCreateOrder...
+    │       ├── queries/      ← Vue Query definitions
+    │       ├── store/        ← Pinia slice (if needed)
+    │       └── types.ts
+    ├── pages/            ← route-level page components (Vue Router)
+    ├── router/           ← route definitions
+    └── lib/              ← utilities, formatters, constants
+
+coding_standards:
+  naming:
+    components: "PascalCase (e.g., OrderList, CreateOrderModal)"
+    composables: "camelCase with 'use' prefix (e.g., useOrderList, useCreateOrder)"
+    stores: "camelCase + Store suffix (e.g., useCartStore) — defined with defineStore()"
+    query_keys: "SCREAMING_SNAKE_CASE string/array (e.g., ['ORDER_LIST', customerId])"
+    files:
+      component: "{Feature}.vue"
+      composable: "use{Feature}.ts"
+      query: "{feature}.queries.ts"
+      store: "{feature}.store.ts"
+      types: "{feature}.types.ts"
+  patterns:
+    data_fetching: "Vue Query (TanStack Query v5 for Vue)"
+    global_state: "Pinia stores"
+    forms: "VeeValidate + Zod"
+    api_client: "Axios with interceptors for auth + error handling"
+    reactivity: "ref() for primitives, reactive() for objects, computed() for derived state"
+
+testing:
+  unit: "Vitest + Vue Test Utils"
+  e2e: "Playwright or Cypress"
+  patterns:
+    - "Test behavior, not implementation — query by role/label via @testing-library/vue"
+    - "Mock Vue Query with VueQueryPlugin wrapper in test setup"
+    - "Use MSW (Mock Service Worker) to mock API calls in tests"
+    - "mountWithProviders() helper wraps component with Pinia + VueQuery + Router"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"

package/core/rules/data-protection.md

@@ -0,0 +1,80 @@
+# Data Protection Rules
+
+> These rules are loaded by `steps/context-loader.md` at the start of every command.
+> AI agents MUST follow these rules without exception.
+
+---
+
+## NEVER Read — Sensitive Files
+
+The following file patterns contain credentials, secrets, or private keys.
+**Do NOT read, display, log, or reference their contents under any circumstance.**
+
+### Environment & Secrets
+- `.env`
+- `.env.*` (e.g., `.env.local`, `.env.production`, `.env.staging`)
+- `*.secret`
+- `secrets/` (entire directory)
+- `.secrets/` (entire directory)
+- `*credentials*`
+
+### Cryptographic Keys & Certificates
+- `*.key`
+- `*.pem`
+- `*.p12`
+- `*.pfx`
+- `*.jks`
+- `*.keystore`
+- `*.crt` / `*.cert`
+
+### Framework-Specific Config Files (may contain DB passwords, API keys)
+- `application-prod.yml` / `application-prod.properties`
+- `application-production.yml`
+- `appsettings.Production.json`
+- `appsettings.Staging.json`
+- `database.yml` (Rails)
+- `config/master.key` (Rails)
+- `storage/oauth-private.key`
+
+### Files Matching Dangerous Keywords
+Any file whose name contains (case-insensitive):
+- `password`
+- `passwd`
+- `secret`
+- `private_key`
+- `api_key`
+- `access_token`
+- `auth_token`
+
+---
+
+## NEVER Write or Modify
+
+- Any file listed above
+- `*.lock` files that are not package lock files (e.g., `*.lock` outside of `package-lock.json`, `yarn.lock`, `composer.lock`)
+
+---
+
+## NEVER Execute via Bash
+
+- Commands that print secrets: `printenv`, `env | grep -i secret`, `cat .env`
+- Commands that expose credentials: `docker inspect`, `kubectl get secret -o yaml`
+- Git commands that may expose history of secrets: `git show`, `git log -p` on config files
+
+---
+
+## Safe Alternatives
+
+If context about environment configuration is needed:
+
+1. Ask the user to describe the configuration **without sharing actual values**.
+2. Reference the **structure** of config (keys, not values): "I see you use `DATABASE_URL` — I'll generate code that reads from that variable."
+3. Use placeholder values in generated code: `process.env.DATABASE_URL` or `${DATABASE_URL}`.
+
+---
+
+## If a Sensitive File is Accidentally Accessed
+
+1. Do NOT display or repeat any content from the file.
+2. Immediately stop and notify the user: "I've detected a sensitive file. I will not read or use its contents."
+3. Ask the user what they actually need (usually it's the structure, not the values).

package/core/rules/workflow.md

@@ -0,0 +1,44 @@
+# Workflow Rules
+
+> General AI behavior rules for all spec-driven-docs commands.
+> Loaded by `steps/context-loader.md` at the start of every command.
+
+---
+
+## Checkpoints
+
+- **Always** show a CHECKPOINT before making significant changes.
+- A CHECKPOINT must include: what will be done, which files will be created/modified, estimated scope.
+- Wait for explicit "Y" or user confirmation before proceeding.
+- Exception: read-only analysis commands (`/review-code`, `/validate-traces`, `/debug`) may skip CHECKPOINT.
+
+## Scope Control
+
+- Work only within the scope explicitly confirmed at CHECKPOINT.
+- Do NOT create files outside the directories specified in `project-context.yaml → paths`.
+- If new scope is discovered mid-command, STOP and ask: "I found additional scope [{description}]. Should I include it? (Y/N)"
+
+## Code Generation
+
+- Never generate code for files not backed by a `.feature` spec (unless `/fix-bug` or `/debug`).
+- Always add `@trace.implements` tags on controller-level methods.
+- Never overwrite existing business logic without explicit confirmation.
+- Build must pass before committing: run `{conventions.build_command}` and fix errors (max 3 retries).
+
+## File Operations
+
+- Prefer **editing** existing files over replacing them entirely.
+- When creating new files, check if a similar file already exists first.
+- Never delete files unless explicitly instructed.
+
+## Communication
+
+- Report in the language the user writes in (Vietnamese if user uses Vietnamese, English otherwise).
+- Keep reports structured: status, artifacts created, next recommended command.
+- If unsure about business intent, ask — do not guess and generate wrong spec.
+
+## Error Handling
+
+- If a tool call fails (file not found, build error, etc.), report the specific error clearly.
+- Do NOT silently skip errors or pretend success.
+- Suggest a concrete fix, not just "please check the error".

package/core/skills/code/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Sinh implementation code từ BDD spec đã duyệt kèm tag traceability, hoặc review code read-only đối chiếu spec compliance và quy tắc kiến trúc. Trigger when: "/generate-code", "/review-code", "sinh code", "generate code", "viết code", "implement feature", "review code", "kiểm tra code", "code review", "check implementation".
+---
+
+# Code Skills — Generate & Review
+
+Skill này xử lý `/generate-code` và `/review-code`. Để **không lệch schema/gate**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
+
+## /generate-code — Sinh Implementation Code
+
+→ **Đọc và tuân theo `commands/generate-code.md`** với cùng `$ARGUMENTS`.
+
+Command lo: guard mềm BDD `@trace.status` approved + Design Spec (approved/độ-tươi/sanity) cho FE/App · `--phase=ui`/`--phase=integration` · branch + build verify · trace TSV (22 cột) `@trace.implements`.
+
+## /review-code — Code Review chỉ-đọc (READ-ONLY)
+
+→ **Đọc và tuân theo `commands/review-code.md`** với cùng `$ARGUMENTS`.
+
+Command lo: Pre-Review Scan · 4 lăng kính (Traceability · Layer Architecture · Coding Standards · Spec Compliance) · đề xuất ghi Lesson cho lỗi AI lặp.

package/core/skills/debug/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Fix bug với full workflow (branch, test, commit), phân tích debug nhanh các lỗi hoặc hành vi bất ngờ, hoặc kiểm chứng độ phủ traceability giữa spec và code. Trigger when: "/fix-bug", "/debug", "/validate-traces", "fix bug", "sửa bug", "debug lỗi", "phân tích lỗi", "tại sao lỗi này", "validate traces", "kiểm tra traceability", "coverage matrix", "trace drift".
+---
+
+# Debug & Quality Skills — Fix Bug, Debug, Validate Traces
+
+Skill này xử lý `/fix-bug`, `/debug`, `/validate-traces`. Để **không lệch schema/flow**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command.
+
+## /fix-bug — Full Bug Fix Workflow
+→ **Đọc và tuân theo `commands/fix-bug.md`** với cùng `$ARGUMENTS`.
+(Command lo: bug-type table theo platform · đọc `{BUG-ID}` report · regression test · build + push 2 tầng (umbrella) · BUG State `Open→Fixed`→`Closed` · đề xuất Lesson.)
+
+## /debug — Phân tích nhanh
+→ **Đọc và tuân theo `commands/debug.md`** với cùng `$ARGUMENTS`.
+(Command lo: 4 path (stack trace / reproduce / test fail / câu hỏi code) · bảng lỗi theo từng platform/module · stack-trace đọc dưới-lên.)
+
+## /validate-traces — Traceability Coverage
+→ **Đọc và tuân theo `commands/validate-traces.md`** với cùng `$ARGUMENTS`.
+(Command lo: đọc trace TSV 22 cột authoritative · tính OK/DRIFT/GAP/UNTRACKED + PRD/TECHDOC drift · sync `uc_status` ← `@trace.status` · aggregate dashboard.)

package/core/skills/design-spec/SKILL.md

@@ -0,0 +1,11 @@
+---
+description: Sinh tài liệu Design Specification cho platform FE hoặc App từ một Business PRD. Trigger when: "/generate-design-spec", "tạo design spec", "generate design spec", "viết design spec", "tạo tài liệu thiết kế UI", "generate UI spec", "cần design spec cho", "tôi muốn spec UI", "tài liệu cho FE", "tài liệu cho app".
+---
+
+# /generate-design-spec — Generate Design Specification (FE / App)
+
+Skill này xử lý `/generate-design-spec`. Để **không lệch gate/schema**, skill KHÔNG nhân bản — thực thi **y hệt** command.
+
+→ **Đọc và tuân theo `commands/generate-design-spec.md`** với cùng `$ARGUMENTS`.
+
+Command lo: guard PRD approved (mềm) · ghi `Built from PRD` + Version Check drift · Figma per-screen node-level link (`?node-id=`) fetch qua MCP, màn thiếu link → ❌ Missing → Status giữ `draft` · Screen Inventory/Specs/States · Interaction Patterns + Platform Considerations theo platform · AC-UI (Verified by) · **Self-Review Gate** trước khi ghi · chỉ FE/App (BE bị từ chối).

package/core/skills/discovery/SKILL.md

@@ -0,0 +1,14 @@
+---
+description: Dẫn dắt product discovery cho một feature mới qua Q&A có cấu trúc. Trigger when: "/define-product", "khám phá tính năng", "define new feature", "start new feature", "product discovery", "tôi muốn build tính năng mới", "let's define a feature", "begin feature discovery".
+---
+
+# /define-product — Feature Discovery (Q&A theo phase)
+
+Lệnh này thực thi **y hệt** `commands/define-product.md` — không nhân bản logic ở đây để tránh lệch cấu trúc / phase / path output.
+
+`commands/define-product.md` dẫn PO qua các phase Q&A có checkpoint:
+Knowledge Sync → Feature Definition (Context/Problem/Goal/Actor/In&Out Scope/User Story/Phụ thuộc liên service) → User Flow (kèm Edge Cases) → Clarification Log → Business Rules → Business Logic → Acceptance Criteria → Validation Report.
+
+Output ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/product-definition.template.md` — input cho `/generate-prd`.
+
+→ **Đọc và tuân theo `commands/define-product.md`** với cùng `$ARGUMENTS`.

package/core/skills/prd/SKILL.md

@@ -0,0 +1,19 @@
+---
+description: Sinh PRD từ một product definition, hoặc phân tích một PRD có sẵn qua 4 lăng kính review (QA, DEV, SA, PO) để tìm gap và rủi ro. Trigger when: "/generate-prd", "/refine-prd", "tạo PRD", "generate PRD", "phân tích PRD", "review PRD", "refine PRD", "PRD có vấn đề gì không", "check PRD quality".
+---
+
+# PRD Skills — Generate & Refine
+
+Skill này xử lý `/generate-prd` và `/refine-prd`. Để **không lệch logic/schema**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
+
+## /generate-prd — Sinh Product Requirements Document
+
+→ **Đọc và tuân theo `commands/generate-prd.md`** với cùng `$ARGUMENTS`.
+
+Command lo: guard discovery completed · phân giải API Source (existing/greenfield/partner) · Terminology Map · map §1c "Phụ thuộc liên service" + §4b Wireframe · slug kế thừa · template canonical (`templates/prd.template.md`) · Change Log rolling-window.
+
+## /refine-prd — Phân tích PRD qua 4 lăng kính review
+
+→ **Đọc và tuân theo `commands/refine-prd.md`** với cùng `$ARGUMENTS`.
+
+Command lo: 4 lăng kính fan-out đa sub-agent + completeness-critic (findings đầy đủ 1 lần chạy) · schema findings đầy đủ (`uc_id`, `quote`, `auto_fixable`) cho Review Board · Resume Mode (apply → bump version → reset draft → changelog).

package/core/skills/qc/qa-analyst/DOC_GAPS.template.md

@@ -0,0 +1,63 @@
+---
+version: 1.1
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Gap Analysis – <FEATURE>
+
+> File ghi lại các **khoảng trống của tài liệu** mà `qa-analyst` phát hiện sau khi
+> phân tích. Là đầu vào để hỏi dev/BA và cho `qa-planner`. Mỗi gap có ID `GAP-xx`
+> để business rule (BR-xx), acceptance criteria (AC-xx) và test case trace ngược về.
+
+| Trường | Giá trị |
+|---|---|
+| Feature | `<FEATURE>` |
+| Project / Service | `<project or service name / domain>` |
+| Tài liệu nguồn | `<đường dẫn / link PRD / user story>` |
+| Người phân tích | qa-analyst |
+| Ngày phân tích | `<YYYY-MM-DD>` |
+| Tổng số gap | `<N>` (Blocker: x · High: y · Medium: z · Low: w) |
+| Trạng thái chung | 🔴 Blocked / 🟡 Cần làm rõ / 🟢 Đủ rõ để thiết kế TC |
+
+---
+
+## Bảng Gap
+
+| ID | Loại | Mô tả gap | Vị trí (mục/nguồn) | Ảnh hưởng (chức năng / BR / AC) | Mức độ | Người trả lời | Trạng thái | Câu trả lời |
+|---|---|---|---|---|---|---|---|---|
+| GAP-01 | MISSING | … | spec §x | chức năng A / BR-02 | 🔴 Blocker | Dev/BA | Open | — |
+| GAP-02 | AMBIGUOUS | … | mockup màn hình Y | AC-03 | 🟠 High | BA | Open | — |
+| GAP-03 | CONTRADICTORY | … | §2 vs §5 | BR-04 | 🟠 High | BA | Open | — |
+| GAP-04 | ASSUMPTION | … (giả định AI tự đưa, cần xác nhận) | — | chức năng B | 🟡 Medium | Dev | Open | — |
+
+### Loại gap
+- **MISSING** – thông tin/chức năng/field/rule chưa được mô tả.
+- **AMBIGUOUS** – mô tả mơ hồ, có ≥ 2 cách hiểu.
+- **CONTRADICTORY** – các phần tài liệu mâu thuẫn nhau.
+- **ASSUMPTION** – giả định do qa-analyst tự suy ra, cần dev/BA xác nhận.
+- **OPEN QUESTION** – câu hỏi mở cần trả lời trước khi thiết kế/triển khai.
+
+### Mức độ
+🔴 Blocker (chặn thiết kế TC) · 🟠 High · 🟡 Medium · 🟢 Low
+
+---
+
+## Quy ước cập nhật
+- `qa-analyst` tạo & điền gap khi phân tích; **không tự bịa câu trả lời** cho gap Blocker.
+- Khi có phản hồi dev/BA: điền cột *Câu trả lời*, đổi *Trạng thái* → `Answered`.
+- Còn gap 🔴 Blocker `Open` ⇒ **chưa** chuyển sang `qa-designer`; đẩy sang `qa-planner`
+  (skill `questions-for-dev`) để chốt câu hỏi.
+
+---
+
+## ⚠️ Checklist bắt buộc trước khi lưu file
+
+Trước khi lưu `DOC_GAPS.md`, kiểm tra **từng hàng** trong bảng gap:
+
+- [ ] **9 cột đủ** – đúng thứ tự: `ID | Loại | Mô tả gap | Vị trí (mục/nguồn) | Ảnh hưởng (chức năng / BR / AC) | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
+- [ ] **Cột Vị trí không rỗng** – phải có tham chiếu cụ thể đến mục trong tài liệu nguồn (vd `§3 UC4 BR25`, `Appendix B loại 7`, `§4.b Screen 3`). Đây là cột hay bị bỏ thiếu nhất → gây lệch toàn bộ cột sau.
+- [ ] **Cột Ảnh hưởng = BR/AC references** – KHÔNG phải mức độ severity. Ví dụ đúng: `BR25, BR26 / AC-F01-33`. Nếu thấy "Blocker" / "High" ở đây → đang bị lệch cột.
+- [ ] **Cột Mức độ có emoji** – bắt buộc dùng: `🔴 Blocker` / `🟠 High` / `🟡 Medium` / `🟢 Low`. Không được ghi text thuần.
+- [ ] **Cột Người trả lời = vai trò** (PO / BA / Dev / Design / Content / DPO / QC Lead). Nếu thấy "Open" ở đây → đang bị lệch cột.
+- [ ] **Cột Trạng thái = Open / Answered**. Nếu thấy "—" ở đây → đang bị lệch cột.

package/core/skills/qc/qa-analyst/acceptance-criteria.md

@@ -0,0 +1,60 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Acceptance Criteria — Sinh tiêu chí chấp nhận
+
+Chuyển yêu cầu đã phân tích thành acceptance criteria (Given/When/Then) làm cơ sở thiết kế TC.
+
+## Khi nào trigger
+- "viết acceptance criteria cho [X]" / "định nghĩa tiêu chí pass"
+- Sau spec-breakdown + business-rules, là bước cuối của qa-analyst
+- Cần điều kiện chấp nhận rõ ràng để qa-designer trace TC ngược về
+
+## Khi KHÔNG trigger
+- Cần bóc tách spec → dùng spec-breakdown
+- Cần thiết kế test case chi tiết (steps cụ thể) → dùng qa-designer
+- Cần phân tích rủi ro → dùng qa-planner
+
+---
+
+## Phase 1 — Tổng hợp
+
+Gom đầu vào từ spec-breakdown, business-rules, data-flow:
+- Mỗi chức năng/luồng → một nhóm acceptance criteria.
+- Mỗi business rule (BR-xx) → ít nhất một AC kiểm chứng.
+
+---
+
+## Phase 2 — Viết AC
+
+Dùng format Given/When/Then, mỗi AC kiểm chứng MỘT điều:
+
+```
+AC-01 (chức năng / BR-xx):
+  Given <tiền điều kiện>
+  When  <hành động + dữ liệu cụ thể>
+  Then  <kết quả mong đợi CỤ THỂ>
+```
+
+Bắt buộc phủ:
+- Happy path (điều kiện hợp lệ).
+- Negative (vi phạm validation / authorization).
+- Boundary (giá trị biên của giới hạn trong business-rules).
+- Alternate flow (luồng phụ trong data-flow).
+
+Mỗi AC gắn mã trace: chức năng + BR-xx để TC sau này map 1-1.
+
+---
+
+## Output
+
+Ghi vào **mục Acceptance Criteria** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`):
+
+- Danh sách AC dạng Given/When/Then, có mã trace về chức năng, business rule (BR-xx)
+  và scenario chính thức `{UC-ID}-SC{N}` của `.feature`.
+- Bảng ma trận: BR / chức năng × AC để xác nhận không bỏ sót.
+- Đây là đầu vào trực tiếp cho `qa-designer` (mỗi AC → ≥1 test case) và `qa-reviewer` (đối chiếu coverage).

package/core/skills/qc/qa-analyst/business-rules.md

@@ -0,0 +1,59 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Business Rules — Trích xuất luật nghiệp vụ
+
+Trích xuất và liệt kê toàn bộ business rule, điều kiện và ràng buộc từ yêu cầu.
+
+## Khi nào trigger
+- "liệt kê business rule cho [X]" / "feature này có luật nghiệp vụ gì"
+- Sau spec-breakdown, khi cần làm rõ logic điều kiện trước khi thiết kế TC
+- Feature có nhiều điều kiện AND/OR, phân quyền, tính toán, giới hạn
+
+## Khi KHÔNG trigger
+- Cần bóc tách tổng thể spec → dùng spec-breakdown
+- Cần luồng dữ liệu → dùng data-flow
+- Cần phân tích rủi ro / lập test plan → thuộc qa-planner (skill test-plan)
+
+---
+
+## Phase 1 — Quét
+
+1. Đọc spec đã bóc tách (output của spec-breakdown) hoặc tài liệu gốc.
+2. Quét tìm: điều kiện ("nếu… thì…"), ràng buộc field, giới hạn (min/max, rate limit),
+   quy tắc phân quyền, công thức tính, quy tắc trạng thái, default value.
+
+---
+
+## Phase 2 — Cấu trúc hoá
+
+Mỗi rule ghi dưới dạng bảng:
+
+| ID | Rule | Điều kiện | Kết quả | Nguồn | Ghi chú/Ưu tiên |
+|---|---|---|---|---|---|
+| BR-01 | … | … | … | spec §x | … |
+
+Phân loại rule:
+- VALIDATION: ràng buộc input (định dạng, bắt buộc, độ dài, range).
+- AUTHORIZATION: ai được làm gì.
+- CALCULATION: công thức, làm tròn, đơn vị.
+- STATE: điều kiện chuyển trạng thái hợp lệ vs cấm.
+- LIMIT: rate limit, quota, concurrent.
+
+Với rule có nhiều điều kiện kết hợp → gợi ý dựng **Decision Table** (đầu vào cho qa-designer).
+
+---
+
+## Output
+
+Ghi vào **mục Business Rules** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`):
+
+- Bảng business rule có ID (BR-xx) để TC trace ngược về.
+- Gợi ý các rule cần Decision Table / BVA khi sang qa-designer.
+
+Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`
+(loại CONTRADICTORY / AMBIGUOUS, cột "Ảnh hưởng" trỏ BR-xx).