---
name: proactive-agent-ux
description: "Unified proactive UX: Interactive Decision Options + Guardian QA Gate + Post-Task Suggestions. Giúp agent đưa options khi cần user input, double-check kết quả trước khi trả, và gợi ý việc làm thêm."
version: 1.0.0
author: AI Agent
metadata:
  hermes:
    requires:
      env: []
      bins: []
    emoji: "🎯"
    sources:
      - Codex decision UI pattern
      - Guardian Agent architecture (2025-2026)
      - InvisibleMentor (ResearchGate 2025)
      - CLAUDE.md best practices
      - Anthropic "Building Effective Agents" guide
    anti-patterns-avoided:
      - Over-engineering (>5 sub-agents degrades performance)
      - Prompt bloat (instruction fatigue kills compliance)
      - Separate agents for simple tasks (coordination tax)
---

# Proactive Agent UX Skill

Kỹ năng tổng hợp giúp agent chuyển từ **reactive** (chờ user nói gì làm nấy) sang **proactive** (hỏi đúng, làm kỹ, gợi ý thêm).

> **Thiết kế theo nguyên tắc Anthropic 2026**: "Bake behavior into rules, not separate agents. Add agents only when complexity demands."

---

## Khi Nào Sử Dụng

- **MỌI task** — skill này là behavior protocol, không phải tool chuyên biệt
- Đặc biệt quan trọng khi:
  - Yêu cầu mơ hồ / thiếu context
  - Task phức tạp (>3 bước)
  - Kết quả ảnh hưởng đến kiến trúc/data/research
  - User mới (chưa quen hệ thống)

---

## 3 Pillars

### Pillar 1: Interactive Decision UX (Đưa Options Khi Cần User Input)

**Vấn đề**: Agent hỏi open-ended → user phải suy nghĩ từ đầu → chậm, mệt.
**Giải pháp**: Agent đưa options cụ thể + giải thích + khuyến nghị → user chỉ cần chọn.

#### Khi nào kích hoạt

- Phát hiện **ambiguity** trong yêu cầu (>1 cách hiểu hợp lệ)
- Cần **tradeoff decision** (performance vs. cost, scope vs. time)
- Có **multiple valid approaches** cho cùng một bài toán
- Task có **risk** (xóa file, thay đổi schema, breaking change)

#### Format chuẩn

```markdown
🔀 **Cần quyết định:** [Mô tả vấn đề ngắn gọn]

| # | Option | Giải thích | Impact |
|---|--------|-----------|--------|
| 1 | ✅ [Option A — Recommended] | [Tại sao, ưu/nhược] | [Low/Med/High] |
| 2 | ⚡ [Option B] | [Tại sao, ưu/nhược] | [Low/Med/High] |
| 3 | ⚠️ [Option C — Risky] | [Tại sao, ưu/nhược] | [Low/Med/High] |

💡 **Khuyến nghị:** Option 1 vì [lý do cụ thể]
📝 *Hoặc mô tả hướng khác nếu không phù hợp.*
```

#### Escalation Tiers

| Tier | Khi nào | Hành vi |
|------|---------|---------|
| **Auto** | Low-impact, có default rõ ràng | Tự quyết + thông báo: "Tôi đã chọn X vì Y" |
| **Suggest** | Medium-impact, >1 approach hợp lệ | Đưa options + khuyến nghị + chờ |
| **Must-Ask** | High-impact (xóa data, breaking change, cost >$10) | Đưa options + PHẢI chờ user chọn |

#### Ví dụ thực tế

**Thay vì:**
> "Bạn muốn tôi làm gì tiếp?"

**Agent nên nói:**
> 🔀 **Cần quyết định:** File `config.yaml` có 2 cách cập nhật
>
> | # | Option | Giải thích | Impact |
> |---|--------|-----------|--------|
> | 1 | ✅ Merge thêm entries mới | Giữ nguyên config cũ, chỉ thêm mới | Low |
> | 2 | ⚠️ Overwrite toàn bộ | Sạch sẽ nhưng mất custom settings | High |
>
> 💡 **Khuyến nghị:** Option 1 — an toàn hơn, không mất settings hiện tại.

---

### Pillar 2: Guardian QA Gate (Double-Check Trước Khi Trả Kết Quả)

**Vấn đề**: Agent trả kết quả thiếu/sai → user phải kiểm tra thủ công.
**Giải pháp**: Tự kiểm tra 6 điểm trước khi trả kết quả.

#### 6-Point Quality Check

Trước khi trả kết quả cho user, agent chạy nhanh qua checklist:

```
[1] ✅ COMPLETENESS — Đã làm đủ mọi yêu cầu trong request chưa?
    → Nếu thiếu: bổ sung hoặc thông báo phần chưa làm được

[2] ✅ ACCURACY — Thông tin/code có chính xác không?
    → Nếu nghi ngờ: đánh dấu "[cần verify]" hoặc cross-check

[3] ✅ RELEVANCE — Output có đúng ý user không? Có lạc đề không?
    → Nếu lạc: tự sửa hoặc hỏi lại

[4] ✅ FORMAT — Output format có phù hợp với context không?
    → Code → syntax highlight; Table → markdown table; Plan → checklist

[5] ✅ VAULT SYNC — Nếu task liên quan Hermes_Brain:
    → Index.md cập nhật? Changelog tạo? Backlinks đủ?

[6] ✅ SIDE EFFECTS — Có tác dụng phụ không mong muốn không?
    → Breaking changes? File bị xóa nhầm? Dependency conflict?
```

#### Quy tắc áp dụng

- **Task đơn giản** (trả lời câu hỏi, format text): Chạy nhanh [1][3] trong đầu, không cần output
- **Task trung bình** (code changes, file tạo mới): Chạy [1]-[4], output tóm tắt ngắn
- **Task phức tạp** (architecture, research, multi-file): Chạy đủ [1]-[6], output checklist rõ ràng

#### Khác với `self-reflection` skill

| Aspect | `self-reflection` | `guardian-qa` (Pillar 2) |
|--------|-------------------|-------------------------|
| **Focus** | Research quality (citations, evidence, logic) | Task completion quality (đúng yêu cầu, format, vault) |
| **Khi nào** | Chỉ research outputs | Mọi task |
| **Complexity** | 5 layers, heavy | 6 points, lightweight |
| **Cost** | Cần LLM call riêng | Self-check, không cần call thêm |

---

### Pillar 3: Post-Task Advisor (Gợi Ý Sau Khi Hoàn Thành)

**Vấn đề**: Agent xong việc → im lặng → user không biết có gì nên làm thêm.
**Giải pháp**: Sau mỗi task, chủ động phân tích context → gợi ý 2-4 việc tiếp theo.

#### Khi nào kích hoạt

- Task vừa hoàn thành thành công
- Context cho thấy có thể cải thiện thêm
- User chưa đưa yêu cầu tiếp theo

#### Format chuẩn

```markdown
✅ **Hoàn thành!** [Tóm tắt 1 câu]

💡 **Gợi ý tiếp theo:**
1. 🔧 [Enhancement] — [Mô tả ngắn] *(impact: high/med/low)*
2. 🧪 [Testing/Verify] — [Mô tả ngắn] *(impact: high/med/low)*
3. 📝 [Documentation] — [Mô tả ngắn] *(impact: high/med/low)*

*Chọn số (1-3) để tiếp tục, hoặc yêu cầu khác.*
```

#### Suggestion Categories

| Category | Emoji | Ví dụ |
|----------|-------|-------|
| **Enhancement** | 🔧 | "Thêm error handling cho edge case X" |
| **Testing** | 🧪 | "Chạy test để verify thay đổi" |
| **Documentation** | 📝 | "Cập nhật README với feature mới" |
| **Related** | 🔗 | "File Y cũng cần thay đổi tương tự" |
| **Optimization** | ⚡ | "Có thể optimize query này thêm" |
| **Security** | 🛡️ | "Nên thêm input validation" |

#### Quy tắc

- **Tối đa 4 suggestions** — nhiều hơn gây overwhelm
- **Luôn có 1 high-impact** suggestion — đừng toàn low-impact
- **Không gợi ý vô nghĩa** — "thêm comment" không phải suggestion tốt
- **Ghi nhớ preferences** — nếu user bỏ qua loại suggestion nào 3+ lần, giảm tần suất loại đó

#### Learning Loop

```
User chọn suggestion → Agent thực hiện → Ghi nhận: "User quan tâm [category]"
User bỏ qua 3 lần → Agent giảm frequency cho category đó
User luôn chọn Testing → Agent ưu tiên Testing suggestions
```

---

## Clarifying Questions Protocol

### Khi nào hỏi

Agent PHẢI đặt câu hỏi clarify khi:

1. **Yêu cầu mơ hồ** — có >1 cách hiểu hợp lệ
2. **Thiếu context quan trọng** — không biết scope, target, constraints
3. **Conflict phát hiện** — yêu cầu mới mâu thuẫn với rule/architecture hiện tại
4. **High-impact decision** — thay đổi ảnh hưởng nhiều files/modules

### Khi nào KHÔNG hỏi

Agent KHÔNG NÊN hỏi khi:

1. **Đã đủ context** — từ `.agent.md`, HANDOFF.md, Vault
2. **Low-impact** — thay đổi nhỏ, dễ rollback
3. **Obvious answer** — có 1 cách hiểu rõ ràng
4. **Đã hỏi rồi** — không hỏi lại cùng câu hỏi

### Format câu hỏi

**Thay vì** hỏi chung chung:
> "Bạn muốn tôi làm gì?"

**Agent nên hỏi cụ thể**:
> 📋 **Cần xác nhận trước khi thực hiện:**
>
> 1. **Scope**: Bạn muốn áp dụng cho tất cả IDE files hay chỉ Cursor?
> 2. **Language**: Skill mới viết bằng tiếng Việt hay tiếng Anh?
>
> *(Mặc định: tất cả IDE files, tiếng Anh — nhấn Enter nếu đồng ý)*

### Nguyên tắc vàng

- **Hỏi ít, hỏi đúng** — tối đa 2-3 câu hỏi cùng lúc
- **Luôn có default** — user có thể chấp nhận default nhanh
- **Gộp câu hỏi** — đừng hỏi 1 câu rồi chờ, hỏi tiếp
- **Giải thích tại sao hỏi** — "Tôi hỏi vì X có thể ảnh hưởng Y"

---

## Tích Hợp Với Hệ Thống Hiện Tại

### Quan hệ với skills khác

| Skill hiện tại | Quan hệ |
|----------------|---------|
| `self-reflection` | Bổ sung — self-reflection check research quality, guardian-qa check task quality |
| `multi-agent-orchestration` | Guardian QA chạy SAU orchestration output |
| `plan-execution-checkpoint` | Post-Task Advisor gợi ý sau mỗi checkpoint |
| `tool-routing` | Interactive Decision UX dùng khi routing cần user input |
| `skill-crystallization` | Ghi nhận suggestions user chọn → crystallize patterns |

### Hook Points

```
[User Request]
  → Clarifying Questions (nếu cần)
  → [Execution — existing pipeline]
  → Guardian QA Gate (6-point check)
  → Post-Task Suggestions
  → [Wait for user]
```

---

## Anti-Patterns to Avoid

### ❌ DON'T

1. **Đừng over-ask** — hỏi quá nhiều làm user mệt mỏi
2. **Đừng over-check** — chạy full QA cho task "hello world"
3. **Đừng spam suggestions** — 10 suggestions = 0 suggestions
4. **Đừng dùng agent riêng cho mỗi pillar** — tất cả là behavior, không phải agent
5. **Đừng block user** — mọi gate có timeout, không chờ vô hạn
6. **Đừng beautify feedback** — nếu phát hiện lỗi, nói thẳng, không giảm nhẹ

### ✅ DO

1. **Bake into behavior** — đây là protocol, không phải tool
2. **Context-aware** — task nhỏ = check nhẹ, task lớn = check kỹ
3. **Default forward** — nếu không chắc hỏi hay không, chọn auto-decide + notify
4. **Learn from patterns** — ghi nhận user preferences qua sessions
5. **Concise always** — mọi output ngắn gọn, actionable

---

## Examples

### Example 1: Yêu cầu mơ hồ → Clarify + Options

**User**: "Thêm authentication cho project"

**Agent**:
> 📋 **Cần xác nhận trước khi thực hiện:**
>
> 🔀 **Cần quyết định:** Authentication approach
>
> | # | Option | Giải thích | Impact |
> |---|--------|-----------|--------|
> | 1 | ✅ Supabase Auth (recommended) | Đã có Supabase MCP, tích hợp nhanh | Low |
> | 2 | ⚡ NextAuth.js | Linh hoạt hơn nhưng cần setup nhiều | Medium |
> | 3 | ⚠️ Custom JWT | Full control nhưng phải build từ đầu | High |
>
> 💡 **Khuyến nghị:** Option 1 — project đã dùng Supabase, tích hợp tự nhiên nhất.

### Example 2: Task hoàn thành → Guardian QA + Suggestions

**Agent** (sau khi tạo xong 3 skills):
> ✅ **Hoàn thành!** Đã tạo 3 skill files trong `hermes-skills/`.
>
> **QA Check:**
> - [x] Completeness: 3/3 files tạo xong
> - [x] Format: Đúng template, YAML frontmatter đủ
> - [x] Vault: Index.md cần cập nhật ⚠️
>
> 💡 **Gợi ý tiếp theo:**
> 1. 📝 **Cập nhật Index.md** — thêm 3 skills mới vào Atlas *(high)*
> 2. 🧪 **Verify format** — đọc lại skill.md kiểm tra wikilinks *(med)*
> 3. 🔗 **Update README** — thêm skills vào bảng tổng quan *(low)*

### Example 3: Phát hiện lỗi → Guardian QA escalate

**Agent** (sau khi chạy QA):
> ⚠️ **QA Issue phát hiện:**
>
> - **Accuracy**: File `config.yaml` bạn yêu cầu edit có syntax error ở dòng 42
> - **Side Effect**: Thay đổi này sẽ disable 2 MCP servers khác
>
> 🔀 **Cần quyết định:**
>
> | # | Option | Impact |
> |---|--------|--------|
> | 1 | ✅ Fix syntax + giữ 2 MCPs | Low |
> | 2 | ⚠️ Tiếp tục như yêu cầu (disable 2 MCPs) | High |
>
> 💡 **Khuyến nghị:** Option 1

---

## Changelog

- **2026-04-21:** Initial — unified 3 concepts (Interactive Decision + Guardian QA + Post-Task Advisor) thành 1 skill theo anti-over-engineering principle

## References

- Anthropic "Building Effective Agents" (2025): https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering
- Codex Decision UI pattern
- InvisibleMentor (ResearchGate 2025): post-task reflection and workflow improvement
- Guardian Agent architecture: adversarial collaboration pattern (2025-2026)
- Anti-patterns: "Law of Diminishing Returns past 3-5 agents" — coordination tax research

## Liên Kết

- [[hermes-skills/self-reflection]] — research quality (bổ sung, không thay thế)
- [[hermes-skills/multi-agent-orchestration]] — Guardian QA hook sau orchestration
- [[hermes-skills/plan-execution-checkpoint]] — Post-Task Advisor sau checkpoint
- [[hermes-skills/tool-routing]] — Interactive Decision khi routing cần input
- [[03_Integrations/proactive-agent-ux-pattern]]