Kry Ux

/kry-ux — Đặc tả UX trước Plan

Skill này lấp khoảng trống lớn nhất giữa "ý tưởng đã rõ" và "code": hành vi sản phẩm chưa được đóng đinh. Biến business logic → UX spec đầy đủ mà AI hiểu và code không sai.

> Vị trí: idea → /kry-debrief → /kry-ux → /kry-plan → /kry-cook > /kry-ux chốt HÀNH VI (user muốn gì, màn nào, nút nào làm gì, kịch bản nào, trạng thái nào). /kry-plan chốt KỸ THUẬT (stack, file, phases). KHÔNG lẫn 2 việc.

📖 Doc phương pháp đầy đủ: docs/spec-template.html (phương pháp 6 Lớp) 📄 Template fork: docs/spec-template.html (8 trang A4 ngang, Mermaid render)

Triết lý gốc — Intent-driven (LUẬT CỨNG)

> Thấu hiểu = biết được khoảnh khắc và ý định (intent) của người ta lúc họ tương tác, chứ không phải mình muốn nói gì.

• Flow lấy intent làm gốc, KHÔNG lấy hệ thống làm gốc. Mỗi bước hỏi: ngay khoảnh khắc này user muốn gì, đang nghi ngờ/lo điều gì → đáp ứng nhanh nhất, ít suy nghĩ nhất.
• Chọn surface (modal/drawer/toast) = đáp ứng intent + tốc độ, KHÔNG phải thẩm mỹ. Chọn sai = không thấu hiểu user.

Nguyên tắc đếm (LUẬT CỨNG)

> Độ phủ không đến từ "nghĩ ra được bao nhiêu", mà từ liệt kê đối chiếu với một khung đếm được.

Luôn chạy Lớp 0 (đếm) TRƯỚC khi điền. KHÔNG brainstorm tới khi thấy "chắc đủ".

Bộ khung 6 Lớp

Lớp 0 · ĐẾM     → Actor×Goal + Entry points + CRUD matrix + decision-count + taxonomy
Lớp 1 · FLOW    → Intent Map: Mermaid flowchart + bảng (Khoảnh khắc·Intent·Đáp ứng·Nỗi nghi·Surface)
Lớp 2 · MÀN     → Screen inventory + CRUD matrix
   2b · SURFACES → modal/drawer/popover/toast/banner/tooltip/context-menu/cmd-palette/bottom-sheet
   2c · STATES   → mỗi màn × N state (empty/loading/error/no-permission/offline/partial)
Lớp 3 · ELEMENT → từng nút/input + enable/disable/ẩn + mở surface gì
Lớp 4 · AC      → Given-When-Then (mỗi ◇ ≥1 happy + 1 unhappy)
Lớp 5 · STATE   → state machine (Mermaid) + edge taxonomy 10 nhóm

Máy phát số lượng mỗi lớp:

| Lớp | Máy phát | |-----|----------| | 1 Flow | Actor × Goal (mọi vai × mỗi việc) + Entry points (web·email·QR·webhook·cron) | | 2 Màn | Node trong flow + CRUD matrix mỗi entity (List·Detail·Create·Edit) | | 3 Element | Quét cạn từng vùng: input·button·link·toggle·state | | 4 AC | Mỗi ◇ decision × 2 nhánh + mỗi action quan trọng | | 5 Edge | Taxonomy 10 nhóm: Rỗng·Loading·Lỗi·Quyền·Biên·Trùng/retry·Timeout·Mạng·Input bẩn·Đồng thời |

Quy tắc Page hay Surface: URL/Back/SEO → Page · giữ context màn nền → Drawer/Modal · chỉ báo kết quả → Toast · xác nhận nguy hiểm → Modal chặn.

Workflow

Bước 1 — Load context

1. Detect brand từ CWD (giống skills khác) + đọc CLAUDE.md folder nếu có.
2. Nhận business logic từ: argument, prompt output của /kry-debrief, hoặc file business logic bạn chỉ. Nếu folder có project code → đọc qua công cụ đọc codebase để hiểu hệ sẵn.
3. Restate lại business logic bằng từ của bạn để confirm hiểu đúng. Nếu logic còn mơ hồ → đẩy ngược về /kry-debrief, KHÔNG tự bịa.

Bước 2 — Đề xuất hướng triển khai

TRƯỚC khi viết spec, output 1 đề xuất ngắn (Context → hướng → trade-off):

📐 Hướng triển khai đề xuất cho [app]:

- **Actors:** [liệt kê vai từ Actor×Goal]
- **Flow chính:** [2-4 flow xương sống]
- **Entry points:** [web/email/QR/webhook/cron — cái nào áp dụng]
- **Độ phức tạp ước tính:** [N flow · M màn · ~K surface]
- **Rủi ro UX cần chú ý:** [1-2 chỗ dễ sai — vd async payment, real-time, permission]

Đây có đúng hướng không? Cần thêm/bớt actor hay flow nào trước khi tôi viết spec chi tiết?

Đợi bạn confirm hướng → mới sang Bước 3. (Tránh viết spec 8 trang sai hướng.)

Bước 3 — Viết UX spec detail (6 Lớp)

1. Fork docs/spec-template.html — KHÔNG build from scratch.
2. Điền lần lượt Lớp 0 → 5 cho app thật. Mỗi lớp:

• Chạy máy phát tương ứng để ra con số đầy đủ (không sót).
• Lớp 1 BẮT BUỘC có bảng Intent (Khoảnh khắc·Intent·Đáp ứng·Nỗi nghi) cho các bước quan trọng — đây là điểm khác biệt cốt lõi của kry-ux.
• Thiếu info ở lớp nào → DỪNG, hỏi bạn, KHÔNG tự giả định.

1. Spawn challenger-ux (agent giọng phản biện sắc bén (nguyên lý + gu)) — đào lỗ hổng state/edge/intent/permission mà nocode không nghĩ tới, chống bias từ lời bạn. Nhận ≥3 challenge → bổ sung spec. Lặp tới khi hết 🔴. (Thay cho self-critic — agent độc lập bắt được nhiều hơn.)
2. Comment header file ghi rõ: app name + archetype + ngày.

Bước 4 — Preview + deploy

1. Verify Mermaid render bằng Chrome headless (chrome.exe --headless=new --screenshot) — KHÔNG báo done nếu chưa thấy diagram render thật (rule UI craft).
2. Đẩy lên host tĩnh của bạn để preview.
3. Optional: lưu bản Markdown long-form ở nơi bạn chọn (tuỳ chọn).

Bước 5 — Hand off /kry-plan

Output prompt sạch cho /kry-plan, đính kèm link spec:

━━━ PROMPT CHO /kry-plan ━━━

/kry-plan "[app name] — build theo UX spec đã chốt tại [ URL].
Scope: [N flow · M màn]. Stack đề xuất: [để /kry-plan quyết].
Must-have từ spec: [3-5 điểm quan trọng]. KHÔNG làm: [scope creep]."

3 lựa chọn:
A · Copy prompt → gõ /kry-plan
B · Tôi gọi /kry-plan luôn
C · Sửa spec thêm trước khi plan

Anti-pattern — KHÔNG được làm

• ❌ Bỏ qua Lớp 0 (đếm) → nhảy thẳng vào vẽ flow → sót flow/màn/case
• ❌ Flow chỉ là "hộp màn" không có Intent → quay lại triết lý intent-driven
• ❌ Chốt stack/framework/file/DB schema — đó là việc /kry-plan, KHÔNG phải kry-ux
• ❌ Viết code — đó là /kry-cook
• ❌ Tự bịa edge case/business rule khi business logic chưa rõ → đẩy về /kry-debrief
• ❌ Báo done khi Mermaid chưa render thật (chỉ curl 200 / grep)
• ❌ Build HTML from scratch thay vì fork template
• ❌ Viết spec 8 trang trước khi bạn confirm hướng (Bước 2)
• ❌ Output English

Khi nào KHÔNG dùng /kry-ux

| Tình huống | Dùng | |-----------|------| | Business logic còn mơ hồ, chưa rõ làm gì | /kry-debrief trước | | App đã có spec rõ, chỉ cần plan kỹ thuật | /kry-plan thẳng | | Quick fix / 1 màn nhỏ không có nhiều state | /kry-cook | | Cần kiến trúc HỆ THỐNG (services, DB, infra) | doc kiến trúc hoặc /kry-diagram | | Chỉ cần sơ đồ đẹp để present | /kry-diagram |

Triggers

• "/kry-ux", "đặc tả UX", "spec UX", "UX spec", "logic flow"
• "user flow cho app", "thiết kế luồng", "flow mua hàng/đăng ký thế nào"
• "app này có những màn gì", "làm rõ màn hình/nút/kịch bản"
• "viết spec cho tool/app", "đóng đinh hành vi trước khi code"
• Sau /kry-debrief khi đã có business logic rõ nhưng chưa có UX spec

Quan hệ với family /kry-*

[Idea raw]
   ↓
/kry-debrief   ← Phase 0: làm rõ, hỏi ngược → prompt sạch
   ↓
/kry-ux        ← Phase 0.5: business logic → đề xuất hướng → UX spec 6 Lớp → preview
   ↓
/kry-plan      ← Phase 1: plan kỹ thuật (stack, file, phases)
   ↓
/kry-cook      ← Phase 2: execute
   ↓
/kry-qc        ← Phase cuối: QC trước done

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dangpm
• Source: dangpm/kry-build-pipeline
• License: MIT

Install and usage instructions live in the source repository linked above.