ai-developer-skill-os 9.1.1 → 9.3.0

package/.agents/skills/qk-system-evolution/evals/scorecard.yaml

@@ -1,26 +1,26 @@
-name: qk-system-evolution-eval
-description: Đánh giá độ an toàn của quy trình nâng cấp System & Framework
-version: 9.1.0
-threshold: 90 # Việc nâng cấp framework mang rủi ro sập hệ thống rất cao
-
-metrics:
-  - id: rollback_safety
-    name: Cơ chế Rollback bắt buộc
-    description: Agent có thiết lập và ghi chép lại lệnh rollback trước khi nâng cấp không?
-    weight: 40
-    criteria:
-      - Phải yêu cầu/lưu lại Rollback command (git tag / version trước đó) trước khi sửa code (40đ)
-
-  - id: changelog_awareness
-    name: Phân tích Breaking Changes
-    description: Agent có đọc Changelog thay vì nhắm mắt upgrade không?
-    weight: 35
-    criteria:
-      - Quét và liệt kê các Breaking Changes từ Changelog/Migration Guide trước khi chạy (35đ)
-
-  - id: incremental_upgrade
-    name: Nâng cấp gia tăng (Incremental)
-    description: Có nâng cấp từng phần và chạy test xác minh thay vì Big-bang không?
-    weight: 25
-    criteria:
-      - Chạy test ngay sau khi nâng cấp 1 package thay vì update hàng loạt (25đ)
+name: qk-system-evolution-eval
+description: Đánh giá độ an toàn của quy trình nâng cấp System & Framework
+version: 9.1.0
+threshold: 90 # Việc nâng cấp framework mang rủi ro sập hệ thống rất cao
+
+metrics:
+  - id: rollback_safety
+    name: Cơ chế Rollback bắt buộc
+    description: Agent có thiết lập và ghi chép lại lệnh rollback trước khi nâng cấp không?
+    weight: 40
+    criteria:
+      - Phải yêu cầu/lưu lại Rollback command (git tag / version trước đó) trước khi sửa code (40đ)
+
+  - id: changelog_awareness
+    name: Phân tích Breaking Changes
+    description: Agent có đọc Changelog thay vì nhắm mắt upgrade không?
+    weight: 35
+    criteria:
+      - Quét và liệt kê các Breaking Changes từ Changelog/Migration Guide trước khi chạy (35đ)
+
+  - id: incremental_upgrade
+    name: Nâng cấp gia tăng (Incremental)
+    description: Có nâng cấp từng phần và chạy test xác minh thay vì Big-bang không?
+    weight: 25
+    criteria:
+      - Chạy test ngay sau khi nâng cấp 1 package thay vì update hàng loạt (25đ)

package/.agents/skills/qk-test-engineering/SKILL.md

@@ -1,9 +1,9 @@
----
+---
 # ── Identity ───────────────────────────────────────────────
 name: qk-test-engineering
-version: 9.1.0
-status: experimental
-description: "Công cụ quyết định chiến lược kiểm thử (Unit, Integration, E2E, Coverage, Regression, Mock)."
+version: 9.2.0
+status: stable
+description: "Thiết kế chiến lược kiểm thử toàn diện và viết bộ test tự động: Test Pyramid (Unit, Integration, E2E), Mocking strategy, Edge-case coverage, Regression testing. Dùng skill này khi user nhắc đến: viết test, test strategy, unit test, coverage, e2e, integration test, mock data, pytest, vitest, playwright — kể cả khi chỉ nói 'viết test cho module này'."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 # ── V9: Classification ─────────────────────────────────────
@@ -11,11 +11,10 @@ type: capability
 
 intent:
   - testing-strategy
-  - unit-test-strategy
-  - integration-test-strategy
-  - e2e-test-strategy
-  - mock-strategy
-  - test-coverage-planning
+  - unit-testing
+  - integration-testing
+  - e2e-testing
+  - test-automation
 
 complexity:
   level: high
@@ -25,11 +24,18 @@ complexity:
     has_external_dependency: true
     has_breaking_change: false
 
-triggers:
-  - "chiến lược test"
-  - "viết test"
-  - "mock data"
-  - "test coverage"
+triggers:
+  - "viết test"
+  - "test strategy"
+  - "unit test"
+  - "coverage"
+  - "e2e"
+  - "integration test"
+  - "mock data"
+  - "pytest"
+  - "vitest"
+  - "playwright"
+
 
 # ── V8: References ─────────────────────────────────────────
 workflow: feature-delivery
@@ -43,7 +49,8 @@ tools:
   - terminal
 
 related_skills:
-  - qk-engineering-standard
+  - qk-code-review
+  - qk-bug-resolution
 
 knowledge_scope:
   domain:
@@ -52,57 +59,24 @@ knowledge_scope:
     - unit-testing
     - integration-testing
     - e2e-testing
-    - visual-regression
   concepts:
     - test-pyramid
     - mock-strategy
+    - arrange-act-assert
   references:
     - architecture
-    - anti-patterns
-    - playwright
     - vitest
-    - storybook-testing
-
-decision_boundary:
-  owns:
-    - test pyramid
-    - coverage strategy
-    - regression planning
-  does_not_own:
-    - business logic implementation
-    - writing tests
-  conflicts_with: []
+    - pytest
+    - playwright
 
 # ── V8: Verification ───────────────────────────────────────
 verification:
   required: true
   strategy: feature
 
-lifecycle:
-  promotion_gate:
-    requirements:
-      tests:
-        minimum_pass_rate: 0.95
-      usage:
-        minimum_runs: 20
-      conflicts:
-        zero_boundary_violation: true
-      evidence:
-        required:
-          - evaluation_report
-          - usage_history
-          - boundary_audit
-  demotion_gate:
-    triggers:
-      - repeated_failure
-      - boundary_violation
-      - outdated_reference
-    action:
-      change_status: "stable -> experimental"
-
 selection:
-  priority: medium
-  confidence_threshold: 0.80
+  priority: high
+  confidence_threshold: 0.85
 
 examples: []
 learnings: []
@@ -112,414 +86,130 @@ execution_mode: deterministic
 cost: medium
 latency: medium
 risk: low
-side_effects: read_only
-produces: [report, test_plan]
-consumes: [user-description]
+side_effects: edit_files
+produces: [code, test_plan]
+consumes: [source-code, user-description]
 
 token_budget:
-  max_files_read: 5
+  max_files_read: 6
   max_lines_per_read: 150
-  max_shell_commands: 0
+  max_shell_commands: 3
   stop_early: true
 
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
 
-# qk-test-engineering — Test Engineering Strategist
+# qk-test-engineering — Automated Testing & Quality Architect
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
-## Memory Workflow
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Convention / Pattern (vd: chiến lược Test Pyramid, mock provider Vitest/Jest, boundary test).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern viết mock/stub mới hoặc chiến lược fixture dự án.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* File coverage nháp sinh ra trong quá trình chạy test.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Convention / Pattern (vd: chiến lược Test Pyramid, mock provider Vitest/Jest, boundary test).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern viết mock/stub mới hoặc chiến lược fixture dự án.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* File coverage nháp sinh ra trong quá trình chạy test.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern viết mock/stub mới hoặc chiến lược fixture dự án.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* File coverage nháp sinh ra trong quá trình chạy test.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Pattern viết mock/stub mới hoặc chiến lược fixture dự án.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* File coverage nháp sinh ra trong quá trình chạy test.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
----
----
-
-## Preconditions
-- [ ] Có code hoặc requirement rõ ràng cần kiểm thử.
+Chịu trách nhiệm thiết kế chiến lược kiểm thử cân bằng (Test Pyramid) và trực tiếp cài đặt các bộ test tự động đáng tin cậy: **Unit Tests nhanh & cô lập, Integration Tests kiểm chứng hợp đồng kết nối, và E2E Tests bảo vệ luồng nghiệp vụ sống còn.**
 
-## Scope
-- Đưa ra quyết định chọn loại test (Unit, Integration, E2E) theo Test Pyramid.
-- Thiết kế chiến lược Mock (Mocking vs Stubbing vs Faking).
-- Đánh giá Test Coverage hiện tại và đưa ra target.
-- Quyết định Regression analysis (những phần nào cần test lại khi file A thay đổi).
-- **Bắt buộc thiết kế test case cho ranh giới dữ liệu (Negative Testing / Boundary Testing) để đảm bảo tuân thủ R-SEC-04.**
-- Không tự động sinh test trừ khi user yêu cầu implement, skill này chủ yếu tư vấn architecture và strategy cho QA/Testing.
-
-## Non-Goals
-- ❌ Provide implementation outside of Testing Strategy scope
-- ❌ Override explicit user directives without explanation
-- ❌ Guess ambiguous requirements without asking
-
-## Priority Order
-
-| Priority | Task | Skip Threshold |
-|----------|------|----------------|
-| P1 | Core Testing Strategy analysis and decision making | Never |
-| P2 | Validation of existing patterns | Budget < 30% |
-| P3 | Detailed documentation generation | Budget < 50% |
-| P4 | Edge case exploration | Budget < 70% |
-
-## Workflow
-
-### Phase 1 — Context Loading
-**Steps:**
-1. Read existing configuration and requirements related to Testing Strategy.
-2. Check for missing preconditions.
-
-**Decision:**
-```
-IF context is clear
-  → Confidence: HIGH → go to Phase 2
-ELSE
-  → EXIT: BLOCKED — ask user
-```
+---
+
+## Preconditions
 
-### Phase 2 — Analysis & Strategy
-**Steps:**
-1. Analyze the current state against Testing Strategy best practices.
-2. Formulate strategy or audit report based on findings.
+Trước khi viết test, AI BẮT BUỘC xác nhận:
 
-**Decision:**
-```
-IF strategy/audit is complete
-  → Confidence: HIGH → go to Phase 3
-ELSE IF minor gaps exist
-  → Confidence: MEDIUM → proceed with assumptions noted
-```
+- [ ] Xác định Test Framework từ `DEV_PROFILE.md` hoặc manifest (Vitest, Jest, Pytest, Go `testing`, Playwright).
+- [ ] Xác định code mục tiêu cần test (function, class, API endpoint, hoặc user journey).
+- [ ] Xác định phụ thuộc ngoại vi (Database, External API, File system, Third-party service) để chọn phương án Mock phù hợp.
 
-### Phase 3 — Finalization
-**Steps:**
-1. Generate final report or configuration.
-2. Prepare handoff data for subsequent skills.
+*Nếu chưa có code mục tiêu và user không yêu cầu TDD (Test-Driven Development):*
+→ **EXIT: BLOCKED**
+→ Yêu cầu: "Vui lòng chỉ định hàm, module hoặc file cần viết test."
 
-## Confidence Model
+---
 
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | All preconditions met, context fully understood | Proceed directly |
-| MEDIUM | Some context missing but safe defaults exist | Proceed and note assumptions |
-| LOW | Core requirements missing | EXIT: BLOCKED |
+## Scope
 
-## Severity (for findings)
+✅ Skill này làm:
+- Thiết lập **Test Cases Matrix** bao phủ:
+  - **Happy path:** Dữ liệu hợp lệ, kết quả mong đợi.
+  - **Edge cases:** Giới hạn biên (0, -1, max int, chuỗi rỗng, mảng rỗng, ký tự đặc biệt UTF-8).
+  - **Error boundaries:** Ném lỗi đúng loại (Custom Error / HTTP Status) khi đầu vào sai.
+  - **Async / Timeout:** Xử lý promise reject, network delay.
+- Viết Unit Tests theo cấu trúc kinh điển **AAA (Arrange - Act - Assert)** hoặc **Given - When - Then**.
+- Viết Integration Tests kiểm chứng sự phối hợp giữa Service và Database (dùng in-memory DB hoặc Testcontainers).
+- Viết E2E Tests (Playwright) cho các User Flows quan trọng nhất (Sign up → Checkout → Payment).
+- Xây dựng Mocking Strategy đúng mực: Mock ở ranh giới hệ thống (HTTP client, Message queue), **không bao giờ mock implementation details nội bộ**.
+
+❌ Skill này KHÔNG làm:
+- Viết tests rỗng không có `expect` / `assert` chỉ để farm chỉ số coverage.
+- Mock quá mức khiến test luôn pass dù code thật bị hỏng (Tautological tests).
+- Viết E2E test cho mọi biến thể nhỏ (vi phạm kim tự tháp kiểm thử, gây chậm CI và flaky test).
 
-| Level | Definition |
-|-------|-----------|
-| CRITICAL | Severe violation of Testing Strategy principles |
-| HIGH | Significant risk or technical debt |
-| MEDIUM | Suboptimal pattern but functional |
-| LOW | Minor style or documentation issue |
+---
 
-## Evidence Format
+## Execution Steps
 
+### Step 1 — Phân tầng Kiểm thử (Pyramid Placement)
 ```
-[SEVERITY] Context/File
-Issue:      [what was found]
-Confidence: HIGH
-Recommendation: [actionable advice]
+Quyết định tầng test phù hợp:
+  - Pure function, domain logic, utils       → 70% Unit Tests (Chạy < 10ms/test).
+  - Database queries, API routes, middleware → 20% Integration Tests (Mock external API).
+  - Critical checkout / login flow           → 10% E2E Tests (Playwright / Cypress).
 ```
 
-## Retry Policy
+### Step 2 — Lập Ma trận Kịch bản (Test Scenario Matrix)
 ```
-Task fails due to missing context
-  └─ Ask user for clarification
-       ├─ Provided → Retry Phase 1
-       └─ Not provided → EXIT: BLOCKED
+Ví dụ với hàm transferMoney(fromId, toId, amount):
+  1. TC-01 (Happy): Chuyển tiền thành công khi số dư đủ, trừ tài khoản A, cộng tài khoản B.
+  2. TC-02 (Edge): Chuyển đúng bằng số dư hiện có (số dư về 0).
+  3. TC-03 (Error): Chuyển số tiền âm hoặc = 0 -> Ném ValidationError.
+  4. TC-04 (Error): Số dư không đủ -> Ném InsufficientFundsError.
+  5. TC-05 (Edge): fromId trùng toId -> Ném SelfTransferError.
+  6. TC-06 (Concur): 2 giao dịch đồng thời -> Xử lý lock/transaction an toàn.
 ```
 
-## Escalation Rules
+### Step 3 — Viết Code Kiểm thử (Test Implementation)
+```
+Tuân thủ cấu trúc AAA:
+  // 1. Arrange: Chuẩn bị dữ liệu mẫu và mock
+  const user = createMockUser({ balance: 100 });
+  
+  // 2. Act: Gọi hàm cần test
+  const result = await transferMoney(user.id, recipient.id, 50);
+  
+  // 3. Assert: Kiểm tra kết quả
+  expect(result.status).toBe('SUCCESS');
+  expect(user.balance).toBe(50);
+```
 
+### Step 4 — Verification & Chạy Test Thực Tế
 ```
-BLOCKED: Missing critical context for Testing Strategy
-Missing:
-  - [Specific requirement]
-Questions:
-  1. Bạn có thể cung cấp thêm thông tin về yêu cầu này không?
-  2. Mục tiêu chính của bạn là gì?
-Recommended Assumptions: none
+Actions:
+  - Chạy lệnh test thật qua terminal (`npm test -- run`, `pytest -v`, `go test ./...`).
+  - Đảm bảo toàn bộ test cases đều PASS (Màu xanh).
+  - Đảm bảo test chạy độc lập (Isolated), không phụ thuộc vào thứ tự thực thi.
 ```
 
-## Handoff Contract
+---
 
-### Consumes
-```json
-{
-  "from": "user or qk-orchestrator",
-  "required_fields": ["context"],
-  "optional_fields": ["existing_config"]
-}
-```
+## Prompt Template
 
-### Produces
-```json
-{
-  "to": "user or downstream skill",
-  "output_fields": ["strategy_report", "exit_code"]
-}
 ```
+Target:       [File hoặc Function cần viết test: vd: src/services/PaymentService.ts]
+Framework:    [Vitest / Jest / Pytest / Playwright]
+Level:        [Unit / Integration / E2E]
+Phụ thuộc:    [Cần mock Stripe API, PostgreSQL DB]
+Yêu cầu:      [Cover các trường hợp lỗi mạng, thẻ hết hạn, concurrency]
+```
+
+### Ví dụ theo Stack:
 
-## Exit Codes
+**Vitest (Unit Test cho Business Logic)**
+```
+Target:       calculateDiscount(cart, coupon)
+Framework:    Vitest + TypeScript
+Yêu cầu:      Test giảm giá phần trăm, giảm giá cố định, mã hết hạn, coupon vượt quá tổng giá trị đơn hàng.
+```
+→ AI tạo: `tests/unit/calculateDiscount.test.ts` với đầy đủ 6 test cases, kiểm tra boundary condition `Math.max(0, total - discount)`.
 
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Testing Strategy task completed successfully | Strategy/audit generated |
-| PARTIAL | Task completed with assumptions | Medium confidence |
-| BLOCKED | Missing context | Cannot proceed |
-| FAILED | Critical conflict or error | Unresolvable constraint |
+**Pytest (Integration Test cho FastAPI Endpoint)**
+```
+Target:       POST /api/v1/items
+Framework:    Pytest + httpx AsyncClient
+Yêu cầu:      Test tạo item thành công (201), validate body thiếu trường bắt buộc (422), unauthenticated (401).
+```
+→ AI tạo: `tests/test_items_api.py`, sử dụng pytest fixture cho test DB session và test client.