@anhth2/spec-driven-dev-plugin 0.10.0 → 0.11.0

package/core/skills/debug/SKILL.md

@@ -163,19 +163,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -275,7 +297,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -442,6 +465,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
@@ -586,6 +616,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
@@ -687,6 +724,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

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

@@ -237,19 +237,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -349,7 +371,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -471,6 +494,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

package/core/skills/discovery/SKILL.md

@@ -142,19 +142,41 @@ If the file does not exist → skip silently.
 
 ---
 
-## Step 3 — [CRITICAL] Load CLAUDE.md
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
 
 *This is the highest-priority context — it defines HOW to write code and documents for this project.*
 
-Read `CLAUDE.md`. Extract and store:
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
 
 - **§1 Project Overview** → project name, language, framework, build/test commands, domains
-- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
-- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
-- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
-- **§7 Git Conventions** → branch naming pattern, commit message format
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
 
-If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
 
 ---
 
@@ -254,7 +276,8 @@ Output exactly this block:
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
 Platform  : {active_module} ({platform_type})
-Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
@@ -452,6 +475,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

package/core/skills/prd/SKILL.md

@@ -194,6 +194,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
@@ -443,6 +450,13 @@ Suggest the logical next command based on workflow phase:
 | /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` to verify coverage |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
 | /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |

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,56 @@
+---
+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
+
+- Danh sách AC dạng Given/When/Then, có mã trace về chức năng và business rule.
+- 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,55 @@
+---
+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
+
+- Bảng business rule có ID (BR-xx) để TC trace ngược về.
+- Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `DOC_GAPS.md` (loại CONTRADICTORY / AMBIGUOUS,
+  cột "Ảnh hưởng" trỏ BR-xx) rồi ghi vào `DOC_GAPS.md`.
+- Gợi ý các rule cần Decision Table / BVA khi sang qa-designer.

package/core/skills/qc/qa-analyst/data-flow.md

@@ -0,0 +1,60 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Data Flow — Phân tích luồng dữ liệu
+
+Phân tích luồng dữ liệu, input/output, state và điểm tích hợp của feature.
+
+## Khi nào trigger
+- "phân tích data flow cho [X]" / "dữ liệu đi qua đâu"
+- Feature có nhiều bước, qua nhiều màn hình/API/DB, hoặc tích hợp Kafka/service khác
+- Cần xác định điểm tích hợp trước khi thiết kế integration/e2e TC
+
+## Khi KHÔNG trigger
+- Chỉ cần bóc tách spec tổng quan → dùng spec-breakdown
+- Chỉ cần luật nghiệp vụ → dùng business-rules
+- Thiết kế integration TC → dùng qa-designer/integration
+
+---
+
+## Phase 1 — Lập bản đồ
+
+Với mỗi luồng nghiệp vụ, xác định:
+1. ĐIỂM BẮT ĐẦU: actor/sự kiện kích hoạt + dữ liệu đầu vào.
+2. CÁC CHẶNG: UI → API → service → DB → message queue → service ngoài.
+3. BIẾN ĐỔI: dữ liệu được tạo/sửa/xoá/validate ở mỗi chặng.
+4. ĐIỂM KẾT THÚC: output, side-effect (email, notification, audit log).
+
+---
+
+## Phase 2 — Mô tả
+
+Thể hiện luồng dạng bước tuần tự hoặc sơ đồ text:
+
+```
+[User submit form]
+   → POST /api/... (payload: ...)
+   → Service validate (rule BR-xx)
+   → DB insert bảng X
+   → Kafka topic Y (event Z)
+   → UI hiển thị kết quả / trạng thái
+```
+
+Đánh dấu cho mỗi chặng:
+- INTEGRATION POINT (nơi cần integration test).
+- STATE CHANGE (dữ liệu/trạng thái thay đổi → cần verify + cleanup).
+- FAILURE POINT (nơi có thể lỗi: timeout, validation fail, partial commit).
+
+---
+
+## Output
+
+- Sơ đồ/list luồng dữ liệu cho mỗi kịch bản chính.
+- Danh sách integration point + state change + failure point.
+- Chặng nào luồng/hành vi chưa rõ (vd lỗi xử lý ra sao, retry, partial commit) →
+  ghi vào `DOC_GAPS.md` (loại MISSING / OPEN QUESTION).
+- Gợi ý loại test cần cho từng điểm (gui-feature / integration / e2e) khi sang qa-designer.
+- Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho qa-runner.

package/core/skills/qc/qa-analyst/spec-breakdown.md

@@ -0,0 +1,57 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Spec Breakdown — Bóc tách yêu cầu
+
+Bóc tách spec/PRD/user story thô thành mô tả yêu cầu có cấu trúc cho QC.
+
+## Khi nào trigger
+- "phân tích spec/PRD cho feature [X]" / "bóc tách yêu cầu"
+- Nhận tài liệu thô (PRD, user story, mô tả Figma, email) cần làm rõ trước khi thiết kế TC
+- Là bước ĐẦU TIÊN của pipeline, trước qa-planner
+
+## Khi KHÔNG trigger
+- Cần phân tích rủi ro / what-if → dùng qa-planner
+- Cần trích riêng business rule → dùng business-rules
+- Cần thiết kế test case → dùng qa-designer
+
+---
+
+## Phase 1 — Thu thập
+
+1. Đọc toàn bộ tài liệu nguồn QC cung cấp (PRD, user story, mockup, ghi chú).
+2. **Bỏ qua văn bản gạch ngang (strikethrough)** — đó là nội dung đã huỷ, KHÔNG đưa
+   vào phân tích/BR/AC. Với file Confluence/HTML/MHTML: phát hiện qua thẻ `<s>`,
+   `<strike>`, `<del>` hoặc style `text-decoration: line-through`.
+3. Xác định: feature name, actor/role, mục tiêu nghiệp vụ, phạm vi (in/out scope).
+4. Đánh dấu phần MƠ HỒ / THIẾU → ghi vào `DOC_GAPS.md` (gap GAP-xx).
+
+---
+
+## Phase 2 — Bóc tách
+
+Tách yêu cầu thành các khối:
+
+A. TỔNG QUAN: mục tiêu, actor, giá trị nghiệp vụ.
+B. CHỨC NĂNG: list từng chức năng (visible + ẩn + integration point).
+C. INPUT/OUTPUT: mỗi chức năng có input gì, output gì, ràng buộc field.
+D. TRẠNG THÁI & LUỒNG: các state, điều kiện chuyển, happy path + alternate flow.
+E. PHỤ THUỘC: hệ thống/API/module liên quan.
+F. GIẢ ĐỊNH & CÂU HỎI MỞ: điều suy ra được vs điều cần dev/BA xác nhận.
+
+---
+
+## Output
+
+File Markdown mô tả yêu cầu có cấu trúc (đặt trong `docs/<project>/<feature>/`):
+- Bảng chức năng + input/output/constraint
+- Sơ đồ/list luồng chính & phụ
+- Danh sách giả định và câu hỏi mở (đánh dấu rõ điều CHƯA chắc)
+
+Đồng thời ghi mọi khoảng trống phát hiện vào `docs/<project>/<feature>/DOC_GAPS.md`
+(theo `.claude/skills/qa-analyst/DOC_GAPS.template.md`), mỗi gap có ID `GAP-xx`.
+
+Kết thúc bằng gợi ý: feature đã đủ rõ để chuyển sang `qa-planner` (phân tích rủi ro) chưa.

package/core/skills/qc/qa-designer/e2e/journey.md

@@ -0,0 +1,41 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Test Case — E2E Journey
+
+Skill **tự chứa** để viết TC end-to-end: hành trình đầu→cuối xuyên nhiều màn/module
+(mở → nhập → submit → verify tạo + định tuyến + đồng bộ + hiển thị). Chỉ cần load file này.
+
+## Khi nào trigger
+- "viết E2E cho [feature]" / nở danh sách journey trong TEST_PLAN thành TC chi tiết đầu-cuối
+
+## Khi KHÔNG trigger
+- Test 1 màn/field → `functional/*` · test riêng 1 điểm tích hợp → `integration/*`
+
+---
+
+## Format file TC (bắt buộc)
+- Metadata **list**: Title · Feature · Priority · Status(Draft) · Author(AI) · Tags · **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx](DOC_GAPS.md)`.
+- **Test Data** dạng list (tài khoản/role, dữ liệu lớp/buổi…) · **Steps** `[Action]`/`[Verify]` xuyên các màn ·
+  **Expected** 1 bullet = chuỗi verify point (tạo thành công, mã đúng, định tuyến đúng, đồng bộ đúng, hiển thị danh sách).
+- ID journey `E2E-<FEATURE>-NN` · cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
+
+## Kỹ thuật áp dụng
+- **Use Case/Scenario:** mỗi journey = main + alternate + exception flow.
+- **Decision Table** để chọn journey đại diện cho mỗi nhánh của **trục bao phủ** (vd Đối tượng × Bộ phận xử lý × lớp/buổi × role × CRM).
+- **Verify points chung** (V1…Vn) áp cho mọi journey · **end-to-end data** (nhập màn A → hiện đúng màn B/DB/hệ thống ngoài).
+
+## Phase 1 — Clarify
+Lấy danh sách journey + trục bao phủ + verify points từ TEST_PLAN · mỗi journey: actor/role, tiền điều kiện
+(data + tài khoản), bước chính, kết quả/định tuyến kỳ vọng · journey nào phụ thuộc gap Blocker.
+
+## Phase 2 — Write
+Mỗi journey → 1 TC bám Format; Expected = chuỗi verify point; chuẩn bị tiền điều kiện & cleanup, mỗi journey độc lập.
+**Journey phụ thuộc gap vẫn viết + 🚫 Block: GAP-xx**, định tuyến ghi "dự kiến theo BR". Trace BR.
+
+## Output
+File TC e2e (hoặc nhóm E2E trong file feature) trong `docs/<project>/<feature>/`.
+In bảng `E2E-ID | Journey | Pri | Trace | Block` + bảng TC block. Bàn giao `qa-reviewer`.