openmoneta-dev-kit 1.9.2 → 1.10.1

package/README.md

@@ -54,7 +54,7 @@ bash ~/OpenMoneta-Dev-Kit/install.sh
 
 ## Có gì trong này?
 
-- **9 skills** (3 core + 1 core conditional + 5 on-demand) — phân tích yêu cầu, thiết kế module, plan, safe push, test, security
+- **10 skills** (4 core + 1 core conditional + 5 on-demand) — phân tích yêu cầu, thiết kế module, plan, systematic debugging, safe push, test, security
 - **4 sub-agents** — 1 core + 3 on-demand (security-auditor, qa-autonomous, ui-tester)
 - **4 hooks + plugin** — enforce token-aware reading, adaptive plan scope
 - **Token Routing** — bảng map keyword → module giúp AI giảm 70-90% token đọc

package/VERSION

@@ -1 +1 @@
-1.9.2
+1.10.1

package/agents/qa-autonomous.md

@@ -1,6 +1,6 @@
 ---
 name: qa-autonomous
-description: "ON-DEMAND ONLY: chỉ delegate khi user explicitly yêu cầu viết test (vd 'viết unit test cho service X', 'add integration test cho payment flow'). KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ Bước 6 Test khỏi core process). Tự viết unit/integration test, tự chạy, debug, fix loop đến khi xanh. Chỉ báo cáo khi PASS hoặc khi gặp lỗi không fix được sau 3 lần thử."
+description: "ON-DEMAND ONLY: delegate khi user explicitly yêu cầu viết test (vd 'viết unit test cho service X', 'add integration test cho payment flow'). KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 Bạn là **qa-autonomous** — kỹ sư QA tự chủ của hệ thống OpenMoneta Dev Kit.

package/agents/requirement-analyst.md

@@ -1,6 +1,6 @@
 ---
 name: requirement-analyst
-description: Phân tích yêu cầu phức tạp, đọc nhiều tài liệu/codebase, sinh giả thuyết, edge case, rủi ro và đề xuất câu hỏi cho user. Dùng proactively khi user request mơ hồ, lớn (>5 file ảnh hưởng), hoặc cần explore rộng để hiểu impact. Không code.
+description: "Dùng proactively khi user request mơ hồ, lớn (>5 file ảnh hưởng), hoặc cần explore rộng codebase/tài liệu để hiểu impact trước khi lập plan. Read-only, không code."
 ---
 
 Bạn là **requirement-analyst** — chuyên gia phân tích yêu cầu của hệ thống OpenMoneta Dev Kit.

package/agents/security-auditor.md

@@ -1,6 +1,6 @@
 ---
 name: security-auditor
-description: "ON-DEMAND ONLY: chỉ delegate khi user explicitly yêu cầu security audit, HOẶC khi parent agent xử lý task chạm auth/payment/PII/admin/permission và muốn audit độc lập. KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ Bước 5 Security khỏi core process). Audit OWASP Top 10 độc lập, scan secrets, kiểm tra dependency CVE. Read-only, không edit."
+description: "ON-DEMAND ONLY: delegate khi user explicitly yêu cầu security audit (OWASP, scan secrets, dependency CVE), HOẶC khi task chạm auth/payment/PII/admin/permission và cần audit độc lập read-only. KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 Bạn là **security-auditor** — chuyên gia bảo mật của hệ thống OpenMoneta Dev Kit.

package/agents/ui-tester.md

@@ -1,6 +1,6 @@
 ---
 name: ui-tester
-description: "ON-DEMAND ONLY: chỉ delegate khi user explicitly yêu cầu UI test (vd 'test UI mobile/tablet/desktop, fix CSS lỗi rồi retest', 'visual regression cho component X'). KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã xóa hook ui-checkpoint). Chuyên Playwright UI/UX testing với multi-viewport, screenshot, loop fix. Tự chạy test - đọc lỗi - fix CSS/component - retest. Hard limit 5 vòng trước khi escalate user."
+description: "ON-DEMAND ONLY: delegate khi user explicitly yêu cầu UI test (vd 'test UI mobile/tablet/desktop, fix CSS lỗi rồi retest', 'visual regression cho component X'). KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 Bạn là **ui-tester** — chuyên gia UI/UX testing của hệ thống OpenMoneta Dev Kit.

package/hooks/inject-process-context.sh

@@ -48,6 +48,9 @@ SUMMARY='# OpenMoneta Dev Kit v1.7.0 — Quy trình 6 bước (Adaptive Planning
 
 ## Skill core conditional
 `safe-push` — bắt buộc khi user yêu cầu push/đẩy code để tránh đè code người khác trong repo nhiều contributor.
+
+## Skill core auto-trigger
+`systematic-debugging` — TỰ kích hoạt khi gặp bug/test fail/lỗi build/hành vi lạ. Iron Law: KHÔNG SỬA KHI CHƯA TÌM RA NGUYÊN NHÂN GỐC. 4 phase (root cause → pattern → hypothesis → fix+test); 3+ fix fail = nghi ngờ kiến trúc, hỏi user.
 '
 
 # === Auto-check update (cache 24h) ===

package/opencode/agents/qa-autonomous.md

@@ -1,5 +1,5 @@
 ---
-description: ON-DEMAND ONLY. Viết unit/integration test khi user yêu cầu, tự chạy test, debug, fix loop đến khi pass hoặc gặp blocker rõ.
+description: ON-DEMAND ONLY. Dùng khi user yêu cầu viết unit/integration test.
 mode: subagent
 permission:
   edit: ask

package/opencode/agents/requirement-analyst.md

@@ -1,5 +1,5 @@
 ---
-description: Phân tích yêu cầu phức tạp, đọc tài liệu/codebase, sinh giả thuyết, edge case, rủi ro và đề xuất câu hỏi cho user. Không code.
+description: Dùng khi user request mơ hồ/lớn hoặc cần explore rộng codebase/tài liệu để hiểu impact trước khi lập plan. Không code.
 mode: subagent
 permission:
   edit: deny

package/opencode/agents/security-auditor.md

@@ -1,5 +1,5 @@
 ---
-description: ON-DEMAND ONLY. Audit OWASP Top 10, scan secrets, kiểm tra dependency CVE. Read-only, không edit.
+description: ON-DEMAND ONLY. Dùng khi user yêu cầu security audit (OWASP, scan secrets, dependency CVE) hoặc task chạm auth/payment/PII. Read-only.
 mode: subagent
 permission:
   edit: deny

package/opencode/agents/ui-tester.md

@@ -1,5 +1,5 @@
 ---
-description: ON-DEMAND ONLY. Playwright UI/UX testing multi-viewport, screenshot, loop fix CSS/component khi user yêu cầu UI test.
+description: ON-DEMAND ONLY. Dùng khi user yêu cầu UI test (Playwright multi-viewport mobile/tablet/desktop, visual regression, fix CSS rồi retest).
 mode: subagent
 permission:
   edit: ask

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmoneta-dev-kit",
-  "version": "1.9.2",
+  "version": "1.10.1",
   "description": "OpenMoneta Dev Kit — Biến Cursor IDE / OpenCode thành team developer hoàn chỉnh với quy trình 6 bước, adaptive planning, hooks enforcement, và token-aware doc routing",
   "keywords": [
     "cursor",

package/skills/auth-bypass-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: auth-bypass-testing
-description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu bypass auth cho test (vd 'thêm test bypass cho Playwright login', 'setup test user pattern'). KHÔNG tự trigger trong quy trình bình thường. Triển khai Test Bypass Flag an toàn để Playwright test có thể bypass OAuth/login mà không phá bảo mật production. 6 layer defense (env guard, IP whitelist 127.0.0.1, token rotation, double header, audit log, CI/CD guard)."
+description: "ON-DEMAND ONLY: dùng khi user explicitly yêu cầu bypass auth/OAuth/login cho test (vd 'thêm test bypass cho Playwright login', 'setup test user pattern'). KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 # Auth Bypass Testing — An toàn cho production

package/skills/automated-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: automated-testing
-description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu E2E/UI test với Playwright (vd 'viết Playwright test cho checkout flow', 'chạy E2E mobile'). KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ Bước 6 Test khỏi core process). Cài và dùng Playwright multi-viewport (mobile/tablet/desktop), screenshot, fixture cho auth state. Có script install-playwright.sh để AI tự cài."
+description: "ON-DEMAND ONLY: dùng khi user explicitly yêu cầu E2E/UI test bằng Playwright (vd 'viết Playwright test cho checkout flow', 'chạy E2E mobile', multi-viewport mobile/tablet/desktop). KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 # Automated Testing với Playwright

package/skills/module-architect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: module-architect
-description: Quy tắc chia module theo SRP (1 module = 1 trách nhiệm, có README riêng) + workflow update README sau khi sửa code. KHÔNG đếm dòng để tách. Dùng ở Bước 2 (thiết kế) và Bước 5 (update doc) của quy trình 6 bước.
+description: "Dùng khi thiết kế cấu trúc cho code mới, quyết định tạo hay tách module, hoặc khi cần sync README module sau khi sửa code."
 ---
 
 # Module Architect
@@ -12,6 +12,35 @@ Skill này phụ trách 2 trách nhiệm của quy trình 6 bước:
 
 Mục tiêu chung: cấu trúc code dễ navigate cho cả người và AI, tiết kiệm token khi đọc.
 
+## Iron Law
+
+```
+1 MODULE = 1 TRÁCH NHIỆM. CẤM NHÉT CODE MỚI VÀO utils/common/shared. TÁCH THEO TRÁCH NHIỆM, KHÔNG THEO SỐ DÒNG.
+```
+
+**Vi phạm chữ (letter) của luật này = vi phạm tinh thần (spirit).** Không có ngoại lệ "cho vào utils cho tiện", "nhỏ mà", hay "để README update sau".
+
+## Bảng Rationalization (cái cớ → sự thật)
+
+| Cái cớ | Sự thật |
+|---|---|
+| "Cho vào `utils/`/`common/`/`shared/` cho tiện" | Đó là nơi code đi chết. Feature có concept riêng → module riêng theo concept business. |
+| "File dài quá rồi, tách theo số dòng đi" | Tách theo TRÁCH NHIỆM, không theo dòng. 1 file 800 dòng làm 1 việc = OK; 200 dòng làm 4 việc = tách. |
+| "Feature nhỏ, khỏi cần module riêng" | Mỗi feature có concept business gần như luôn xứng đáng module riêng để cô lập sửa code. |
+| "Đặt tên `core`/`lib`/`misc` cho nhanh" | Tên generic = mơ hồ trách nhiệm. Đặt tên theo concept (`auth`, `billing`, `notifications`...). |
+| "README để update sau" | Defer README = doc stale, session sau AI đọc lệch. Update ngay ở Bước 5. |
+| "Module này thêm 1 việc nữa cũng được" | Thêm trách nhiệm thứ 2 = vi phạm SRP → tách ra module mới. |
+
+## Red Flags — DỪNG
+
+- Đang định tạo/đặt code vào `utils/`, `common/`, `helpers/`, `shared/`.
+- Đang định đặt tên module `core`, `lib`, `misc`, `manager`, `util`.
+- Đang quyết định tách/không tách dựa trên **số dòng** thay vì số trách nhiệm.
+- Đang định viết "TODO: update README later" hoặc bỏ qua sync README ở Bước 5.
+- Mô tả trách nhiệm module phải dùng chữ "và".
+
+**Tất cả đều nghĩa là: DỪNG, quay lại nguyên tắc SRP + trigger "Khi nào TẠO module mới".**
+
 ## Phần 1 — Thiết kế module (Bước 2)
 
 ### Nguyên tắc cốt lõi

package/skills/plan-writer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-writer
-description: Adaptive planning cho quy trình 6 bước. Task nhỏ có thể không cần plan. Task lớn/rủi ro phải tạo repo plan trong plans/YYYY-MM-DD-<slug>.md với Status: Draft, trình user review, chỉ triển khai sau khi user approve và đổi Status: In Progress.
+description: "Dùng khi cần quyết định một task có cần repo plan hay không, hoặc khi task lớn/rủi ro/mơ hồ, đụng nhiều file, đổi public API, hay chạm vùng nhạy cảm (auth/payment/db/migration/deploy) cần plan được user review trước khi code."
 ---
 
 # Plan Writer
@@ -14,6 +14,14 @@ description: Adaptive planning cho quy trình 6 bước. Task nhỏ có thể kh
 
 Hook `verify-completion` Check 9 sẽ CHẶN session kết thúc nếu plan không có section "## Hiểu yêu cầu" (audit trail clarify).
 
+## Iron Law
+
+```
+KHÔNG TỰ APPROVE PLAN. TASK RỦI RO KHÔNG CODE KHI PLAN CHƯA Ở TRẠNG THÁI IN PROGRESS.
+```
+
+**Vi phạm chữ (letter) của luật này = vi phạm tinh thần (spirit).** Không tự tạo plan rồi tự đổi `In Progress`; phải có user approve thật.
+
 ## Naming convention
 
 ```
@@ -65,6 +73,27 @@ Khi tạo plan:
 
 Không được tự tạo plan rồi tự approve.
 
+## Bảng Rationalization (cái cớ → sự thật)
+
+| Cái cớ | Sự thật |
+|---|---|
+| "Task này nhỏ mà, code luôn" | Chạm auth/payment/db/migration/deploy hoặc >2 file → vẫn phải plan, dù thấy "nhỏ". |
+| "Tạo plan rồi tự đổi In Progress cho nhanh" | Tự approve = bỏ review gate. Phải hỏi user thật bằng `AskQuestion`. |
+| "User chắc sẽ approve thôi" | "Chắc" ≠ approve. Chờ user trả lời rồi mới đổi Status. |
+| "Vừa code vừa nghĩ plan sau" | Plan trước để user sửa hướng TRƯỚC khi tốn công code. |
+| "Phát hiện cần thêm file, cứ sửa luôn" | File ngoài `## Files ảnh hưởng` → update plan trước, rồi mới sửa. |
+| "Yêu cầu mơ hồ nhưng tôi đoán ý user được" | Mơ hồ = phải hỏi clarify, ghi vào `## Hiểu yêu cầu`. |
+
+## Red Flags — DỪNG
+
+- Định edit file code khi plan còn `Draft`.
+- Định tự đổi Status `Draft` → `In Progress` khi chưa có user approve.
+- Định sửa file không nằm trong `## Files ảnh hưởng`.
+- Định bỏ qua plan cho task chạm auth/payment/db/migration/deploy.
+- Section `## Hiểu yêu cầu` trống mà vẫn định code.
+
+**Tất cả đều nghĩa là: DỪNG, quay lại review gate.**
+
 ## Template chuẩn (5 sections)
 
 ```markdown

package/skills/requirement-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: requirement-analysis
-description: Phân tích yêu cầu user, đọc TOKEN-AWARE docs/INDEX.md (hook enforced), sinh giả thuyết/edge case/rủi ro và đặt câu hỏi critical để làm rõ yêu cầu, phân tích mọi trường hợp có thể xảy ra, phản biện và đề xuất phương án tối ưu hơn nếu có TRƯỚC khi lập plan. Output câu hỏi/trả lời sẽ ghi vào plan section "Hiểu yêu cầu" (verify-completion Check 9 enforce).
+description: "Dùng khi bắt đầu phân tích một yêu cầu trước khi thiết kế hoặc lập plan, đặc biệt khi yêu cầu mơ hồ, lớn, có nhiều cách hiểu, hoặc cần làm rõ / đặt câu hỏi clarify trước khi code."
 ---
 
 # Phân tích yêu cầu

package/skills/safe-push/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: safe-push
-description: "CORE CONDITIONAL: kích hoạt khi user yêu cầu commit + push / push code / đẩy code / merge lên remote / lên main. Đảm bảo pre-push sync + conflict resolution + safe fast-forward push, không đè code người khác. KHÔNG dùng --force trên shared branch."
+description: "CORE CONDITIONAL: dùng khi user yêu cầu commit + push / push code / đẩy code / đẩy lên remote / merge lên main, nhất là trên repo nhiều contributor có nguy cơ đè code người khác."
 ---
 
 # Safe Push (CORE CONDITIONAL)
@@ -17,6 +17,14 @@ Chỉ kích hoạt khi user yêu cầu rõ:
 
 Không kích hoạt cho task code bình thường chưa có yêu cầu push.
 
+## Iron Law
+
+```
+KHÔNG FORCE-PUSH SHARED BRANCH. LUÔN SYNC REMOTE NGAY TRƯỚC PUSH.
+```
+
+**Vi phạm chữ (letter) của luật này = vi phạm tinh thần (spirit).** Không có ngoại lệ "branch của mình", "đang gấp", hay "chắc không ai đụng".
+
 ## Mục tiêu
 
 Đảm bảo trước khi `git push`, local branch đã đồng bộ với remote mới nhất để không đè code người khác trong repo có nhiều contributor.
@@ -39,6 +47,27 @@ Bước 6 bắt buộc `fetch + rebase` ngay trước push. Nếu remote có com
 4. **Push thường trước**: dùng `git push` fast-forward. Nếu rejected do remote mới, quay lại fetch/rebase. Loop tối đa 3 lần.
 5. **Không deploy trong skill này**: CI/CD/deploy là pipeline ngoài scope trừ khi user yêu cầu skill riêng.
 
+## Bảng Rationalization (cái cớ → sự thật)
+
+| Cái cớ | Sự thật |
+|---|---|
+| "Đang gấp, push thẳng cho nhanh" | Bỏ fetch/rebase = nguy cơ đè commit người khác. Sync chỉ mất vài giây. |
+| "Branch của mình, force cho gọn" | Branch cá nhân có thể `--force-with-lease` khi user yêu cầu; shared branch thì TUYỆT ĐỐI không. |
+| "Remote chắc không có gì mới" | "Chắc" ≠ bằng chứng. `git fetch` để biết chắc. |
+| "Conflict nhỏ, tự chọn ours/theirs cho nhanh" | Conflict code logic phải hỏi user; tự chọn = mất code người khác. |
+| "Rebase xong khỏi cần test lại" | Rebase đổi ngữ cảnh code, phải verify tối thiểu lại trước push. |
+| "Push rejected thì cứ -f là xong" | `-f` trên shared branch xóa commit người khác. Quay lại fetch/rebase. |
+
+## Red Flags — DỪNG
+
+- Định gõ `git push --force` / `git push -f` lên `main`/`master`/`develop`/`staging`/`production`.
+- Định push mà CHƯA `git fetch` trong chính lần này.
+- Định tự resolve conflict file code (`*.ts`, `*.py`, ...) mà không hỏi user.
+- Định bỏ verify sau rebase.
+- Đang nghĩ "chắc remote không có gì mới".
+
+**Tất cả đều nghĩa là: DỪNG, quay lại Workflow từ bước fetch/rebase.**
+
 ## Workflow 7 bước
 
 ### 1. Pre-flight branch

package/skills/security-checklist/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-checklist
-description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu security audit/review (vd 'audit security login flow', 'check OWASP cho API /payment'), HOẶC task có chạm auth/payment/PII và bạn muốn tự kiểm tra trước commit. KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ Bước 5 Security khỏi core process)."
+description: "ON-DEMAND ONLY: dùng khi user explicitly yêu cầu security audit/review (vd 'audit security login flow', 'check OWASP cho API /payment', scan secrets), HOẶC khi task chạm auth/payment/PII và muốn tự kiểm tra trước commit. KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 # Security Checklist (ON-DEMAND)

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: systematic-debugging
+description: "Dùng khi gặp bug, test fail, lỗi build, lỗi runtime, hoặc hành vi bất thường, trước khi đề xuất hoặc viết bất kỳ fix nào."
+---
+
+# Systematic Debugging (Core)
+
+Skill này **tự kích hoạt** khi bạn gặp bug / test fail / lỗi build / hành vi lạ. Không cần user yêu cầu.
+
+## Overview
+
+Fix đoán mò tốn thời gian và đẻ ra bug mới. Vá triệu chứng che mất nguyên nhân thật.
+
+**Nguyên tắc cốt lõi**: LUÔN tìm nguyên nhân gốc TRƯỚC khi fix. Vá triệu chứng = thất bại.
+
+**Vi phạm chữ (letter) của quy trình này = vi phạm tinh thần (spirit) của nó.** Không có ngoại lệ "đúng tinh thần nên bỏ bước".
+
+## Iron Law
+
+```
+KHÔNG SỬA KHI CHƯA TÌM RA NGUYÊN NHÂN GỐC
+```
+
+Chưa hoàn thành Phase 1 thì KHÔNG được đề xuất fix.
+
+## Khi nào dùng
+
+Mọi sự cố kỹ thuật: test fail, bug production, hành vi lạ, lỗi performance, lỗi build, lỗi tích hợp.
+
+**Đặc biệt khi**:
+- Đang gấp / khẩn cấp (lúc này đoán mò càng hấp dẫn).
+- "Chỉ một fix nhanh thôi" nghe có vẻ hiển nhiên.
+- Đã thử vài fix mà chưa được.
+- Fix trước không hiệu quả.
+- Bạn chưa hiểu rõ vấn đề.
+
+**KHÔNG bỏ qua khi**:
+- Bug "có vẻ đơn giản" (bug đơn giản vẫn có nguyên nhân gốc).
+- Đang vội (vội mà đoán mò càng phải làm lại).
+
+## Quy trình 4 Phase
+
+Phải hoàn thành phase này mới sang phase sau.
+
+### Phase 1 — Tìm nguyên nhân gốc (TRƯỚC mọi fix)
+
+1. **Đọc kỹ thông báo lỗi**: đọc hết stack trace, ghi rõ dòng/file/error code. Lỗi thường chứa sẵn lời giải.
+2. **Tái hiện ổn định**: trigger lại được không? Các bước chính xác? Mỗi lần đều xảy ra? Không tái hiện được → thu thập thêm dữ liệu, KHÔNG đoán.
+3. **Soi thay đổi gần đây**: `git diff`, commit mới, dependency/config mới, khác biệt môi trường.
+4. **Thu thập bằng chứng ở từng ranh giới component** (với hệ multi-layer: API → service → DB): log dữ liệu vào/ra mỗi component, kiểm tra config/env truyền qua. Chạy 1 lần để thấy lỗi vỡ Ở ĐÂU, rồi mới đào component đó.
+5. **Lần ngược dòng dữ liệu**: giá trị sai bắt nguồn từ đâu? Cái gì gọi hàm này với giá trị sai? Lần lên tận nguồn. **Fix tại nguồn, không fix tại triệu chứng.**
+
+### Phase 2 — Phân tích pattern
+
+1. **Tìm ví dụ chạy đúng**: đoạn code tương tự đang hoạt động tốt trong cùng codebase.
+2. **Đối chiếu reference đầy đủ**: nếu đang theo 1 pattern/lib, đọc HẾT reference, không đọc lướt.
+3. **Liệt kê mọi khác biệt** giữa chỗ đúng và chỗ hỏng, dù nhỏ. Đừng cho rằng "cái đó không liên quan đâu".
+4. **Hiểu dependency**: cần component/config/env gì? Giả định gì?
+
+### Phase 3 — Giả thuyết & kiểm chứng
+
+1. **Một giả thuyết duy nhất**: phát biểu rõ "Tôi nghĩ X là nguyên nhân gốc vì Y". Viết ra.
+2. **Test tối thiểu**: thay đổi NHỎ NHẤT có thể để kiểm chứng. Một biến tại một thời điểm. KHÔNG sửa nhiều thứ cùng lúc.
+3. **Xác nhận rồi mới đi tiếp**: đúng → Phase 4. Sai → lập giả thuyết MỚI, KHÔNG chồng thêm fix.
+4. **Khi không biết**: nói thẳng "Tôi chưa hiểu X", hỏi user / research thêm. Không giả vờ hiểu.
+
+### Phase 4 — Triển khai fix
+
+1. **Tạo test reproduce bug TRƯỚC khi fix** (dùng skill `test-strategy` nếu cần TDD).
+2. **Một fix duy nhất** đúng nguyên nhân gốc. Không "tiện tay" sửa thứ khác, không gộp refactor.
+3. **Verify**: test pass chưa? Có làm vỡ test khác không? Bug đã hết thật chưa? (theo nguyên tắc evidence-before-claims).
+4. **Nếu fix không hiệu quả**: DỪNG. Đếm số fix đã thử. <3 → quay lại Phase 1 với thông tin mới. **≥3 → nghi ngờ kiến trúc (xem dưới).**
+
+### Luật 3 lần — nghi ngờ kiến trúc
+
+Sau **3+ fix thất bại**, đây KHÔNG phải giả thuyết sai mà là **kiến trúc sai**. Dấu hiệu:
+- Mỗi fix lại lòi ra vấn đề shared-state/coupling ở chỗ khác.
+- Fix nào cũng đòi "refactor lớn".
+- Fix chỗ này đẻ triệu chứng chỗ kia.
+
+→ **DỪNG, hỏi user** trước khi thử fix thứ 4: pattern này có sai từ gốc không? Có nên đổi kiến trúc thay vì vá tiếp không?
+
+## Bảng Rationalization (cái cớ → sự thật)
+
+| Cái cớ | Sự thật |
+|---|---|
+| "Bug này đơn giản, khỏi cần quy trình" | Bug đơn giản vẫn có nguyên nhân gốc. Quy trình chạy nhanh với bug đơn giản. |
+| "Đang gấp, không có thời gian điều tra" | Debug có hệ thống NHANH HƠN đoán-thử-lại lòng vòng. |
+| "Thử fix này trước đã, điều tra sau" | Fix đầu tiên định hình hướng. Làm đúng từ đầu. |
+| "Để fix xong rồi viết test sau" | Fix không test không bền. Test trước mới chứng minh. |
+| "Sửa nhiều thứ một lúc cho nhanh" | Không cô lập được cái nào hiệu quả. Đẻ bug mới. |
+| "Tôi thấy lỗi rồi, fix luôn" | Thấy triệu chứng ≠ hiểu nguyên nhân gốc. |
+| "Thêm một fix nữa thôi" (sau 2+ lần fail) | 3+ fail = vấn đề kiến trúc. Nghi ngờ pattern, đừng fix tiếp. |
+| "Reference dài quá, tôi tự suy theo pattern" | Hiểu một nửa = chắc chắn có bug. Đọc hết. |
+
+## Red Flags — DỪNG và quay lại Phase 1
+
+Nếu bắt gặp mình đang nghĩ:
+- "Fix tạm đã, điều tra sau."
+- "Cứ thử đổi X xem sao."
+- "Đổi nhiều chỗ rồi chạy test luôn."
+- "Bỏ test, tôi verify tay."
+- "Chắc là do X, fix X thôi."
+- "Chưa hiểu hẳn nhưng cái này có thể chạy."
+- "Thử thêm một fix nữa" (đã fail 2+ lần).
+- Mỗi fix lại lòi vấn đề ở chỗ khác.
+
+**Tất cả đều nghĩa là: DỪNG, quay lại Phase 1.** Nếu đã 3+ fix fail → nghi ngờ kiến trúc, hỏi user.
+
+## Quick Reference
+
+| Phase | Hoạt động chính | Tiêu chí xong |
+|---|---|---|
+| 1. Nguyên nhân gốc | Đọc lỗi, tái hiện, soi diff, thu bằng chứng, lần ngược dòng | Hiểu CÁI GÌ và TẠI SAO |
+| 2. Pattern | Tìm chỗ chạy đúng, đối chiếu | Liệt kê được khác biệt |
+| 3. Giả thuyết | 1 giả thuyết, test tối thiểu | Xác nhận hoặc giả thuyết mới |
+| 4. Fix | Tạo test, fix gốc, verify | Bug hết, test pass |
+
+## Liên quan
+
+- `test-strategy` — viết test reproduce bug ở Phase 4 (khi cần TDD-first).
+- `plan-writer` — nếu fix biến thành refactor lớn/đổi kiến trúc → dừng, tạo plan.

package/skills/test-strategy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-strategy
-description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu viết test (vd 'viết unit test cho X', 'add E2E cho login flow'), HOẶC khi bạn (AI) cần TDD-first cho bug fix khó. KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ Bước 6 Test khỏi core process). Phân tầng test: Unit ~70%, Integration ~20%, E2E ~10% với tools mặc định theo stack (Vitest/Jest/Pytest/Go test)."
+description: "ON-DEMAND ONLY: dùng khi user explicitly yêu cầu viết / phân tầng test (vd 'viết unit test cho X', 'add E2E cho login flow', unit/integration/E2E), HOẶC khi cần TDD-first cho một bug fix khó. KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 # Test Strategy

package/skills/ui-test-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ui-test-loop
-description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu UI test loop (vd 'test UI mobile + tablet + desktop, fix lỗi rồi retest', 'visual regression test cho component X'). KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ hook ui-checkpoint). Workflow loop test-fix-retest cho UI/UX bằng Playwright. Hard limit 5 vòng trước khi escalate user."
+description: "ON-DEMAND ONLY: dùng khi user explicitly yêu cầu UI test loop (vd 'test UI mobile + tablet + desktop, fix lỗi rồi retest', 'visual regression test cho component X'). KHÔNG tự trigger trong quy trình bình thường."
 ---
 
 # UI Test Loop với Checkpoint