ai-developer-skill-os 9.1.1 → 9.3.0

package/.agents/skills/qk-project-memory/SKILL.md

@@ -1,9 +1,9 @@
 ---
 # ── Identity ───────────────────────────────────────────────
 name: qk-project-memory
-version: 9.1.0
+version: 9.2.0
 status: stable
-description: "Quản trị Tri thức và Bộ nhớ dự án V1 (Local Private Mode) — Quản lý tại .ai-local/ như source code: tự động khởi tạo, bảo mật gitignore, có thể review, cập nhật và luôn có con người phê duyệt."
+description: "Quản trị Tri thức và Bộ nhớ dự án V1 (Local Private Mode) — Quản lý tại .ai-local/ như source code: tự động khởi tạo, bảo mật gitignore, có thể review, cập nhật và luôn có con người phê duyệt. Dùng skill này khi user nhắc đến: lưu context, project memory, ghi nhớ, /learn, lưu vào bộ nhớ, nhớ lại, tìm lại fact, lưu tri thức dự án — kể cả khi chỉ nói 'nhớ lại lỗi này để sau không mắc lại'."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 # ── V9: Classification ─────────────────────────────────────
@@ -24,11 +24,13 @@ complexity:
 
 triggers:
   - "lưu context"
-  - "nhớ lại"
   - "project memory"
+  - "ghi nhớ"
+  - "/learn"
   - "lưu vào bộ nhớ"
+  - "nhớ lại"
   - "tìm lại fact"
-  - "/learn"
+  - "lưu tri thức dự án"
 
 # ── V9: References ─────────────────────────────────────────
 workflow: documentation
@@ -42,19 +44,19 @@ tools:
 
 related_skills:
   - qk-context-loader
-  - qk-engineering-standard
+  - qk-docs
 
 knowledge_scope:
   owns:
-  - project-facts
-  - verified-context
-  - patterns
-  - hard-bugs
+    - project-facts
+    - verified-context
+    - patterns
+    - hard-bugs
   references:
-  - architecture
-  - convention
-  - pattern
-  - hard-bug
+    - architecture
+    - convention
+    - pattern
+    - hard-bug
 
 # ── V9: Verification ───────────────────────────────────────
 verification:
@@ -78,7 +80,7 @@ produces: [knowledge-update]
 consumes: [source-code, task-outcome]
 
 token_budget:
-  max_files_read: 2
+  max_files_read: 3
   max_lines_per_read: 150
   max_shell_commands: 0
   stop_early: true
@@ -88,13 +90,43 @@ exit_codes: [SUCCESS, BLOCKED, DISMISSED, FAILED]
 
 # qk-project-memory — Project Knowledge Management V1
 
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
 > **Kim chỉ nam tối thượng:** *"Knowledge phải được quản lý giống như source code: đơn giản, có thể xem xét (review), có thể cập nhật, có thể loại bỏ và luôn có con người chịu trách nhiệm phê duyệt."*
-> 
-> **Nguyên tắc định hướng:**
-> - **Đơn giản hơn > Thông minh hơn:** Mọi tính năng chỉ phục vụ 2 mục tiêu: giúp AI mở đúng file nhanh hơn, hoặc tránh lặp lại một lỗi đã trả giá đắt.
-> - **Navigator, NOT Source of Truth:** Memory chỉ dùng để giảm thời gian tìm kiếm, không thay thế việc đọc mã nguồn hiện tại.
-> - **Tài liệu Kỹ Thuật:** `AGENTS.md` và `index.yaml` là tài liệu kỹ thuật của dự án, tuyệt đối KHÔNG phải nhật ký hội thoại của AI ("Hôm nay AI đã...", "User bảo...").
-> - **AI Đề xuất -> Con người Phê duyệt:** AI không tự học ngầm, AI tóm tắt và đề xuất để lập trình viên chốt duyệt.
+
+---
+
+## Preconditions
+
+Trước khi đọc hoặc ghi vào bộ nhớ dự án:
+
+- [ ] Kiểm tra xem thư mục `.ai-local/` đã tồn tại chưa:
+  - Nếu **chưa có**: Tự động tạo `.ai-local/AGENTS.md` và `.ai-local/knowledge/index.yaml` (Self-Init Protocol), đồng thời đảm bảo `.ai-local/` đã nằm trong `.gitignore`.
+- [ ] Xác định thao tác: **Tra cứu (Retrieve)** hay **Học/Ghi nhớ (/learn)**.
+- [ ] Với thao tác Ghi nhớ: Tri thức BẮT BUỘC phải thuộc 1 trong 4 danh mục cốt lõi:
+  1. `Architecture` (Cấu trúc nền tảng)
+  2. `Convention` (Quy ước viết code bất di bất dịch)
+  3. `Pattern` (Mẫu giải pháp lặp lại nhiều bước)
+  4. `Hard Bug` (Lỗi tốn nhiều thời gian xử lý)
+- [ ] Nếu là lỗi typo, format CSS vặt vãnh, hoặc CRUD tầm thường:
+  → **EXIT: DISMISSED** (Bỏ qua để giữ sạch bộ nhớ).
+
+---
+
+## Scope
+
+✅ Skill này làm:
+- Khởi tạo và duy trì bộ nhớ cục bộ an toàn tại `.ai-local/` (tách biệt khỏi git commit chung).
+- Tra cứu nhanh các quyết định kiến trúc, patterns và cách fix bug cũ trước khi giải quyết task mới.
+- Đề xuất bản thảo tri thức mới (Draft Proposal) dưới chuẩn YAML súc tích.
+- Xin phê duyệt rõ ràng từ lập trình viên (Human Approval Gate) trước khi lưu vĩnh viễn.
+- Lưu vết lịch sử theo cơ chế Zero-Overwrite (Chuyển trạng thái cũ sang `Archived` thay vì xóa mất dữ liệu).
+
+❌ Skill này KHÔNG làm:
+- Tự động ghi ngầm tri thức mà không có sự đồng ý của con người.
+- Lưu trữ nhật ký hội thoại ("Hôm nay user bảo làm X...").
+- Dùng đường dẫn tuyệt đối máy cá nhân (`C:/...`, `D:/...`).
+- Thay thế mã nguồn thật (Memory chỉ là Navigator hỗ trợ định vị).
 
 ---
 
@@ -208,7 +240,7 @@ knowledge:
 
 ---
 
-## 4. Quy Trình Trò Chuyện & Thao Tác (The `/learn` Lifecycle)
+## Execution Steps — The `/learn` Lifecycle
 
 Bất kỳ lúc nào người dùng gõ `/learn`, `./qk-project-memory`, hoặc sau khi hoàn tất một task phức tạp có tham số yêu cầu ghi nhớ, Agent PHẢI tuân thủ theo 4 bước khép kín:
 
@@ -246,3 +278,26 @@ Trình bày rõ trước người dùng trên chat:
 | BLOCKED | Đề xuất tri thức bị Người dùng từ chối (Hoặc thiếu quyền truy xuất file) | Không thay đổi bộ nhớ |
 | DISMISSED | Thao tác không thỏa mãn 4 tiêu chí lọc V1 (Chỉ là typo, css vặt) | Bỏ qua ghi nhớ nhằm sạch hệ thống |
 | FAILED | File bộ nhớ sai định dạng cú pháp YAML hoặc vi phạm giới hạn 100 dòng | Yêu cầu sửa/reset cấu trúc file |
+
+---
+
+## Prompt Template
+
+```
+Lệnh:         [/learn hoặc tra cứu tri thức]
+Tri thức:     [Tóm tắt pattern, convention, kiến trúc, hoặc hard bug vừa xử lý]
+File liên quan:[Đường dẫn tương đối: vd: src/services/apiClient.ts]
+Mục đích:     [Giúp AI trong tương lai không lặp lại lỗi hoặc mở đúng file]
+```
+
+### Ví dụ thao tác:
+
+**Lưu một Hard Bug vừa xử lý xong**
+```
+Lệnh:         /learn
+Tri thức:     Hard Bug: Lỗi hydration mismatch trong Next.js do dùng new Date() trực tiếp trong component render.
+Khắc phục:    Dùng useEffect để set client date hoặc dùng thư viện suppressHydrationWarning.
+File:         src/components/HeaderClock.tsx
+```
+→ AI chuẩn bị bản draft YAML đề xuất theo chuẩn `index.yaml` và hỏi người dùng phê duyệt trước khi commit vào `.ai-local/knowledge/index.yaml`.
+

package/.agents/skills/qk-refactor/SKILL.md

@@ -1,8 +1,8 @@
----
+---
 name: qk-refactor
-version: 9.1.0
+version: 9.2.0
 status: stable
-description: "Tái cấu trúc và dọn dẹp mã nguồn để dễ bảo trì hơn mà không làm thay đổi logic hoạt động bên ngoài."
+description: "Tái cấu trúc code để dễ bảo trì, dễ test hơn — không thay đổi external behavior. Dùng skill này khi user nhắc đến: refactor, tái cấu trúc, tách file, extract function/component/module, clean code, reduce complexity, file quá dài, God class, quá nhiều responsibilities — kể cả khi chỉ nói \"file này lộn xộn quá\"."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 type: capability
@@ -20,13 +20,17 @@ complexity:
     has_external_dependency: false
     has_breaking_change: false
 
-triggers:
-  - refactor
-  - tái cấu trúc
-  - clean up this code
-  - simplify
-  - reduce complexity
-  - dẫn cấu trúc code
+triggers:
+  - "refactor"
+  - "tái cấu trúc"
+  - "tách file"
+  - "extract function/component/module"
+  - "clean code"
+  - "reduce complexity"
+  - "file quá dài"
+  - "God class"
+  - "quá nhiều responsibilities"
+
 
 selection:
   priority: medium
@@ -44,7 +48,7 @@ tools:
   - terminal
 
 related_skills:
-  - qk-engineering-standard
+  - qk-code-review
   - qk-project-health
 
 knowledge_scope:
@@ -76,305 +80,164 @@ token_budget:
   max_shell_commands: 2
   stop_early: true
 
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
 
 # qk-refactor - Safe Refactor
 
-> Language rule: Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+Chịu trách nhiệm tái cấu trúc mã nguồn để tăng khả năng bảo trì, giảm độ phức tạp và tăng tính kiểm thử mà **TUYỆT ĐỐI KHÔNG làm thay đổi hành vi bên ngoài (External Behavior)**.
+
+---
 
-## 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:* Pattern / Convention (vd: chiến lược tách file anti-slop, bảo toàn public contract).
-
-- 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 tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- 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:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### 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:* Pattern / Convention (vd: chiến lược tách file anti-slop, bảo toàn public contract).
-
-- 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 tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- 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:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### 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 tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- 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:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### 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 tái cấu trúc mã nguồn hiệu quả (vd: bẻ gẫy god-file thành module O(1)).
-
-- 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:* Các thao tác đổi tên biến (rename) hoặc format đơn giản.
-
----
-
-### 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
-- [ ] Target file(s) or module(s) are specified
-- [ ] Tests exist for the target code (or can be created)
 
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "Missing: target files or test coverage"
+Trước khi tái cấu trúc bất kỳ file nào, AI BẮT BUỘC kiểm tra:
+
+- [ ] Xác định rõ mục tiêu refactor (tách file, giảm cognitive complexity, khử duplication, áp dụng Design Pattern).
+- [ ] Xác định public contracts (functions, classes, API routes, props) cần giữ nguyên vẹn.
+- [ ] Kiểm tra hệ thống test hiện có: có tests để verify behavior không?
+- [ ] Nếu yêu cầu refactor kèm theo thay đổi nghiệp vụ hoặc đổi behavior:
+  → **EXIT: BLOCKED**
+  → Báo cáo user: Tách riêng việc refactor (qk-refactor) và việc đổi tính năng (qk-feature-delivery).
+
+---
 
 ## Scope
-- Improve internal code quality without changing external behavior
-- Reduce complexity, improve naming, extract functions
-- Remove dead code and duplication
-
-## Non-Goals
-- Add new functionality
-- Change public API signatures
-- Modify behavior or business logic
-
-## Workflow
-1. Establish baseline (current behavior + tests)
-2. Plan refactor steps
-3. Execute step by step
-4. Verify behavior unchanged
-5. Run validation gate
-
-## Exit Codes
-| Code | Meaning |
-|------|---------|
-| SUCCESS | Refactor complete, behavior preserved, tests pass |
-| PARTIAL | Refactor done, some tests need attention |
-| BLOCKED | Missing preconditions |
-| FAILED | Behavior changed or tests broken |
+
+✅ Skill này làm:
+- Trích xuất hàm, component, custom hooks hoặc helper modules (Extract method/module).
+- Giảm độ phức tạp cyclomatic (lồng if/else sâu, switch case khổng lồ).
+- Khử trùng lặp mã nguồn (DRY) mà không tạo ra over-abstraction gượng ép.
+- Tối ưu đặt tên biến, hàm theo đúng quy ước sạch (Clean Code).
+- Bảo đảm 100% backward compatibility với các consumer của module.
+
+❌ Skill này KHÔNG làm:
+- Sửa đổi business logic hoặc thay đổi đầu ra mong đợi của hệ thống.
+- Viết tính năng mới ngoài lề trong quá trình refactor.
+- Tự ý thay đổi schema cơ sở dữ liệu (→ `qk-data-lifecycle`).
+
+---
+
+## Execution Steps
+
+### Step 1 — Current State & Contract Lock
+```
+Inputs:  Mã nguồn mục tiêu, Public interface
+Actions:
+  - Phân tích luồng thực thi và các điểm vào/ra (inputs/outputs, exceptions).
+  - Khóa (lock) contract công khai: không thay đổi signature của exported functions/components.
+  - Kiểm tra test coverage hiện có (nếu có).
+Output: Refactor Safety Boundary
+```
+
+### Step 2 — Incremental Transformation
+```
+Inputs:  Target code, Safety boundary
+Actions:
+  - Tách nhỏ từng phần (baby steps): trích xuất hàm con, module độc lập.
+  - Thay thế cấu trúc lồng ghép bằng Guard Clauses (early return).
+  - Di chuyển các helper/utility sang vị trí phù hợp theo kiến trúc dự án.
+Output: Refactored code
+```
+
+### Step 3 — Verification & Equivalence Check
+```
+Inputs:  Refactored code, Original tests
+Actions:
+  - Chạy linter và typecheck: 0 type errors, 0 lint warnings.
+  - Chạy tests để xác nhận tính tương đương hành vi (behavior equivalence).
+  - So sánh diff để đảm bảo không xóa nhầm logic hay import.
+Exit: SUCCESS nếu code sạch hơn, pass linter/types và giữ nguyên behavior.
+```
+
+---
+
+## Prompt Template
+
+AI đọc `DEV_PROFILE.md` để biết conventions. Mô tả vấn đề — AI đọc code thật trước khi refactor.
+
+```
+Target:      [File / module / function cần refactor — đường dẫn cụ thể]
+Vấn đề:     [Code đang gây ra vấn đề gì — quá dài / khó test / lặp lại / ...]
+Mục tiêu:   [Muốn đạt được gì sau refactor]
+Giữ nguyên: [Public interface / behavior / test cases không được đổi]
+```
+
+---
+
+### Theo Role — AI refactor theo chiều sâu khác nhau:
+
+**role: fe**
+```
+Target:      src/pages/CheckoutPage.tsx (380 dòng)
+Vấn đề:     Một file trộn lẫn: form state, API calls, validation, UI rendering,
+             cart calculation — không test được, không reuse được
+Mục tiêu:   Tách thành: CheckoutPage (UI) + useCheckout (logic hook) +
+             checkoutSchema (validation) + cartUtils (calculation)
+Giữ nguyên: Props interface của CheckoutPage không đổi, behavior submit không đổi
+```
+→ AI refactor: custom hook extraction pattern, co-location vs separation of concerns,
+  memoization opportunities (useMemo/useCallback), type narrowing sau khi tách.
+
+**role: be**
+```
+Target:      src/services/OrderService.ts (420 dòng)
+Vấn đề:     God class — xử lý: tạo order, tính giá, gửi email, update inventory,
+             generate invoice — vi phạm SRP, unit test không isolate được
+Mục tiêu:   Tách ra theo domain: PricingService, InventoryService, NotificationService,
+             OrderService chỉ orchestrate
+Giữ nguyên: Public method signatures của OrderService, không đổi DB transactions
+```
+→ AI refactor: dependency injection pattern, service boundary design,
+  transaction scope sau khi tách (vẫn cần atomic), interface extraction cho testability.
+
+**role: fullstack**
+```
+Target:      src/features/products/ (toàn bộ folder)
+Vấn đề:     Feature folder có: API route, DB query, FE component, type definitions
+             — tất cả trong cùng 1 file products.ts (550 dòng)
+Mục tiêu:   Feature-based architecture: products/api.ts, products/db.ts,
+             products/components/, products/types.ts, products/hooks.ts
+Giữ nguyên: Import paths của các file khác đang dùng products types
+```
+→ AI refactor: barrel exports để preserve import paths, layer separation
+  (presentation/business/data), shared types location, circular dependency check.
+
+**role: data**
+```
+Target:      transforms/order_metrics.sql (250 dòng)
+Vấn đề:     SQL monolith — một query tính tất cả metrics, không reusable,
+             debug khó, CTE lồng nhau 6 cấp
+Mục tiêu:   Tách thành dbt models: stg_orders, int_order_items, fct_order_metrics
+             Mỗi model làm đúng một việc
+Giữ nguyên: Output schema của fct_order_metrics không đổi (downstream depends on it)
+```
+→ AI refactor: dbt model layering (staging/intermediate/mart), ref() dependencies,
+  incremental model strategy, documentation + schema.yml generation.
+
+**role: ai-engineer**
+```
+Target:      agents/rag_agent.py (300 dòng)
+Vấn đề:     Monolithic RAG function — embed + retrieve + rerank + generate
+             tất cả trong 1 hàm, không thể A/B test từng component
+Mục tiêu:   Tách thành pipeline: Retriever, Reranker, Generator — mỗi class
+             có interface rõ ràng, swap được implementation
+Giữ nguyên: Input/output interface của rag_agent() không đổi
+```
+→ AI refactor: Strategy pattern cho từng pipeline stage, dependency injection
+  cho model/embedding, eval hooks tại từng stage, config-driven pipeline.
+
+**role: devops**
+```
+Target:      .github/workflows/deploy.yml (200 dòng)
+Vấn đề:     Một workflow file làm tất cả: test + build + push image + deploy staging
+             + deploy prod + notify — không reusable, khó debug khi fail
+Mục tiêu:   Tách thành reusable workflows: test.yml, build-push.yml,
+             deploy.yml (reusable), notify.yml — orchestrated từ main.yml
+Giữ nguyên: Trigger conditions và environment variables không đổi
+```
+→ AI refactor: GitHub reusable workflows pattern (workflow_call),
+  matrix strategy cho multi-env deploy, secret scoping per environment,
+  concurrency groups để tránh parallel deploys.