rich-elicitation

# Rich Elicitation Skill

## Overview

This skill governs how Antigravity resolves task ambiguity before starting work. When a user's request has too many unanswered dimensions — each with several reasonable answers — Antigravity asks targeted clarifying questions across multiple rounds rather than silently picking defaults.

The goal is a correct first draft, not a generic answer that requires three revision cycles. Rounds are capped at three; anything still unclear after Round 3 gets a stated assumption and Antigravity proceeds.

---

## When to Use This Skill

- Use when a request has 2 or more dimensions that are ambiguous and each has 3+ viable options
- Use when the user's likely intent is unclear across scope, audience, tone, format, or strategy
- Use when an early answer would meaningfully change the structure or direction of the output
- Use when working on writing, planning, design, recommendations, or creative tasks with open-ended scope
- Use when a Round 1 answer unlocks a new set of meaningful choices that need resolving before proceeding

Do **not** trigger for:
- Simple factual lookups or math
- Clearly scoped requests with a single obvious interpretation
- Minor unknowns where a safe default exists

---

## How It Works

### Step 1: Run the Trigger Checklist

Before starting any task, mentally check how many of these apply:

| Signal | Action |
|---|---|
| Multiple valid output formats | Ask about format |
| Audience is unknown | Ask about audience |
| Tone is ambiguous | Ask about tone |
| Scope could be narrow or broad | Ask about depth/length |
| Technical vs. simple treatment unclear | Ask about technical level |
| Multiple strategic directions exist | Ask which direction |
| User's constraints are unknown | Ask about constraints |

**If 2+ rows apply → trigger this skill.**

### Step 2: Ask Round 1 Questions

Ask up to 3 questions using `ask_user_input_v0`. Group related questions in a single call. Lead with 1–2 sentences explaining why you're asking. Mark one option per question as **(Recommended)**.

### Step 3: Re-run the Checklist

After Round 1 answers, re-run the checklist on what's still unresolved. If 2+ rows still apply, run Round 2. Otherwise, proceed.

### Step 4: Run Follow-up Rounds (if needed)

| Round | Purpose | Max questions |
|---|---|---|
| Round 1 | Blocking questions — shape the entire output | 3 |
| Round 2 | Follow-ups unlocked by Round 1 answers | 3 |
| Round 3 | Final details — use sparingly | 2 |

Transition between rounds naturally. Don't announce "Round 2" mechanically. Use phrasing like:
> "Got it — that helps a lot. One more thing before I start:"

### Step 5: Proceed

After Round 3 (or earlier, if enough context exists), state any remaining assumptions briefly and begin the task.

---

## Examples

### Example 1: Multi-Round — Investor Pitch Deck

**User:** "Help me create a presentation for my project."

**Round 1** — Three blocking questions:

```
Framing: "This could go a lot of different ways. Quick questions before I start:"

Q1: Who is the audience?
  - Internal team / colleagues
  - External clients or partners
  - Investors or stakeholders (Recommended)
  - General / public audience

Q2: What's the primary goal?
  - Inform and update
  - Persuade and drive a decision (Recommended)
  - Teach or explain a concept
  - Pitch and raise funding

Q3: How much content do you already have?
  - Starting from scratch
  - Rough notes or an outline (Recommended)
  - Full draft — just needs polish
  - Previous version to update
```

*User answers: Investors | Pitch | Rough notes → Round 2 is warranted.*

**Round 2** — Unlocked by Round 1:

```
Framing: "Perfect — investor pitch it is. A couple more things:"

Q1: What stage is this raise?
  - Pre-seed / idea stage
  - Seed round (Recommended)
  - Series A or later
  - Strategic partnership / grant

Q2: How long should the deck be?
  - Short and punchy, 8–10 slides (Recommended)
  - Standard, 12–15 slides
  - Comprehensive, 20+ slides
```

*No Round 3 needed — proceed.*

---

### Example 2: Single-Round — Business Email

**User:** "Write a business email to follow up on a proposal."

**Round 1 only:**

```
Framing: "Two quick questions to nail the tone:"

Q1: What tone should this email strike?
  - Formal and professional (Recommended)
  - Friendly but direct
  - Urgent and firm
  - Warm and relationship-focused

Q2: What's the primary goal?
  - Request action / get a response (Recommended)
  - Share information only
  - Repair or maintain the relationship
  - Negotiate or push back
```

*Enough context. No Round 2 needed.*

---

## Best Practices

- ✅ Always mark one option per question as **(Recommended)**
- ✅ Lead with a 1–2 sentence framing before the question widget
- ✅ Group up to 3 related questions in a single `ask_user_input_v0` call
- ✅ Re-evaluate after each round — stop as soon as you have enough context
- ✅ Use `single_select` for mutually exclusive choices, `multi_select` when combinations are valid
- ✅ State remaining assumptions explicitly before proceeding after Round 3
- ❌ Don't ask 6 separate question calls when 2 grouped calls would do
- ❌ Don't mark two options as Recommended in the same question
- ❌ Don't use vague option labels like "Other" or "It depends" without elaborating
- ❌ Don't mechanically label rounds in the UI ("Round 1:", "Round 2:")
- ❌ Don't run a follow-up round for minor details that have safe defaults

---

## Limitations

- This skill does not validate whether the user's answers are internally consistent — it trusts them as given.
- Round structure is a guideline, not a rigid contract; judgment is required on when to stop.
- Works best with `ask_user_input_v0` — in environments without that tool, question quality may degrade.
- Does not handle tasks where ambiguity can only be resolved by fetching external information (e.g., reading a file the user hasn't uploaded).
- Not designed for real-time or high-latency-sensitive workflows where any question overhead is unacceptable.

---

## Security & Safety Notes

This skill is pure reasoning — it issues no shell commands, reads no files, makes no network requests, and mutates no state. Risk level is `none`.

No `npm run security:docs` review is required for this skill.

---

## Common Pitfalls

- **Problem:** Antigravity asks one good question, gets an answer, then proceeds without checking if new unknowns emerged.
  **Solution:** Always re-run the trigger checklist mentally after each round before deciding to proceed.

- **Problem:** All options in a question look equally valid so Antigravity marks none as Recommended.
  **Solution:** Pick the option that works for most users or is lowest-risk and mark it. "No preference" is rarely true.

- **Problem:** Antigravity runs 4+ rounds trying to eliminate every unknown.
  **Solution:** Hard cap at 3 rounds. After Round 3, state assumptions and proceed.

- **Problem:** Round 2 questions cover the same category as Round 1 (e.g., tone again).
  **Solution:** Each round should unlock new dimensions, not re-ask resolved ones.

---

## Related Skills

- `@ask-user-questions` — Single-round elicitation with recommended options. Use that skill for simpler tasks; use rich-elicitation when answers to early questions open up new meaningful choices.