interactive-clarify

---
name: interactive-clarify
description: Use for every interaction where clarification is needed — enforces AskUserQuestion tool over plaintext questions for all requirement gathering and decision making
---

# Interactive Clarification

## Overview

When you need to ask the user anything, use the AskUserQuestion tool — NEVER dump plaintext questions. Users give short messages and want help figuring out what they need through interactive selection, not by reading and typing answers to a wall of text.

**Core principle:** Asking is a UI interaction, not a text dump. Make it easy to answer.

## The Rule

```
NEVER output questions as plaintext and expect the user to type answers.
ALWAYS use the AskUserQuestion tool with selectable options.
```

**No exceptions.** This applies to:
- Requirement gathering
- Design decisions
- Implementation choices
- Scope clarification
- Bug triage
- Any situation where you need user input

## How to Use AskUserQuestion

### Format Rules

1. **1-4 questions per call** — ask the most important questions first
2. **2-4 options per question** — cover the common cases
3. **Short header** (max 12 chars) — category label like "Stack", "Scope", "Auth"
4. **Concise labels** (1-5 words) — the choice itself
5. **Helpful descriptions** — explain what each option means
6. **Mark a recommended option** — add "(Recommended)" to the most likely choice
7. **"Other" is automatic** — users can always type custom input, don't add it

### Good vs Bad

**BAD — plaintext question dump:**
```
I have a few questions:
1. What stack would you like? (Go, Python, or both?)
2. Do you need authentication?
3. What kind of database schema?
4. Should I set up Docker?
5. Do you want CI/CD?
6. What about monitoring?
7. Any specific API patterns?
```

**GOOD — interactive with AskUserQuestion:**
```
AskUserQuestion with:
  Q1: "Which backend stack?" [Header: "Stack"]
    - "Go/Fiber (Recommended)" — Go backend with Fiber framework
    - "Python/FastAPI" — Python backend with FastAPI
    - "Both" — Separate Go and Python services

  Q2: "What's included in the MVP?" [Header: "Scope", multiSelect: true]
    - "Auth (JWT)" — User authentication and authorization
    - "CRUD API" — Standard resource endpoints
    - "Admin panel" — Admin-facing management UI
    - "Real-time" — WebSocket or SSE for live updates
```

### When to Use multiSelect

Use `multiSelect: true` when options are NOT mutually exclusive:
- "Which features do you want?" — can pick multiple
- "Which checks should run?" — can pick multiple

Use `multiSelect: false` (default) when options ARE mutually exclusive:
- "Which stack?" — pick one
- "What's the priority?" — pick one

### When to Use Previews

Use the `preview` field when users need to compare visual/code options:
- Different UI layouts (ASCII mockups)
- Different code patterns
- Different architecture diagrams

```
AskUserQuestion with:
  Q1: "Which response format?" [Header: "Format"]
    - "Envelope" — Wraps all responses in data/error envelope
      preview: |
        // Success
        { "data": { "id": "1", "name": "Alice" } }
        // Error
        { "error": { "code": "not_found", "message": "..." } }

    - "Flat" — Direct response without envelope
      preview: |
        // Success
        { "id": "1", "name": "Alice" }
        // Error (HTTP status only)
        404 Not Found
```

### Follow-Up Rounds

After the first round of answers, you may need to ask 1-2 more questions based on responses. This is fine — ask in rounds, not all at once.

```
Round 1: "What are you building?" + "Which stack?"
  → User picks "API service" + "Go"

Round 2: "Does it need auth?" + "What database operations?"
  → User picks "JWT auth" + "CRUD + search"

Now you have enough to start. Invoke skills.
```

**Max 3 rounds of questions.** If you need more than that, you're overcomplicating it.

## Decision Points During Work

When you encounter a decision during implementation (not just at the start):

```
AskUserQuestion with:
  Q1: "The users table needs a role system. Which approach?" [Header: "Roles"]
    - "Simple enum (Recommended)" — Single role per user (admin, member, viewer)
    - "Role-based (RBAC)" — Multiple roles with permissions table
    - "Attribute-based" — Fine-grained permissions on resources
```

**Don't silently make decisions** for things that affect the user's product. Use AskUserQuestion for:
- Schema design choices
- Auth strategy
- API design decisions
- Feature scope trade-offs
- Architecture decisions

**Do silently decide** for things that are engineering best practices:
- Using parameterized queries (always)
- Adding indexes (always)
- Writing tests (always)
- Using clean architecture (always)

## Chains

- **Used by:** `eng-lead` (orchestrator calls this for all clarification)
- **Used by:** Every skill that needs user input during execution
- **Replaces:** Plaintext questions everywhere

More agent context in vndee/engineering-skills

36 other files this repository gives its agents.