9 added, 4 removed. Audit A to A.
---
name: elicit
description: "Form-driven Socratic discovery — batch independent decision dimensions into one multi-select-capable form instead of N button-turns. Triggers on: scope this, discovery form, ask me everything at once, multi-select question."
---
# Elicit — form-driven Socratic discovery
**IMPORTANT: Start your response by telling the user:**
> **Elicit** — Gathering the independent dimensions of your decision
> as one form (multi-select where it fits), instead of asking one
> button at a time.
This skill turns a **declarative form** (data, not code) into a real
`AskUserQuestion` turn and validates the answers. It is the live wiring
of `attune.elicitation` via two MCP tools:
- `elicitation_render_form` — validate the form, get batched payloads.
- `elicitation_collect_response` — validate the answers (R4).
## When to render a multi-field form (the batching rule)
Batch 2–4 fields into **one** form-turn only when ALL hold:
- the fields are **independent dimensions of one decision** the user
makes together (e.g. spec kickoff: goal + scope + focus), AND
- answers **don't branch** on each other (if a field's relevance
depends on another's answer, stay sequential), AND
- each field is **genuinely ambiguous** — a dimension the user already
specified is omitted, not asked.
**Stay single-question** when only one dimension is unknown, a later
question depends on an earlier answer, or batching would feel like a
bureaucratic intake for a simple ask. The form never adds fields the
ordinary Socratic-ambiguity judgement wouldn't already ask.
## Step 0 — check the template library first (V7)
- Recurring fork classes are stored as named JSON templates
- (`src/attune/elicitation/templates/`). **Reach for a template before
- hand-building**: a reused template makes answers comparable across
- sessions (joinable on `FormResponse.template_id`).
+ Recurring fork classes are stored as named JSON templates in the
+ `attune_forms` package (`attune_forms/templates/` in the installed
+ wheel; new templates land in the attune-forms repo). **Reach for a
+ template before hand-building**: a reused template makes answers
+ comparable across sessions (joinable on `FormResponse.template_id`),
+ and from attune-forms 0.8.0 each cast is telemetry-tagged
+ `template:<name>` vs `dict` — the adoption signal is measured, so
+ hand-building a form a template already covers shows up in the log.
+ Check `list_templates()` first; only hand-build when nothing matches.
```python
from attune.elicitation import form_from_template, list_templates
form = form_from_template("session-contract", {"project": "attune-ai"})
# ... render, then collect with the join key:
response = collect_form_response(form, answers, template_id="session-contract")
```
Available templates:
| Name | Construct | Purpose | Slots |
|---|---|---|---|
| `session-contract` | intake-form | Session-start protocol: mode, outcome, done-when, effort cap | `project` |
Missing/extra slot values and malformed templates fail through the
same every-problem-listed `FormValidationError` a hand-built dict
gets. **Promote-on-repeat (R5):** a form earns templatehood on its
SECOND recurrence — no speculative templates.
## Step 1 — build the declarative form (D3)
A form is plain serializable data:
```json
{
"title": "Scope this work",
"description": "Optional one-liner",
"fields": [
{"id": "goal", "text": "What are you trying to accomplish?",
"type": "single_select",
"options": ["Fix a bug", "Add a feature", "Refactor", "Investigate"]},
{"id": "focus", "text": "Which areas matter here?",
"type": "multi_select",
"options": ["correctness", "security", "performance", "tests"]}
]
}
```
Field `type` is one of `single_select`, `multi_select`, `boolean`,
`text_input`, `number` (with `minimum`/`maximum`), `date` (ISO
`YYYY-MM-DD`), `textarea` (with `max_length`), or `decision` (see "The
decision construct" below). `id` is the stable key the answer comes back
under. The rich controls — `number`/`date`/`textarea` — render on the
native elicitation (`elicitation_ask`) and widget
(`elicitation_render_widget`) surfaces below, but degrade to plain text
on AskUserQuestion.
**List render (`list_style`).** On a `single_select` or `multi_select`,
set `"list_style": "ordered"` (numbered) or `"unordered"` (bulleted) to
render the options as the familiar intro-sentence-plus-list shape —
each item pickable by mouse or the `1`/`2`/`3` reply vocab — instead of
the default dropdown/checkboxes. Presentation only: the answer and its
validation are unchanged (it is **not** a separate construct — see
decisions.md D19). Only valid on the two select types.
## The decision construct (v3)
A `decision` is a presentation-enriched single-select: the agent offers
a **recommended** option with a **rationale** and per-option
**tradeoffs**, and the user picks one. Use it to *offer a choice*, not to
*gather intake* — it is the agent-to-user half of the grammar (the
constructs above gather input). See
`.claude/rules/attune/communication-grammar.md`.
Extra field keys (all optional):
- `recommended` — the option to badge "Recommended" and order first
(must be one of `options`).
- `rationale` — the "why this recommendation" callout shown beneath the
cards.
- `option_notes` — `{option: one-line tradeoff}` shown under each card.
```json
{
"title": "Focused session plan",
"fields": [
{"id": "approach", "text": "How should we spend this session?",
"type": "decision",
"options": ["Verifiable backlog loop", "Behind a verify gate",
"Non-LLM backlog"],
"recommended": "Verifiable backlog loop",
"rationale": "Building LLM features blind manufactures unverified work.",
"option_notes": {"Verifiable backlog loop": "Real progress now",
"Behind a verify gate": "Parked until the key returns",
"Non-LLM backlog": "Fully provable today"}}
]
}
```
**Surface:** the rich card layout (badge + tradeoffs + rationale) renders
on the **widget** surface (`elicitation_render_widget` → `show_widget`);
the answer is one selected option, validated like a single-select.
**AskUserQuestion fallback:** a `decision` maps to a `single_select` with
the recommended option ordered first and " (Recommended)" appended to its
label; fold each `option_notes` tradeoff into that option's
`description`, and use the `rationale` as the question's lead-in.
## The pushback construct (v4)
A `pushback` is a `decision` framed as **dissent**: the agent disagrees
with the user's stated approach and offers a concrete alternative. Use it
when a user-stated choice looks weaker than an alternative you can render
concretely — the decision-routine "pushback discipline". Same
single-select answer path as `decision`; only the framing differs. When
it fires is governed by
`.claude/rules/attune/decision-routine.md`.
Extra field keys (all optional; reuses the decision keys plus one):
- `user_position` — the option that is the user's stated approach; it is
tagged "your approach" (must be one of `options`).
- `recommended` — the agent's alternative; badged "I'd suggest instead"
and ordered first (must be one of `options`).
- `rationale` — the disagreement, shown beneath the cards under a "Why
I'd push back" header.
- `option_notes` — `{option: one-line tradeoff}` shown under each card.
```json
{
"title": "Retry strategy",
"fields": [
{"id": "retries", "text": "How should we handle transient failures?",
"type": "pushback",
"options": ["Fixed 3x retry", "Exponential backoff + jitter"],
"user_position": "Fixed 3x retry",
"recommended": "Exponential backoff + jitter",
"rationale": "Fixed retries hammer a struggling service; backoff is gentler and avoids a thundering herd.",
"option_notes": {"Exponential backoff + jitter": "Industry default"}}
]
}
```
**Surface:** the dissent card layout renders on the **widget** surface
(`elicitation_render_widget` → `show_widget`); the answer is one selected
option (overrule = the user's approach, switch = the alternative),
validated like a single-select.
**AskUserQuestion fallback:** a `pushback` maps to a `single_select` with
the agent's alternative ordered first; label the `user_position` option
clearly as the user's current approach, fold each `option_notes` tradeoff
into the matching option's `description`, and use the `rationale` (the
disagreement) as the question's lead-in.
## The progress construct (v5)
A `progress` is a **report**, not a fork: the agent reports a set of items
by status — `done` / `in_flight` / `blocked` — and surfaces the **blocked**
items as a single-select picker ("which blocker do you want to tackle?").
Use it to report where multi-step work stands while keeping the next move
one pick away. Same single-select answer path as `decision` (the answer is
one blocked item); when nothing is blocked it degrades to a pure status
display with no answer.
Extra field keys (all optional; reuses the decision keys plus one):
- `progress_items` — the reported items as `{label, status, detail?}` dicts,
`status` ∈ `done` / `in_flight` / `blocked`. **The blocked subset's labels
must equal `options`** (the picker offers exactly the actionable items);
`done`/`in_flight` items are reported but not pickable.
- `recommended` — the blocked item to suggest tackling first; badged
"suggested next" and ordered first (must be one of `options`).
- `rationale` — a one-line report summary, shown under a "Summary" header.
- `option_notes` — `{blocked-option: one-line detail}` shown under each card
(a blocked item's `detail` is used as a fallback note when absent).
```json
{
"title": "Spec execution",
"fields": [
{"id": "exec", "text": "Where execution stands", "type": "progress",
"options": ["T6 consumer wiring"],
"recommended": "T6 consumer wiring",
"rationale": "1 of 8 tasks blocked on a quality gate.",
"progress_items": [
{"label": "T1 model", "status": "done"},
{"label": "T3 widget", "status": "in_flight", "detail": "rendering cards"},
{"label": "T6 consumer wiring", "status": "blocked", "detail": "gate failed: score 42"}
]}
]
}
```
When nothing is blocked, set `options: []` and `required: false` — the
report renders as a status display with no picker.
### The "report" style (v5.1)
`"progress_style": "report"` renders a **neutral digest** instead of a
task report: item `status` is a free-form category tag (e.g. a memory
node type — no done/blocked semantics, no strikethrough), and `options`
may be **any subset** of item labels, offered as a "Pick one to go
deeper" picker (items not in `options` render as static tagged rows).
Pure presentation — the answer is still one selected option, validated
as a single-select. Set `required: false` when a pick is optional.
First consumer: the curated-memory recall digest
(`python -m attune.memory.recall_digest` renders the live Redis digest
as this form).
```json
{"id": "digest", "text": "Pull more on a topic?", "type": "progress",
"progress_style": "report", "required": false,
"options": ["Memory architecture"],
"progress_items": [
{"label": "Memory architecture", "status": "project context", "detail": "git + Redis"},
{"label": "Recall benchmarks", "status": "reference"}
]}
```
**Surface:** the three-bucket layout (static done/in_flight rows + the
blocked radiogroup picker) renders on the **widget** surface
(`elicitation_render_widget` → `show_widget`); the answer is the one
selected blocked item, validated like a single-select.
**AskUserQuestion fallback:** a `progress` folds the done/in_flight/blocked
summary into the question text and maps the **blocked** items to a
`single_select` with the `recommended` item ordered first. When there are
no blocked items there is nothing to ask — just narrate the report.
## Infer first — the highest-value thing you can do
Before you build the form, check what the conversation already answered.
A three-field ask where two are inferable is a one-field ask plus a
confirmation. This is the main defence against ceremony: forms feel
heavy when they re-ask what you already said, not when they are rich.
Set `default` to the value and `inferred_from` to why:
```json
{"id": "scope", "type": "single_select", "text": "Which path?",
"options": ["src", "tests"], "default": "src",
"inferred_from": "you have been editing src/"}
```
`inferred_from` without `default` is a definition error. Both surfaces
mark the value as a guess — the widget badges it, `AskUserQuestion`
folds it into help text — so a wrong inference is catchable.
**Infer, then confirm — never infer and skip.** When you can infer every
field, still render the form; it comes back as a one-tap confirmation
with a `Confirm` button. A correct-looking wrong guess the user never
saw is the only failure a form cannot recover from. Do not "save them a
turn" by acting on inferences silently.
Only infer what the conversation actually supports. A guess with no
basis is worse than a question, because it costs the user a correction
instead of an answer.
## Choosing a surface
**The widget is the default. `AskUserQuestion` is the fallback.**
(D21 — this reverses the earlier cheapest-surface-that-fits rule.)
Don't route on what the surface can technically express; route on how
much of the option space the user can see at once. Folding three
options and their tradeoffs into prose above a single-select turns a
scan into a serial read the user has to hold in their head — that loss
is real even though a control-type check can't see it.
`select_form_surface(form, widget_capable=…, keyboard_mode=…)` in
`attune.elicitation` is this rule in code. Call it instead of deciding
by hand. Precedence, highest first:
1. **Client can't render widgets** → `AskUserQuestion`. A constraint,
not a preference.
2. **A `number` / `date` / `textarea` field** → widget, always. These
have no `AskUserQuestion` control at all, so this outranks the
opt-out and the user can never silently lose a field.
3. **Keyboard mode on** → `AskUserQuestion`. The user's opt-out, set
with `attune config set keyboard_mode true` and persisted per project
in `attune.config.json`, with `ATTUNE_KEYBOARD_MODE` as a session
override. If a user says forms feel like too much, point them at that
command rather than arguing the default.
4. **Trivial form** → `AskUserQuestion`. Trivial is narrow and
mechanical: exactly one `single_select`/`boolean`, ≤3 options, and
no option label over 120 chars. A long label means tradeoffs got
folded into the text — that form wanted a card.
5. **Otherwise** → widget.
**Latency is not a reason to downgrade a form.** The extra tool call is
a real cost but it is not the axis; if a form is worth asking, it is
worth asking legibly. `needs_widget` still exists as the low-level
"does this lose fidelity on AskUserQuestion" check, but it no longer
owns the decision — don't route on it directly.
**After the answer comes back,** collapse the form rather than leaving
the rendered markup in the transcript: `form_response_summary(form,
response)` returns a few lines of markdown (title + one bullet per
answer). Use it in your narration so a long session accumulates
summaries, not screenfuls of HTML.
- **Rich / native — one call:** `elicitation_ask` renders the form as a
native MCP elicitation dialog (supports number/date/textarea +
multi-select with a structured return) and returns the validated
answers in a single call — no manual `AskUserQuestion` mapping. It
returns `{success: false, action: "unsupported"}` when the client
can't elicit. **Caveat (Claude Code, observed 2026-06-27, decisions
D10):** some clients advertise elicitation but **auto-decline form
requests without rendering** — you get `action: "decline"` and no
dialog. Treat a `decline` you didn't see the user make as
"surface unavailable" and fall back; don't report it as the user
saying no.
- **Rich / widget — `show_widget`:** `elicitation_render_widget` returns
inline HTML that renders ALL 7 controls richly (number spinner, date
picker, multi-line textarea, multi-select checkboxes). Pass its `html`
straight to `mcp__visualize__show_widget`; the user submits and the
widget posts the answers back (see "Widget surface" below). Best
rich surface on widget-capable clients (Cowork/claude.ai) when native
elicitation doesn't render.
- **Portable — AskUserQuestion:** steps 2–4 below map the form onto
`AskUserQuestion` (selects/booleans/short text only). Use this as the
fallback, or when you want the recommendation-first button UX.
## Step 2 — render it
Call `elicitation_render_form` with `{ "form": <the form> }`.
- Success → `{ "success": true, "batches": [[ <payload>, … ]] }`. Each
batch is one `AskUserQuestion` call (≤4 questions).
- Failure → `{ "success": false, "problems": [ … ] }`. Fix the form
definition and re-render; do not hand-roll the questions.
## Step 3 — ask, mapping each payload to AskUserQuestion
For each payload in a batch, build one `AskUserQuestion` entry:
| Payload field | AskUserQuestion |
| ------------- | --------------- |
| `question` | `question` |
| `type: "multi_select"` | `multiSelect: true` |
| `type: "single_select"` / `"boolean"` | `multiSelect: false` |
| `options` (list of strings) | `options: [{label, description}]` |
| `question_id` | track it — it keys the answer in step 4 |
Also:
- **header** — a short tag (≤12 chars) derived from the question.
- **recommendation-first** — if there's a sensible default, make it the
first option and end its label with " (Recommended)".
- **free text** — for a `text_input` field, offer any curated
suggestions as options; the user types anything via the built-in
**"Other"** escape `AskUserQuestion` always provides.
- **>4 options** — use the two-tier picker (category → item), don't
overflow a single question.
Then call `AskUserQuestion` with all the batch's entries at once. When a
batch has **more than one question**, set `metadata` to
`{"source": "elicit-form"}` — that marker is the deliberate opt-in the
one-question-per-turn guard requires for a §4 batched form. Without it,
a multi-question call is blocked (the default discipline). Multi-select
questions need no "(Recommended)" first option; single-select questions
still lead with the recommended choice.
## Step 4 — collect and validate (R4)
Assemble the answers into `{ field_id: value }` (a string for
single-select/boolean/text, a list of strings for multi-select), then
call `elicitation_collect_response` with `{ "form": <the form>,
"answers": <that map> }`.
- Success → `{ "success": true, "responses": { … } }`. Use those
values — they are validated against the form.
- Failure → `{ "success": false, "problems": [ … ] }` names exactly
which fields are missing-required or out-of-option. **Re-ask only
those fields** (a one-field form) — never silently proceed.
## Widget surface — `show_widget` round-trip
Use this instead of steps 2–4 when you want the rich controls on a
widget-capable client:
1. Call `elicitation_render_widget` with `{ "form": <the form> }`. On
success you get `{ "html", "title", "field_ids" }`; on a bad form,
`{ "success": false, "problems": [...] }` — fix and re-render.
2. Pass `html` verbatim to `mcp__visualize__show_widget`.
3. The user fills the form and submits. The widget posts a chat message
containing a fenced JSON block marked `__elicitation_response__`,
e.g. `{"__elicitation_response__": true, "title": "...", "answers":
{<field_id>: <value>}}` (multi-select → list, number → number,
date → `YYYY-MM-DD`, boolean → `"Yes"`/`"No"`).
4. When that message arrives, parse the JSON block and call
`elicitation_collect_response` with `{ "form": <the same form>,
"answers": <the payload's answers> }` to validate (R4). Re-ask only
the fields it flags as problems — never proceed on raw widget output.
## Worked example — `/attune` discovery in one turn
The headline use: the `/attune` scoping turn that today asks goal, then
scope, then focus as three sequential buttons. Gather them as one form
when each is genuinely open (drop any the user already stated):
```json
{
"title": "What do you want to do?",
"fields": [
{"id": "goal", "text": "What are you trying to accomplish?",
"type": "single_select",
"options": ["Run a workflow", "Manage memory", "Configure settings",
"Learn what attune does"]},
{"id": "scope", "text": "Where should it focus?",
"type": "text_input", "options": ["src/", "tests/", "whole project"]},
{"id": "concerns", "text": "Which concerns matter?",
"type": "multi_select", "required": false,
"options": ["security", "quality", "performance", "tests"]}
]
}
```
Render → ask (one `AskUserQuestion`, `concerns` as multi-select) →
collect → route on `responses["goal"]` (see the attune-hub skill's
routing table) scoped by `responses["scope"]` and `responses["concerns"]`.