pi-skill-search 0.1.0

package/skills/vetc-spec-driven/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: vetc-spec-driven
+description: PROACTIVELY activate khi user mô tả tính năng nhưng chưa có spec, hoặc requirement còn mơ hồ. Biến yêu cầu thành Structured Spec với edge cases, acceptance criteria, success criteria. Dùng trước vetc-api-design.
+---
+
+# VETC Spec-Driven Development
+
+Spec rõ ràng → AI sinh code đúng ngay lần đầu. **Code serves specs, not the other way.**
+
+## When to Activate
+
+- User mô tả tính năng bằng tiếng Việt hoặc tiếng Anh, chưa có spec
+- Requirement còn mơ hồ, chưa có edge case
+- Trước khi dùng `vetc-api-design` hoặc `vetc-planner`
+- Khi cần validate logic với BA/PO trước khi code
+
+## Do NOT Activate When
+
+- Requirement đã rất rõ ràng, có spec chi tiết → dùng `vetc-planner` trực tiếp
+- Bug fix đơn giản, không cần spec → dùng `vetc-systematic-debugging`
+- Chỉ refactor code, không thêm feature mới
+- Đang implement code theo spec đã approved → dùng `vetc-java-patterns` hoặc `vetc-frontend-patterns`
+- Task quá nhỏ (< 1 giờ) → code trực tiếp, không cần spec
+
+## Feature Directory Convention
+
+Mỗi feature có thư mục riêng để persist artifacts:
+
+```
+specs/{NNN}-{slug}/
+├── spec.md           ← Structured Spec (output của skill này)
+├── api-design.md     ← từ vetc-api-design
+├── plan.md           ← từ vetc-planner
+├── tasks.md          ← task list chi tiết
+├── state.md          ← feature state tracking (lifecycle)
+├── checklists/       ← từ vetc-spec-quality
+│   ├── ux.md
+│   ├── security.md
+│   └── api.md
+
+## Spec Lifecycle (từ OpenSpec)
+
+Specs có lifecycle rõ ràng — không phải static document:
+
+| Phase | Status | Description |
+|-------|--------|-------------|
+| DRAFT | `spec.md` mới tạo | Chưa review, có thể thay đổi tự do |
+| PROPOSED | Spec đã được clarify | Đã qua deep-interview hoặc socratic clarification |
+| APPROVED | Plan đã được ralplan approve | Locked — changes cần delta spec |
+| IMPLEMENTING | Ralph đang implement | Spec là source of truth, code follows |
+| APPLIED | Implementation done + verified | Spec merged vào codebase-spec |
+| ARCHIVED | Feature shipped | Delta changes merged, spec đóng |
+
+**State transitions:**
+```
+
+# State: {Feature Name}
+## Lifecycle Phase: DRAFT
+## Last Updated: [date]
+## Changes: [list of delta changes applied]
+```
+
+## Delta Spec Convention
+
+See: `./(see docs)`
+
+## How It Works
+
+### Step 0 — Risk Checklist (bắt buộc)
+
+Trước khi bắt đầu spec, chạy risk checklist để xác định lane:
+
+| Flag | Touches |
+|------|---------|
+| Auth | JWT, Smart OTP, session, refresh token |
+| Authorization | Role, permission, wallet ownership |
+| Data model | Oracle DDL, JPA entity, migration |
+| Audit/security | Audit log, CCCD, balance |
+| External systems | Bank GW, eKYC provider, payment gateway |
+| Public contracts | REST API shape, ResultResp |
+| Cross-module | >1 domain changes |
+| Existing behavior | Code đã test/covered |
+| Weak proof | Khu vực chưa có test |
+
+### Step 1 — Socratic Clarification
+
+Hỏi tối đa 5 câu tập trung:
+- **Actor**: ai thực hiện? (customer, agent, admin, system, external service)
+- **Happy path**: luồng chính là gì?
+- **Failure modes**: điều gì xảy ra khi thất bại? (timeout, duplicate, insufficient balance)
+- **Business constraints**: giới hạn tiền? thời gian? role? frequency?
+- **Integrations**: hệ thống nào liên quan? (ACS, Bank GW, eKYC, ...)
+
+### Step 2 — Structured Spec Output
+
+Ghi vào `specs/{NNN}-{slug}/spec.md`. See template: `./(see docs)`
+
+## [NEEDS CLARIFICATION] Rules
+
+1. **Max 3 items** — không hơn. Mọi thứ khác → Assumptions (informed guess).
+2. **Priority order**: scope > security > UX > technical.
+3. **Format**: câu hỏi + options table + recommended option với reasoning.
+4. **Resolution**: user chọn option → update spec, move to Assumptions hoặc Accepted.
+
+```markdown
+- [NEEDS CLARIFICATION-01] (scope): Timeout QR payment bao lâu?
+  → Options:
+    A) 5 minutes (chuẩn VNPAY) — Recommended: phổ biến nhất
+    B) 15 minutes (thân thiện hơn)
+
+

package/skills/vetc-spec-quality/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: vetc-spec-quality
+description: PROACTIVELY activate sau khi tạo spec — validate spec quality như "Unit Tests for English". Kiểm tra Completeness, Clarity, Consistency, Measurability, Coverage. Dùng sau vetc-spec-driven hoặc vetc-deep-interview, trước vetc-planner.
+---
+
+# VETC Spec Quality — "Unit Tests for Requirements"
+
+Checklists test **REQUIREMENTS QUALITY**, NOT implementation. Giống unit tests nhưng cho English text.
+
+## When to Activate
+
+- Sau khi `vetc-spec-driven` hoặc `vetc-deep-interview` tạo spec
+- Trước khi `vetc-planner` tạo implementation plan
+- Khi review spec từ BA/PO
+- User nói: "check spec", "validate requirements", "spec quality"
+- Trước `/vetc-ship` — spec quality gate
+
+## Do NOT activate when
+
+- Chưa có spec file → dùng `vetc-spec-driven` trước
+- Đang implement code → dùng `vetc-verify` thay
+- Chỉ cần syntax/formatting → manual review đủ
+
+## Core Concept
+
+```
+WRONG:  "Verify button clicks work correctly"     ← tests implementation
+RIGHT:  "Are click requirements defined?"          ← tests requirements quality
+
+WRONG:  "Test API returns 200"                     ← tests code behavior
+RIGHT:  "Is API success criteria specified?"       ← tests spec completeness
+```
+
+## 5 Quality Dimensions
+
+| Dimension | What It Tests | Threshold |
+|-----------|---------------|-----------|
+| **Completeness** | Có thiếu thông tin quan trọng không? | ≥80% items addressed |
+| **Clarity** | Có ambiguity hoặc vague language không? | No unresolved ambiguity |
+| **Consistency** | Có mâu thuẫn giữa các sections không? | 0 contradictions |
+| **Measurability** | Success criteria có measurable không? | All criteria measurable |
+| **Coverage** | Mọi aspect của feature được cover chưa? | ≥80% traceability |
+
+## Checklist Categories
+
+### Category 1: Functional Completeness
+
+```markdown
+## CHK-101: Actor Identification
+- [ ] Are ALL actors identified? [Spec §2]
+- [ ] Is each actor's role clear? [Spec §2]
+- [ ] Are actor permissions defined? [Spec §2]
+
+## CHK-102: Happy Path Coverage
+- [ ] Is the primary flow described step-by-step? [Spec §4]
+- [ ] Does each step have a clear actor and action? [Spec §4]
+- [ ] Are preconditions stated? [Spec §4]
+
+## CHK-103: Edge Case Coverage
+- [ ] Are error scenarios listed? [Spec §5]
+- [ ] Is each edge case tied to a trigger + expected behavior? [Spec §5]
+- [ ] Are timeout/retry scenarios covered? [Spec §5]
+
+## CHK-104: Scope Boundaries
+- [ ] Is in-scope explicitly listed? [Spec §2]
+- [ ] Is out-of-scope explicitly listed? [Spec §2]
+- [ ] Are non-goals stated? [Spec §2]
+```
+
+### Category 2: Clarity & Precision
+
+```markdown
+## CHK-201: Language Precision
+- [ ] Are there vague words ("fast", "good", "simple", "easy")? [Spec §all]
+- [ ] Are all terms defined or commonly understood? [Spec §all]
+- [ ] Are ambiguous requirements marked [NEEDS CLARIFICATION]? [Spec §12]
+
+## CHK-202: Measurable Success Criteria
+- [ ] Are success criteria measurable (not subjective)? [Spec §6]
+- [ ] Are criteria technology-agnostic? [Spec §6]
+- [ ] Are criteria user-focused (not developer-focused)? [Spec §6]
+
+## CHK-203: Acceptance Criteria Quality
+- [ ] Are Gherkin scenarios complete (Given/When/Then)? [Spec §7]
+- [ ] Does each scenario test ONE behavior? [Spec §7]
+- [ ] Are negative scenarios included? [Spec §7]
+```
+
+### Category 3: Consistency
+
+```markdown
+## CHK-301: Internal Consistency
+- [ ] Do edge cases align with happy path? [Spec §4 vs §5]
+- [ ] Do acceptance criteria match user scenarios? [Spec §3 vs §7]
+- [ ] Do data model hints match API contract sketch? [Spec §9 vs §10]
+
+## CHK-302: VETC Domain Consistency
+- [ ] Are VETC integrations correctly referenced? [Spec §10]
+- [ ] Do business rules match VETC constraints? [Spec §5]
+- [ ] Are sensitive data handling rules consistent? [Spec §5, §8]
+```
+
+### Category 4: Security & Compliance
+
+```markdown
+## CHK-401: Security Requirements
+- [ ] Are authentication requirements stated? [Spec §2, §10]
+- [ ] Are authorization rules defined per actor? [Spec §2]
+- [ ] Is sensitive data identified and handling specified? [Spec §5, §9]
+- [ ] Are PII fields listed with masking rules? [Spec §9]
+
+## CHK-402: VETC-Specific Security
+- [ ] Is OTP handling specified (if applicable)? [Spec §4, §5]
+- [ ] Are amount limits defined? [Spec §5, §7]
+- [ ] Are transaction idempotency requirements stated? [Spec §4]
+- [ ] Is audit logging requirement stated? [Spec §14]
+```

package/skills/vetc-systematic-debugging/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: vetc-systematic-debugging
+description: PROACTIVELY activate khi gặp bug, runtime error, build failure, hoặc unexpected behavior. 4-phase root cause analysis — KHÔNG fix trước khi có root cause. "3+ fixes failed = architectural problem."
+---
+
+# VETC Systematic Debugging — 4-Phase Root Cause Analysis
+
+Debug có hệ thống. Không guess-and-check. Tìm root cause TRƯỚC khi fix.
+
+
+
+## When to Activate
+
+- Runtime error, exception, stack trace
+- Build failure (compile, test, package)
+- Unexpected behavior (wrong data, wrong response, wrong state)
+- Performance degradation
+- User reports: "không work", "lỗi", "sai data"
+- Sau khi `vetc-build-resolver` diagnose nhưng cần deeper analysis
+
+## Do NOT Activate When
+
+- Build error đơn giản (missing import, syntax error) → dùng `vetc-build-resolver`
+- Bug đã biết root cause, chỉ cần fix → implement trực tiếp
+- Lỗi chỉ cần đọc error message là hiểu → không cần 4-phase process
+- Task không liên quan debugging (implementation, refactoring, review)
+
+## Rationalization Prevention
+
+| Thought | Reality |
+|---------|---------|
+| "I know what the bug is, let me just fix it" | You think you know. Prove it with evidence. |
+| "Let me try this fix and see if it works" | That's guessing, not debugging. Investigate first. |
+| "The error message tells me everything" | Error messages describe symptoms, not root causes. |
+| "I'll add a try-catch to handle it" | Hiding the error ≠ fixing the error. |
+| "It works on my machine" | Then something in the environment differs. Find what. |
+| "This is probably a timing issue" | "Probably" is not a root cause. Reproduce it reliably. |
+| "Let me restart the service" | Restarting masks the symptom. The bug will return. |
+| "The tests are flaky, ignore them" | Flaky tests reveal real race conditions. Fix them. |
+
+## Phase 1: Root Cause Investigation
+
+**Goal:** Understand WHAT happened and WHERE.
+
+### Step 1.1 — Reproduce
+
+- Reproduce the error reliably (not "sometimes")
+- Note exact steps to trigger
+- Check: does it reproduce in dev? staging? only prod?
+
+```bash
+# Reproduce backend error
+mvn test -Dtest=XxxServiceImplTest#testSpecificCase -q
+
+# Reproduce frontend error
+npm test -- --testPathPattern=XxxComponent
+
+# Check recent changes
+git log --oneline -20
+git diff HEAD~5 --stat
+```
+
+### Step 1.2 — Read the Error
+
+- Full stack trace, not just first line
+- Error message → error code → HTTP status
+- Which layer threw it? (Controller / Service / Repository / External)
+
+```
+Error: NullPointerException
+  at WalletServiceImpl.transfer(WalletServiceImpl.java:145)  ← HERE
+  at WalletController.handleTransfer(WalletController.java:67)
+  at sun.reflect.NativeMethodAccessorImpl.invoke0(Native)
+```

package/skills/vetc-tdd/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: vetc-tdd
+description: PROACTIVELY activate khi viết test cho service/controller/component mới, fix regression, hoặc khi cần tăng coverage. JUnit + Mockito + WireMock + RestAssured. Target 80%+ coverage.
+---
+
+# VETC Test-Driven Development
+
+Viết test trước implementation. Test từ Spec → code đúng ngay lần đầu.
+
+## When to Activate
+
+- Viết test cho service, controller, hoặc component mới
+- Fix regression — thêm test trước khi sửa bug
+- Code review yêu cầu thêm test
+- Cần boost coverage
+
+## Do NOT Activate When
+
+- Spike/prototype code (chưa cần test) → nhưng phải add tests trước khi merge
+- Config files, documentation changes → không cần unit test
+- Hotfix khẩn cấp (fix trước, add test ngay sau) → nhưng PHẢI add test trong cùng PR
+- Chỉ sửa styling/CSS, không affect logic
+
+## Rationalization Prevention
+
+See: `./(see docs)` (11 common TDD rationalizations and why they're wrong)
+
+## Good vs Bad Test Patterns
+
+```java
+// GOOD: Test name describes behavior, not implementation
+@Test
+public void givenInsufficientBalance_whenTransfer_thenThrowWithCorrectErrorCode() {
+    // Arrange
+    Wallet wallet = Wallet.builder().balance(BigDecimal.ZERO).build();
+    when(walletRepo.findByUserId(USER_ID)).thenReturn(Optional.of(wallet));
+
+    // Act & Assert
+    assertThatThrownBy(() -> service.transfer(transferRequest))
+        .isInstanceOf(CustomizeException.class)
+        .hasFieldOrPropertyWithValue("errorCode", "INSUFFICIENT_BALANCE");
+
+## Testing Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Testing private methods | Breaks on refactor | Test through public API |
+| Mocking what you own | Couples test to impl | Use real instances or fakes |
+| `verify(mock).call()` everywhere | Over-specified mocks | Only verify interactions that matter |
+| `Thread.sleep()` in tests | Flaky, slow | Use `awaitility` or `assertEventually` |
+| Ignoring test failures | False confidence | Fix the test, fix the code, or delete the test |
+| Snapshot testing everything | Brittle, meaningless | Snapshot only stable output (contracts) |
+
+## VETC Test Infrastructure
+
+```
+Backend:
+  JUnit 4 hoặc 5 (detect từ pom.xml)
+  Mockito — mock dependencies
+  Spring Boot Test — integration slice
+  RestAssured — HTTP testing
+  WireMock — mock external services (port 8488)
+  AssertJ — fluent assertions
+
+Frontend:
+  Jest + React Testing Library
+  @testing-library/jest-dom
+  User-event — simulate interactions
+```
+
+## Goal Transformation (từ Karpathy)
+
+Trước khi bắt đầu TDD, biến task mơ hồ thành verifiable goals:
+
+| Imperative Task | Verifiable Goal |
+|----------------|-----------------|
+| "Add validation" | "Write tests cho invalid inputs, then make them pass" |
+| "Fix the bug" | "Write a test reproduces the bug, then make it pass" |
+| "Add error handling" | "Write tests cho mỗi error scenario trong spec, then handle" |
+| "Refactor X" | "Tests hiện tại vẫn pass sau khi refactor" |
+| "Improve performance" | "Benchmark trước/sau: Xms → Yms, tests vẫn pass" |
+
+**Multi-step Verification Plan** (cho mỗi task):
+```
+1. [Step] → verify: [check]
+
+## TDD Workflow
+
+```
+RED   → Write failing test (từ Spec acceptance criteria)
+         SEE IT FAIL — confirm failure reason is correct
+GREEN → Write MINIMAL implementation để pass test
+         No gold-plating. No "might need later."
+REFACTOR → Clean up, verify coverage ≥ 80%
+           Run ALL tests after refactor. Every time.
+```

package/skills/vetc-thinking-pm/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: vetc-thinking-pm
+description: PROACTIVELY activate khi BA gửi file Word/PDF/Jira/BRD cần chuẩn hóa, hoặc khi có tài liệu đối tác cần tích hợp. Biến tài liệu đa dạng thành raw-ba-requirements.md chuẩn. Dùng trước vetc-analyze-ba.
+---
+
+# VETC Thinking Like Product Manager
+
+Chuẩn hóa mọi loại tài liệu BA thành `raw-ba-requirements.md` — format chuẩn, sẵn sàng cho `vetc-analyze-ba`.
+
+## When to Activate
+
+- BA gửi file Word/PDF/text/Jira, cần chuẩn hóa trước khi phân tích
+- Có tài liệu đối tác (partner API docs, sequence diagrams) cần tích hợp với yêu cầu nội bộ
+- Cần làm rõ scope, phân biệt "đối tác làm gì" vs "hệ thống VETC sẽ làm gì"
+- User paste text requirement trực tiếp vào chat (không có file)
+- Trước khi chạy `vetc-analyze-ba`
+
+## Do NOT Activate When
+
+- Requirement đã rõ ràng, có spec chi tiết → dùng `vetc-analyze-ba` hoặc `vetc-spec-driven`
+- Chỉ implement theo spec sẵn có → dùng `vetc-java-patterns` hoặc `vetc-frontend-patterns`
+- Bug fix không cần phân tích requirement
+- Code review, không phải requirement analysis
+
+## Thứ tự dùng
+
+```
+1. vetc-analyze-codebase   (1 lần cho project — tạo codebase-spec.md)
+2. vetc-thinking-pm        (chuẩn hóa input BA)  ← skill này
+3. vetc-analyze-ba         (phân tích + implement 13 bước)
+```
+
+## Cấu trúc thư mục
+
+```
+design/thinking/{feature-name}/
+├── source/      ← user bỏ file vào đây (Word, PDF, YAML, text...)
+├── converted/   ← AI đọc từ đây (chạy convert-file source/ để tạo)
+│   ├── partner_*.md    ← tài liệu đối tác (API spec, sequence flow)
+│   └── internal_*.md   ← tài liệu nội bộ (requirements, notes)
+└── raw-ba-requirements.md  ← OUTPUT
+```
+
+**Quy ước đặt tên:**
+- `partner_{mô-tả}.ext` — tài liệu từ đối tác/third party
+- `internal_{mô-tả}.ext` — tài liệu nội bộ VETC
+
+## Workflow (5 Phases)
+
+### Phase 0 — Chuẩn bị
+
+**Mode A — File-based (có Word/PDF):**
+1. Parse feature name từ command argument (kebab-case)
+2. Kiểm tra `design/thinking/{feature}/converted/` tồn tại
+3. List files trong converted/, phân loại `partner_*` vs `internal_*`
+4. Nếu `converted/` chưa có → hướng dẫn convert:
+   - Dùng pandoc: `pandoc source/spec.docx -o converted/internal_spec.md`
+   - Hoặc dùng công cụ convert khác, đặt output vào `converted/`
+
+**Mode B — Direct Text (không có file):**
+1. User paste text requirement trực tiếp → skip Phase 0-1 file scanning
+2. Coi toàn bộ text là `internal_*` source
+3. Tiếp tục từ Phase 2 (Phân tích)
+
+### Phase 1 — Thu thập
+- Đọc file `.md`, `.txt` từ `converted/` (gắn nhãn Partner/Internal theo prefix)
+- Parse `.yaml/.yml` (OpenAPI) → paths, schemas; phân biệt API đối tác vs API dự kiến nội bộ
+- Parse `.puml` (PlantUML) và `.mmd/.mermaid` → actors, flows
+- Gộp nội dung, gắn mỗi phần với Source (`converted/{file}:{line_range}`)
+
+### Phase 2 — Phân tích
+- Tách REQ, BR, AC, UC từ mọi nguồn
+- Mỗi mục phải có Source — KHÔNG đoán, KHÔNG suy diễn không có nguồn
+- Ánh xạ REQ ↔ AC ↔ UC
+- Phân loại delta: ADDED / MODIFIED / REMOVED
+- Xác định GAPs — thiếu thông tin, mâu thuẫn, mơ hồ
+- Từ `internal_*`: rút ra "góc nhìn hệ thống VETC sẽ làm" (product deliverables, system responsibilities)
+- Từ `partner_*`: suy ra API/luồng dự kiến hệ thống ta sẽ build
+
+### Phase 3 — Chuẩn hóa (OpenSpec + spec-kit schema)
+Điền vào template `../../templates/raw-ba-requirements-template.md`:
+
+| Section | Schema nguồn | Nội dung |
+|---------|-------------|---------|
+| 0. Execution Log | — | Ghi lại từng Phase đã làm |
+| 1. Context | OpenSpec | Why, What Changes, Impact |
+| 1b. System View | Internal | Hệ thống VETC sẽ làm gì, out of scope |
+| 2. Capabilities | OpenSpec | New/Modified capabilities |
+| 3. User Stories | spec-kit | Priority P1/P2/P3, Given/When/Then |
+| 4. Requirements | Cả hai | REQ với delta ADDED/MODIFIED/REMOVED |
+| 5. Business Rules | Cả hai | BR với Source |
+| 6. Scenarios | OpenSpec | WHEN/THEN format |
+| 7. Acceptance Criteria | Cả hai | AC map REQ/UC |
+| 8. Data/API | API draft | Partner APIs + Planned Internal APIs |
+
+### Phase 4 — Validation
+- Checklist: User stories có Priority + Given/When/Then?
+- Mọi AC map tới REQ/UC?
+- Error scenarios đã liệt kê?
+- Mọi mục có Source?
+
+### Phase 5 — Output & Handoff
+1. Ghi `design/thinking/{feature}/raw-ba-requirements.md` (bao gồm Execution Log)
+2. Dừng → chờ user review
+3. Sau user confirm → hỏi: "Sẵn sàng move sang `specs/features/{feature}/`?"
+4. Dừng → chờ confirm
+5. Khi user confirm → copy file (đề xuất lệnh trước khi thực thi)
+
+## Anti-Hallucination Rules (BẮT BUỘC)
+

package/skills/vetc-ui-visual-qa/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: vetc-ui-visual-qa
+description: PROACTIVELY activate khi implement/change React component, thay đổi styling, release candidate cho agency-portal hoặc ops-ui. Validate WCAG 2.2 AA, responsive, dark mode (nếu có), focus management, screen reader compatibility.
+---
+
+# VETC UI Visual QA — Accessibility + Visual Consistency
+
+Đảm bảo UI VETC (agency-portal, ops-ui) tuân thủ WCAG 2.2 AA, responsive (320px-1920px), focus management đúng, screen reader navigable. Không dừng ở "looks OK on my laptop".
+
+## When to Activate
+
+- Component mới implement — accessibility + visual sweep
+- Style change (color/font/spacing) — verify contrast & consistency
+- Form/input component — keyboard + SR navigation
+- Modal/dropdown/drawer — focus trap + escape handling
+- Release candidate — full a11y audit
+- Bug report: "screen reader can't read X" / "keyboard stuck"
+
+## Do NOT Activate When
+
+- Backend-only change — no UI
+- Internal tool with 1-2 users, no a11y requirement (still recommended but lower priority)
+- Component still WIP — wait for completion
+
+## WCAG 2.2 AA Checklist — VETC Focus
+
+### Perceivable (can users sense content?)
+
+- [ ] **Text contrast ≥ 4.5:1** for normal text, ≥ 3:1 for large text (≥24px or 18.66px bold)
+- [ ] **UI control contrast ≥ 3:1** (buttons, form borders, focus indicators) — WCAG 2.2 new
+- [ ] **No color-only info** (e.g., red = error must have icon + label too)
+- [ ] **Alt text on images** — `<img alt="...">`, `aria-label` on icon buttons
+- [ ] **Captions on videos** (if any)
+- [ ] **Resize to 200%** without loss of content/function
+- [ ] **Reflow at 320px** wide — no horizontal scroll (except tables/code)
+- [ ] **Text spacing** adjustable: line 1.5x, paragraph 2x, letter 0.12x, word 0.16x
+
+### Operable (can users interact?)
+
+- [ ] **Keyboard accessible** — every interactive element reachable via Tab
+- [ ] **Visible focus indicator** — ≥ 3:1 contrast (WCAG 2.2)
+- [ ] **Focus not obscured** by sticky header/footer (WCAG 2.2 new)
+- [ ] **No keyboard trap** — Tab always moves forward, Shift+Tab backward
+- [ ] **Escape closes modal/dropdown** — restores focus to trigger
+- [ ] **Target size ≥ 24×24px** (WCAG 2.2 new, was 44×44 in 2.1)
+- [ ] **Skip link** to main content (for screen reader users)
+- [ ] **No auto-play** media without controls
+- [ ] **Enough time** — warn before session timeout (15min warning)
+
+### Understandable (can users comprehend?)
+
+- [ ] **Language declared**: `<html lang="vi">`
+- [ ] **Form labels** — every input has visible label or `aria-label`
+- [ ] **Error messages** — identify field + describe fix (not "invalid")
+- [ ] **Help text** associated via `aria-describedby`
+- [ ] **Consistent navigation** — same menu position across pages
+- [ ] **Consistent identification** — same icon = same function everywhere
+- [ ] **Input suggestion on error** — "Amount must be between 1,000 and 10,000,000"
+
+### Robust (can assistive tech parse?)
+
+- [ ] **Valid HTML** — no duplicate IDs, proper nesting
+- [ ] **ARIA roles** where semantic HTML insufficient (`role="dialog"`, `role="tab"`)
+- [ ] **ARIA states/props** updated dynamically (`aria-expanded`, `aria-selected`)
+- [ ] **Status messages** announced — `role="status"` or `role="alert"` for async updates
+- [ ] **Name, Role, Value exposed** — every UI component testable via accessibility tree
+
+## VETC-Specific Checks
+
+### Ant Design / MUI Components
+
+- [ ] Use Ant Design 5.x+ (built-in a11y better than 4.x)
+- [ ] Don't override `tabindex` unless necessary
+- [ ] Custom icons must have `aria-label` or `aria-hidden="true"` (if decorative)
+- [ ] Modal `closable={true}` → Escape key works
+- [ ] Form.Item `label` prop provides label association
+
+### Vietnamese Text
+
+- [ ] Font supports Vietnamese diacritics (most modern fonts OK, but test: "Nguyễn", "Đặng", "Ớt")
+- [ ] No broken ligatures
+- [ ] Vietnamese locale for date/number formatters (`vi-VN`)
+- [ ] Long text (VN often 20% longer than EN) — no truncation in UI labels
+
+### Currency & Numbers
+
+- [ ] Use Intl.NumberFormat with `vi-VN` locale: `1.234.567 đ`
+- [ ] Thousand separator: `.` (VN standard), not `,`
+- [ ] Currency position: after amount (`100.000 đ`)
+- [ ] Never truncate currency (10,000,000 → "10M" loses precision)
+- [ ] Sign amounts clearly: debit `-100.000 đ` (red + minus), credit `+100.000 đ` (green + plus)
+
+### Sensitive Data
+
+- [ ] CCCD displayed partially masked by default: `001***999`
+- [ ] Phone partially masked: `0912***345`
+- [ ] Balance hidden until user clicks "Show" — for public terminals
+- [ ] No sensitive data in URL query string (visible in browser history)
+- [ ] No sensitive data in page title (visible in tab name)
+
+## Workflow
+
+### Step 1 — Static Check (axe-core)
+
+```bash
+# In dev mode, enable axe
+if (process.env.NODE_ENV === 'development') {
+  import('@axe-core/react').then(axe => axe.default(React, ReactDOM, 1000));
+}
+```
+
+Run dev server, open browser DevTools Console — axe reports violations.
+
+Or use CLI:
+```bash
+npx @axe-core/cli https://localhost:3000/wallet/transfer
+```