ai-developer-skill-os 9.3.0 → 10.1.0

package/.agents/skills/qk-devops-release/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: qk-devops-release
+version: 10.1.0
+status: stable
+subtitle: "DevOps, CI/CD & Deploy"
+description: "Vận hành Nền tảng, Tự động hóa CI/CD, Cổng kiểm soát phát hành 8-Gate Production, Đồng bộ tài liệu kỹ thuật, Bộ nhớ dự án (.ai-local/) và Kỹ nghệ AI/RAG. Dùng khi: ci/cd, deployment, pipeline, docker, dockerfile, devops, github actions, deploy production, release checklist, go live, rollout, viết docs, readme, swagger, lưu context, project memory, /learn, build ai, rag pipeline, prompt engineering — TUYỆT ĐỐI KHÔNG dùng khi debug lỗi logic ứng dụng (dùng qk-bug-resolution)."
+tools:
+  - filesystem
+  - terminal
+rules:
+  - global
+  - platform
+  - security
+  - safety
+workflow: production-release
+triggers:
+  - "ci/cd"
+  - "deployment"
+  - "pipeline"
+  - "docker"
+  - "dockerfile"
+  - "devops"
+  - "github actions"
+  - "deploy production"
+  - "release checklist"
+  - "go live"
+  - "rollout"
+  - "viết docs"
+  - "readme"
+  - "swagger"
+  - "lưu context"
+  - "project memory"
+  - "/learn"
+  - "build ai"
+  - "rag pipeline"
+  - "prompt engineering"
+---
+
+# qk-devops-release — DevOps, CI/CD & Deploy (Platform, Release Gate & Memory Engine)
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
+
+> **Core Principle:** Right-size infrastructure. Do not design a Kubernetes cluster for a static site. Automation must be dependable, reproducible, and guarded by strict safety gates.
+> **Release Principle:** PASS is a verified conclusion, never a target. Zero fake green gates.
+
+### 🛡️ Anti-Overengineering Rule (KHÔNG PHỨC TẠP HÓA HẠ TẦNG)
+- **Tương xứng quy mô hạ tầng:** Nếu dự án chỉ là web app vừa và nhỏ, Docker Compose hoặc single-stage container là đủ. Tuyệt đối KHÔNG tự ý đề xuất setup Kubernetes, Helm, Istio service mesh phức tạp hóa trừ khi người dùng yêu cầu rõ ràng.
+- **Tài liệu ngắn gọn, thực chiến:** README chỉ cần 3 bước chuẩn (Prerequisites → Setup → Run). Không viết lan man hàng trang lý thuyết không ai đọc.
+
+### 🔒 No Unrelated Changes Rule (CẤM SỬA LAN MAN)
+- Chỉ can thiệp vào Dockerfile, CI/CD pipeline, deploy scripts hoặc docs được yêu cầu.
+- **CẤM** nhân tiện sửa code nghiệp vụ của ứng dụng trong cùng một commit hạ tầng.
+- Nếu phát hiện code lỗi trong app: **Chuyển giao quyền** cho `qk-bug-resolution`, không tự ý sửa.
+
+### 🛡️ Anti-Fake-Pass Rule (CẤM ÉP PASS ẢO - R-G-14.5)
+- **CẤM** thêm cờ bỏ qua lỗi (`|| true`, `--no-verify`, `continue-on-error: true`) vào CI pipeline chỉ để ép build xanh.
+- **CẤM** hardcode secret hoặc credentials vào Dockerfile/Compose chỉ để test cho nhanh.
+- **CẤM** tự ý đánh dấu PASS cho 8 Gates nếu thiếu bằng chứng thực tế.
+
+### ⚖️ Verify Before Claim Rule (XÁC MINH TRƯỚC KHI BÁO CÁO - R-G-14.7)
+- **Cấm tuyên bố 8 Cổng Đạt nếu chưa chạy lệnh:** Phải chạy test suite và build trước khi tick xanh các cổng Gate 1 và Gate 2.
+- **Báo cáo trung thực:** Nếu không có Docker daemon chạy cục bộ hoặc không có quyền truy cập CI runner, AI phải ghi rõ: `"Trạng thái: NOT VERIFIED — Đã kiểm tra cú pháp Dockerfile/CI tĩnh. Chưa build image thực tế trong môi trường này"`.
+
+---
+
+## 2. Ranh Giới & Phạm Vi Kỹ Thuật (Hard Boundaries)
+
+### ✅ Việc skill này BẮT BUỘC làm:
+- **Production-Ready Dockerfile:** Multi-stage build, Non-root user (`USER node/appuser`), layer caching tối ưu, và healthcheck directive.
+- **8-Gate Production Gatekeeper:** Rà soát nghiêm ngặt 8 cổng an toàn trước khi deploy. **Chỉ cần 1 cổng đỏ = CHẶN release ngay lập tức**.
+- **Accurate Documentation (Code-First Truth):** Viết tài liệu khớp 100% với code thực tế đang chạy.
+- **Institutional Memory (`.ai-local/`, `/learn`):** Ghi nhớ các quyết định kiến trúc và bài học fix bug phức tạp vào `.ai-local/knowledge/` (đã gitignore).
+
+### ❌ Việc skill này TUYỆT ĐỐI KHÔNG làm (Chuyển giao quyền):
+- Viết API endpoint hay logic truy vấn database ứng dụng → Chuyển sang `qk-backend-data`.
+- Điều tra bug crash logic trong mã nguồn → Chuyển sang `qk-bug-resolution`.
+
+---
+
+## 3. 8 Cổng Kiểm Soát Phát Hành Production (8-Gate Checklist)
+
+```
+Gate 1: Test Suite Green       ── 100% tests pass (Verify bằng lệnh thực tế)
+Gate 2: Security Clean         ── 0 lỗ hổng Critical/High, 0 secret leak trong commit
+Gate 3: Safe DB Migrations     ── Migration có tính tương thích ngược và có down script
+Gate 4: Environment Variables  ── Mọi biến mới đã được khai báo trong .env.example
+Gate 5: Rapid Rollback Plan    ── Quy trình rollback được xác định rõ ràng (< 5 phút)
+Gate 6: Smoke Test Plan        ── Danh sách 3-5 endpoints then chốt để test ngay sau deploy
+Gate 7: SemVer & Git Tag       ── Đã bump version đúng chuẩn Semantic Versioning
+Gate 8: Release Notes Ready    ── Bản tóm tắt thay đổi sẵn sàng
+```
+
+---
+
+## 4. Xử Lý Sự Cố Khi Release Gate Thất Bại (Failure Path)
+
+Nếu bất kỳ cổng nào trong 8 cổng không đạt:
+1. **CHẶN RELEASE NGAY:** Không nhắm mắt làm ngơ cho deploy.
+2. **Nêu rõ cổng thất bại:** Báo cáo chi tiết lý do cổng bị chặn (ví dụ: Gate 1 fail do 2 unit test đỏ; Gate 4 fail do biến `STRIPE_SECRET_KEY` chưa có trong `.env.example`).
+3. **Kế hoạch khôi phục khi deploy dở dang:** Kích hoạt rollback ngay lập tức:
+   ```bash
+   git revert <commit_hash>
+   # hoặc pull lại container image tag an toàn trước đó
+   ```
+
+---
+
+## 5. Thích Ứng Theo Role Kỹ Thuật (Role Adaptation)
+
+| Role | Trọng tâm khi chạy DevOps & Release | Hành vi kỹ thuật đặc thù |
+|---|---|---|
+| `devops` | Dockerfile, CI/CD pipeline, Kubernetes/Helm, secrets management | Tối ưu image size, caching layers, rollback automation |
+| `ai-engineer` | RAG architecture, vector db, prompt template, evaluation metrics | Chunking strategy, reranking, scorecard eval |
+| `pm` | Release notes, changelog, feature readiness, user impact | Viết release notes tóm tắt giá trị cho người dùng |
+| `fullstack` | Docker-compose cho local dev, đồng bộ env vars, verify smoke test | Cập nhật `.env.example`, kiểm tra build bundle size |
+
+---
+
+## 6. Báo Cáo Nghiệm Thu Chuẩn Xác (Truth-First Report)
+
+```markdown
+🚀 DevOps & Release Summary                           [Role: <role> | Task: <Deploy / CI-CD / Docs>]
+─────────────────────────────────────────────────────────────────────
+Mục tiêu thực hiện: [Cấu hình CI/CD / 8-Gate Release Check / Sync Docs]
+Trạng thái:         [SẴN SÀNG RELEASE / BỊ CHẶN (RELEASE BLOCKED) / ĐÃ CẤU HÌNH]
+
+Chi tiết kỹ thuật:
+  • [Docker]        [Dockerfile](file:///<workspace-root>/Dockerfile): Multi-stage, Non-root
+  • [CI/CD]         [.github/workflows/ci.yml](file:///<workspace-root>/.github/workflows/ci.yml)
+  • [Documentation] [README.md](file:///<workspace-root>/README.md): Đồng bộ với code thực tế
+
+Tình trạng 8 Cổng An Toàn (Truth-First):
+  • Gate 1 (Tests):        [Pass 100% (Đã chạy thực tế) / Chưa verify]
+  • Gate 2 (Security):     [0 Critical / Cần quét]
+  • Gate 3 (Migration):    [Tương thích ngược / Không có migration]
+  • Gate 4 (Env Vars):     [Đã cập nhật .env.example]
+  • Gate 5 (Rollback):     [Sẵn sàng lệnh revert]
+  • Gate 6 (Smoke Test):   [Đã có 3 endpoints kiểm tra]
+  • Gate 7 (SemVer):       [Bump vX.Y.Z]
+  • Gate 8 (Changelog):    [Sẵn sàng Release Notes]
+```

package/.agents/skills/qk-feature-delivery/SKILL.md

@@ -1,251 +1,183 @@
 ---
-# ── Identity ───────────────────────────────────────────────
-name: qk-feature-delivery
-version: 9.2.0
-status: stable
-description: "Phát triển tính năng mới end-to-end: Requirements → Context → Design → Implement → Self-audit. Dùng skill này khi user nhắc đến: add feature, build new, implement, phát triển tính năng, tạo mới, thêm chức năng — kể cả khi mô tả bằng ngôn ngữ tự nhiên như \"tôi muốn có tính năng X\" hoặc \"làm cho app có thể Y\"."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V9: Classification ─────────────────────────────────────
-type: capability
-
-intent:
-  - feature-building
-  - end-to-end-development
-  - implementation
-
-complexity:
-  level: high
-  criteria:
-    files_affected: "5+"
-    has_behavior_change: true
-    has_external_dependency: true
-    has_breaking_change: false
-
+name: qk-feature-delivery
+version: 10.1.0
+status: stable
+subtitle: "Build Feature mới"
+description: "Phát triển tính năng mới end-to-end: Thiết lập Contract kiểu dữ liệu, tích hợp gọi API, xử lý trọn vẹn 4 trạng thái UI (Loading/Success/Empty/Error) và tuân thủ YAGNI/SOLID. Dùng khi: add feature, phát triển tính năng mới, tạo mới, build new, thêm chức năng, tích hợp api, fetch data, consume api, bind data, state management — TUYỆT ĐỐI KHÔNG dùng cho việc fix bug (dùng qk-bug-resolution) hoặc dọn dẹp code cũ (dùng qk-code-cleaner)."
+tools:
+  - filesystem
+  - terminal
+rules:
+  - global
+  - coding-standards
+  - safety
+workflow: feature-delivery
 triggers:
   - "add feature"
-  - "build new"
-  - "implement"
-  - "phát triển tính năng"
-  - "tạo mới"
+  - "phát triển tính năng mới"
+  - "tạo mới tính năng"
+  - "build new feature"
   - "thêm chức năng"
-
-
-selection:
-  priority: medium
-  confidence_threshold: 0.85
-
-# ── V8: References ─────────────────────────────────────────
-workflow: feature-delivery
-
-rules:
-  - global
-  - coding
-  - safety
-
-tools:
-  - filesystem
-  - terminal
-
-related_skills:
-  - qk-context-loader
-  - qk-test-engineering
-
-knowledge_scope:
-  owns:
-    - feature-implementation
-    - requirement-analysis
-  references:
-    - testing
-    - security
-    - anti-patterns
-    - design-system
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: feature
-
-examples: []
-learnings: []
-
-# ── V7 Runtime ─────────────────────────────────────────────
-execution_mode: deterministic
-cost: high
-latency: slow
-risk: medium
-side_effects: edit_files
-produces: [code, report]
-consumes: [context-graph, design-md, user-description]
-
-token_budget:
-  max_files_read: 5
-  max_lines_per_read: 150
-  max_shell_commands: 2
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-feature-delivery — End-to-End Feature Builder
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-Chịu trách nhiệm triển khai tính năng mới end-to-end theo luồng tiêu chuẩn: **Requirements → Context → Design → Implement → Self-audit**. Bảo đảm code viết ra tích hợp mượt mà vào hệ thống hiện hữu, chuẩn theo role và conventions từ `DEV_PROFILE.md`.
-
----
-
-## Preconditions
-
-Trước khi bắt đầu implement bất kỳ tính năng nào, AI BẮT BUỘC kiểm tra:
-
-- [ ] Đọc `.agents/DEV_PROFILE.md` để lấy role, primary stack, coding conventions và constraints.
-- [ ] Xác định scope thay đổi (màn hình, module, schema, API liên quan).
-- [ ] Kiểm tra tính rõ ràng của yêu cầu: Có acceptance criteria rõ ràng chưa? Đã rõ input/output chưa?
-- [ ] Nếu yêu cầu mơ hồ hoặc có quyết định kiến trúc lớn chưa thống nhất:
-  → **EXIT: BLOCKED**
-  → Báo cáo user câu hỏi làm rõ trước khi can thiệp vào mã nguồn.
-
----
-
-## Scope
-
-✅ Skill này làm:
-- Phân tích yêu cầu và định hình kiến trúc tính năng tương thích với codebase.
-- Định nghĩa type-safe contracts, schemas và dữ liệu liên quan.
-- Triển khai code tính năng hoàn chỉnh qua các tầng (FE UI, BE controller/service, routing).
-- Xử lý đầy đủ các trạng thái biên: loading, error, empty data, pagination, boundary conditions.
-- Tự kiểm toán (Self-audit) sau khi implement: linting, typecheck, và format code.
-
-❌ Skill này KHÔNG làm:
-- Sửa lỗi crash phát sinh đột xuất không nằm trong phạm vi feature mới (→ `qk-bug-resolution`).
-- Tái cấu trúc quy mô lớn codebase không phục vụ feature (→ `qk-refactor`).
-- Chạy đợt audit bảo mật tổng thể toàn dự án (→ `qk-security-audit`).
-
----
-
-## Execution Steps
-
-### Step 1 — Context Loading & Gap Analysis
-```
-Inputs:  Yêu cầu tính năng từ user, DEV_PROFILE.md, mã nguồn hiện tại
-Actions:
-  - Khảo sát các modules, components, services hiện có liên quan đến tính năng.
-  - Lập danh sách các files cần tạo mới và files cần chỉnh sửa.
-  - Xác định dependency mới (nếu có) và đối chiếu với constraints trong DEV_PROFILE.md.
-Output: Feature Implementation Plan
-```
-
-### Step 2 — Contract & Architecture Design
-```
-Inputs:  Feature Implementation Plan
-Actions:
-  - Thiết kế interface/types, DTO, data contracts giữa các tầng.
-  - Xác định state management và data flow (Client state, Server cache, DB model).
-  - Dự phòng các kịch bản ngoại lệ (empty data, network failure, unauthorized).
-Output: Type definitions & Contract drafts
-```
-
-### Step 3 — Incremental Implementation
-```
-Inputs:  Type definitions, Contract drafts
-Actions:
-  - Viết code theo thứ tự từ lõi (Core/Domain/Model) → Service/Logic → Presentation/UI.
-  - Tuân thủ quy ước đặt tên (naming conventions) và design system tokens của dự án.
-  - Không hardcode các giá trị cấu hình, URL hay magic numbers.
-Output: Functional implementation
-```
-
-### Step 4 — Self-Audit & Quality Gate
-```
-Inputs:  Modified & Created files
-Actions:
-  - Kiểm tra lint và type checking.
-  - Rà soát edge cases: null/undefined checks, error boundary handling.
-  - Đảm bảo không làm hỏng các tính năng cũ lân cận (regressions).
-Exit: SUCCESS nếu code pass types/lint và đạt mọi acceptance criteria.
-```
-
----
-
-## Prompt Template
-
-AI đọc `DEV_PROFILE.md` để lấy role + stack. Bạn chỉ cần mô tả **WHAT**, không cần nhắc lại stack.
-
-```
-Tính năng:   [Tên / mục đích tính năng]
-Màn hình:    [Trang / route / component liên quan — hoặc "mới hoàn toàn"]
-Done khi:    [User thấy gì / hệ thống làm gì — tiêu chí cụ thể]
-Edge cases:  [Điều kiện đặc biệt, dữ liệu rỗng, lỗi cần xử lý]
-Không được:  [Ràng buộc — không đổi API này, không xóa field kia]
-```
-
----
-
-### Theo Role — AI sẽ phân tích kỹ thuật như sau:
-
-**role: fe**
-```
-Tính năng:   Infinite scroll cho danh sách sản phẩm
-Màn hình:    /products — ProductList.tsx đã có
-Done khi:    Scroll đến cuối → tự load thêm 20 sản phẩm, có loading indicator
-Edge cases:  Hết data → hiện "Đã xem tất cả", lỗi API → hiện retry button
-Không được:  Không đổi ProductCard component
-```
-→ AI phân tích: intersection observer vs scroll event, React Query `useInfiniteQuery`,
-  cache invalidation, skeleton vs spinner, bundle impact của thư viện.
-
-**role: be**
-```
-Tính năng:   API pagination cho /products với cursor-based paging
-Màn hình:    GET /api/products — route đã có nhưng chỉ trả toàn bộ
-Done khi:    Trả { data, nextCursor, hasMore }, tối đa 20 items/page
-Edge cases:  cursor không hợp lệ → 400, không có data → { data: [], hasMore: false }
-Không được:  Không đổi response shape của existing fields
-```
-→ AI phân tích: cursor vs offset trade-off, index strategy trên DB,
-  validation middleware, backward compatibility của response schema.
-
-**role: fullstack**
-```
-Tính năng:   Thêm chức năng export danh sách đơn hàng ra CSV
-Màn hình:    /orders — có table hiện tại, cần thêm nút Export
-Done khi:    Click Export → tải file CSV với đúng cột, chỉ export filtered data
-Edge cases:  > 10k rows → stream response, không có data → disable button
-Không được:  Không thêm dependency mới nếu native API đủ dùng
-```
-→ AI phân tích: FE trigger + progress UX, BE streaming response vs buffer,
-  type-safe contract giữa FE-BE, memory safety khi dataset lớn.
-
-**role: data**
-```
-Tính năng:   Pipeline load daily sales data từ PostgreSQL → BigQuery
-Màn hình:    DAG mới trong Airflow — incremental load
-Done khi:    Chạy hàng ngày 2AM, chỉ load data của ngày hôm trước, idempotent
-Edge cases:  Re-run phải cho kết quả giống nhau, source schema thay đổi → alert
-Không được:  Không truncate table, chỉ upsert
-```
-→ AI phân tích: watermark strategy, partition pruning, schema evolution handling,
-  idempotency key design, data quality assertion trước khi load.
-
-**role: ai-engineer**
-```
-Tính năng:   RAG pipeline trả lời câu hỏi từ tài liệu nội bộ
-Màn hình:    Chat UI mới — /chat route
-Done khi:    User hỏi → AI trả lời có citation từ đúng document
-Edge cases:  Câu hỏi ngoài scope → "Tôi không tìm thấy thông tin liên quan"
-Không được:  Không hallucinate khi không có context
-```
-→ AI phân tích: chunking strategy, embedding model choice, retrieval (BM25 vs dense),
-  reranking, context stuffing vs summarization, eval metrics (faithfulness, relevance).
-
-**role: devops**
-```
-Tính năng:   CI pipeline tự động chạy test + deploy lên staging khi merge PR
-Màn hình:    .github/workflows/ — chưa có file nào
-Done khi:    PR merge → test pass → deploy staging → notify Slack
-Edge cases:  Test fail → stop pipeline, notify người tạo PR
-Không được:  Không auto-deploy production
-```
-→ AI phân tích: workflow triggers, secrets management, caching strategy,
-  environment isolation, rollback mechanism, notification integration.
+  - "tích hợp api"
+  - "consume api"
+  - "bind data"
+  - "state management"
+---
+
+# qk-feature-delivery — Build Feature mới (End-to-End Delivery Engine)
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
+
+> **Core Principle:** YAGNI (You Aren't Gonna Need It). Build the simplest, cleanest solution that fully satisfies today's requirement. Do not write tomorrow's abstractions today.
+> **Verification Principle:** PASS is evidence, not an objective. Never claim pass without concrete execution proof.
+
+### 🛡️ Anti-Overengineering Rule (CẤM VẼ VOI)
+- **Không tạo kiến trúc cồng kềnh cho tính năng đơn giản:** Nếu một tính năng chỉ cần 1 endpoint và 1 component, TUYỆT ĐỐI KHÔNG tạo ra cả một hệ thống 5 tầng (không Factory, không Adapter, không 3 lớp Repository trung gian) nếu dự án chưa yêu cầu.
+- **Tận dụng tối đa code có sẵn:** Tái sử dụng các hooks, UI components, và utilities đang chạy tốt trong repo. Tránh viết lại những gì đã tồn tại.
+
+### 🔒 No Unrelated Changes Rule (CẤM SỬA LAN MAN)
+Chỉ sửa các file, dependencies, cấu hình và code paths thực sự cần thiết trực tiếp cho tính năng được yêu cầu:
+- **CẤM** reformat hoặc format lại các file không liên quan.
+- **CẤM** đổi tên biến, hàm, hoặc file ngoài phạm vi tính năng.
+- **CẤM** tự tiện nâng cấp thư viện hoặc sửa build script lân cận.
+- **CẤM** "tiện tay" refactor hoặc clean up code xung quanh nếu người dùng không yêu cầu.
+- Nếu phát hiện vấn đề hoặc code smell ngoài phạm vi: **Chỉ ghi nhận vào báo cáo tổng kết**, tuyệt đối không tự ý chạm vào.
+
+### ⚖️ Verify Before Claim Rule (XÁC MINH TRƯỚC KHI BÁO CÁO)
+- **Kiểm tra build và types thật:** Phải chạy `tsc --noEmit`, linter, hoặc build check trước khi tuyên bố tính năng hoàn thành.
+- **Phân định rõ bằng chứng (Evidence-Based Status):**
+  - `PASS`: Đã chạy lệnh kiểm tra thực tế và kết quả đạt yêu cầu.
+  - `FAIL`: Đã chạy và phát hiện lỗi.
+  - `BLOCKED`: Không thể chạy do thiếu database/staging/external service.
+  - `NOT RUN / PARTIAL`: Chưa chạy lệnh hoặc chỉ mới kiểm tra tĩnh (Cần ghi rõ: *"Trạng thái: Đã bind code logic & types. Cần user test giao diện trực tiếp trên trình duyệt"*).
+  - **TUYỆT ĐỐI KHÔNG CHUYỂN BLOCKED/NOT RUN THÀNH PASS!**
+
+---
+
+## 2. Ranh Giới & Phạm Vi Kỹ Thuật (Hard Boundaries)
+
+### ✅ Việc skill này BẮT BUỘC làm:
+- **Scoped Contract-First Implementation:** Đối với các tính năng có tương tác dữ liệu ngoài, API boundaries, database persistence, hoặc untrusted input: BẮT BUỘC định nghĩa Types/DTOs và Validation Schemas (Zod/Pydantic) trước logic nghiệp vụ. Với UI nội bộ (button, modal, local UI state), không ép buộc sinh schema nếu không có ranh giới dữ liệu.
+- **UI State Rule (Không tạo Empty giả tạo):**
+  - **Data-fetching views (Danh sách / màn hình tải dữ liệu):** BẮT BUỘC xử lý đủ 4 trạng thái: `Loading (Skeleton loader)`, `Success (Render data)`, `Empty (Minh họa ngữ cảnh + Nút Call-to-action)`, và `Error (Message lỗi + Nút Thử Lại/Retry)`.
+  - **Mutations & Actions (Login, logout, xóa item, upload file, submit form):** Xử lý các trạng thái tương tác phù hợp thực tế: `Idle`, `Submitting/Pending`, `Success`, và `Error`. TUYỆT ĐỐI KHÔNG tạo `Empty state` giả tạo cho các hành động không có ý nghĩa danh sách rỗng.
+- **Planning Gate & Exceptions:** Với tính năng mới ảnh hưởng ≥ 2 files hoặc tác động kiến trúc, BẮT BUỘC lập `implementation_plan.md` với `RequestFeedback: true` và dừng lại chờ phê duyệt trước khi tạo/sửa files.
+  - **Ngoại lệ bỏ qua Planning Gate:**
+    - Thay đổi chỉ nằm trong đúng 1 file (Single-file change).
+    - Chỉnh sửa UI/text đơn giản (Trivial UI/text change).
+    - Thay đổi thuần tài liệu (Documentation-only).
+    - Người dùng chỉ định rõ ràng yêu cầu thực thi ngay lập tức mà không cần qua gate.
+
+### ❌ Việc skill này TUYỆT ĐỐI KHÔNG làm (Chuyển giao quyền):
+- Điều tra các lỗi crash cũ có sẵn từ trước trong codebase → Chuyển sang `qk-bug-resolution`.
+- Tự tiện thay đổi cấu trúc bảng cơ sở dữ liệu lớn → Chuyển sang `qk-backend-data`.
+- Tái cấu trúc các module cũ không liên quan đến feature → Chuyển sang `qk-code-cleaner`.
+
+---
+
+## 3. Quy Trình Phát Triển 4 Bước Tuần Tự (Sequential Procedure)
+
+```
+[Bước 1: Contract & Plan]    ── Định nghĩa Types/Schemas (nếu có API/DB), lập plan (nếu ≥ 2 files)
+            │
+            ▼
+[Bước 2: Service & Logic]    ── Xây dựng API Caller & State Handler (caching chỉ khi cần thiết)
+            │
+            ▼
+[Bước 3: UI & State Bind]    ── Gắn Component, Skeleton (nếu fetching), Action feedback (nếu mutation)
+            │
+            ▼
+[Bước 4: Verification Gate] ── Chạy Typecheck/Lint thật. Nếu FAIL ──► Kích hoạt Failure Path
+```
+
+### Chi tiết các bước:
+1. **Contract & Plan:** Thiết lập interface chuẩn cho request/response hoặc persistence model. Lập kế hoạch các files sẽ tạo mới (nếu đa file).
+2. **Service & Logic:** Viết hàm gọi API độc lập với component, xử lý lỗi có ngữ cảnh. Chỉ tích hợp caching, state store hoặc optimistic updates khi tính năng hoặc kiến trúc dự án thực sự yêu cầu.
+3. **UI & State Bind:** Gắn dữ liệu vào JSX/Template. Đảm bảo Skeleton loader không làm nhảy giật layout (chống CLS). Đảm bảo action có loading spinner/disable button chống double-submit.
+4. **Verification Gate:** Kiểm tra type-check và lint thực tế. Xác minh không vi phạm nguyên tắc YAGNI hay sinh ra God file (> 300 dòng).
+
+---
+
+## 4. Xử Lý Sự Cố Khi Build Gãy & Cấm Ép Pass (Failure Path Protocol)
+
+Nếu trong quá trình triển khai gặp lỗi biên dịch, lint, hoặc kiểm thử:
+1. **Dừng lại ngay (Failure Analysis Gate):** Không tiếp tục viết thêm code nếu tầng Contract hoặc Types đang bị đỏ.
+2. **Xác định Root Cause:** Đọc call-stack và thông báo lỗi thực tế để tìm nguyên nhân gốc rễ.
+3. **CẤM CHE GIẤU LỖI (Zero Workarounds):**
+   - CẤM dùng `as any` hoặc `@ts-ignore` / `@ts-expect-error` để né lỗi type.
+   - CẤM disable linter rule hoặc comment bỏ qua lint.
+   - CẤM dùng `catch (e) {}` rỗng để nuốt lỗi cho code khỏi crash.
+   - CẤM sửa hoặc làm yếu assertion của test case chỉ để ép pass.
+4. **Revert có kiểm soát:** Nếu bước làm trước đó làm gãy toàn bộ build của dự án:
+   ```bash
+   git restore <các_file_vừa_tạo_hoặc_sửa>
+   ```
+5. **Báo cáo Blocked:** Nếu thiếu endpoint từ phía backend hoặc thiếu dữ liệu bắt buộc từ 3rd party, dừng lại và thông báo rõ contract bị thiếu cho user với trạng thái `Status: BLOCKED`.
+
+---
+
+## 5. Mẫu Kế Hoạch Chuẩn (Implementation Plan Skeleton)
+
+Khi khởi tạo `implementation_plan.md`:
+
+```markdown
+# Implementation Plan: [Tên Tính Năng Mới]
+
+## 1. Yêu cầu & Trải nghiệm người dùng
+- Tính năng: [Mô tả ngắn gọn giá trị mang lại]
+- Điểm chạm UI: [Vị trí màn hình / nút bấm mới]
+
+## 2. Hợp đồng dữ liệu (API / Boundary Contract)
+- Endpoint: `POST /api/v1/orders` (hoặc N/A nếu thuần UI)
+- Input Schema: `{ items: Array<{ id: string, quantity: number }> }`
+- Output Schema: `{ orderId: string, totalAmount: number, status: string }`
+
+## 3. Danh sách files sẽ thay đổi (Laser Focus)
+- [ ] [NEW] [types.ts](file:///<workspace-root>/src/types/...): Khai báo models & Schema
+- [ ] [NEW] [useOrderService.ts](file:///<workspace-root>/src/services/...): API caller
+- [ ] [NEW] [OrderForm.tsx](file:///<workspace-root>/src/components/...): Component UI
+
+## 4. Kiểm soát trạng thái UI
+- Data Fetching: Loading (Skeleton) | Success | Empty (CTA) | Error (Retry)
+- Hoặc Mutation: Idle | Submitting (Spinner) | Success (Redirect/Toast) | Error (Alert)
+```
+
+---
+
+## 6. Thích Ứng Theo Role Kỹ Thuật (Role Adaptation)
+
+| Role | Trọng tâm khi Build Feature | Hành vi kỹ thuật đặc thù |
+|---|---|---|
+| `frontend` | Component hierarchy, Accessibility, responsive layout, interaction feedback | Tạo custom hook quản lý state, tái sử dụng component có sẵn, skeleton loader |
+| `backend` | API route handler, controller, business domain service, query DB | Áp dụng input validation middleware, dependency injection, unit test service |
+| `fullstack` | Đồng bộ 100% từ Database đến giao diện người dùng | Tạo migration nhỏ (nếu cần), tạo endpoint, sinh types, bind vào UI component |
+| `data` | Ingestion job mới, schema validation, data pipeline task | Tạo incremental dbt model, thêm schema test trong `.yml`, SLA logging |
+| `devops` | Cấu hình biến môi trường mới, service connection, helm values | Cập nhật `.env.example`, thêm secret config, healthcheck endpoint |
+
+---
+
+## 7. Báo Cáo Nghiệm Thu Chuẩn Xác (Truth-First Report)
+
+```markdown
+🚀 Feature Delivery Summary                           [Role: <role> | Feature: <Tên tính năng>]
+─────────────────────────────────────────────────────────────────────
+Phạm vi thực tế:    [N files created / modified]
+Trạng thái:         [Hoàn thành sẵn sàng test | Cần cấu hình thêm env | BLOCKED]
+
+Các tệp mã nguồn mới/sửa đổi:
+  • [NEW] [TênFile.tsx](file:///<workspace-root>/path): [Mô tả vai trò]
+
+Kiểm soát trạng thái giao diện:
+  • Fetching:  [Loading / Success / Empty / Error] hoặc [N/A]
+  • Mutation:  [Idle / Submitting / Success / Error] hoặc [N/A]
+
+Kiểm chứng thực tế (Verify Before Claim):
+  • Type-check: [tsc Clean / mypy Pass / Chưa chạy (Nêu lý do)]
+  • Lint check: [0 errors / Chưa chạy]
+  • YAGNI:      ✅ Giữ giải pháp tối giản, không sinh abstraction thừa
+  • Zero Hack:  ✅ Không dùng any, @ts-ignore, hay silent catch
+```