discovery-question-form skill

Discovery question form

This atom defines the protocol. It does not decide whether clarification is required. Follow the active skill and core prompt's requirements-clarification policy. When they identify unresolved information that would materially change the design direction, content structure, or delivery format, surface the smallest possible set of questions that unblocks the workflow.

The questions are rendered as a artifact inline in the originating assistant message. This is assistant text parsed by the host, not a plugin GenUI surface or a native tool call. Submitted answers return as the next user message, beginning with [form answers — ].

Activation boundary

or entering the stage does not trigger a form.

• A first turn or new project does not by itself require a form.
• A discovery pipeline stage only makes this protocol available; declaring

conversation, plugin inputs, memory, active skill, and design system.

• Missing metadata is not automatically a question. First use the request,

• If enough information is available to proceed safely, do not emit a form.
• If a material blocker remains, ask only for that unresolved information.

Emission shape

Emit the form as a question-form block whose body is a JSON object with a top-level questions array. Do not emit a bare question object by itself; the renderer only recognizes the wrapped form contract.

The example below shows field shapes, not a fixed questionnaire. Include only unresolved questions and derive their recommendations from the actual brief; these example values are not fallback answers. A reference file remains unanswered until supplied.

<question-form id="discovery" title="Quick brief — 30 seconds">
{
  "description": "I'll lock these in before building. Skip what doesn't apply — I'll fill defaults.",
  "questions": [
    {
      "id": "audience",
      "label": "Who's the primary audience?",
      "type": "checkbox",
      "default": ["Customer"],
      "options": ["VC", "Customer", "Internal team"],
      "maxSelections": 2,
      "required": true
    },
    {
      "id": "format",
      "label": "Which format should I use?",
      "type": "radio",
      "default": "landscape",
      "options": [
        { "label": "Portrait", "value": "portrait" },
        { "label": "Landscape", "value": "landscape" }
      ]
    },
    {
      "id": "language",
      "label": "Which language should the promo use?",
      "type": "select",
      "default": "en",
      "options": [
        { "label": "Chinese", "value": "zh-CN" },
        { "label": "English", "value": "en" },
        { "label": "French", "value": "fr" },
        { "label": "German", "value": "de" },
        { "label": "Japanese", "value": "ja" },
        { "label": "Spanish", "value": "es" }
      ]
    },
    {
      "id": "reference",
      "label": "Add a r

Question object shape

Each entry in the top-level questions array uses:

number, range, date, time, datetime-local, color, url, email, tel, file, or switch.

• id: stable answer key, for example audience.
• label: user-facing question copy.
• type: one of radio, checkbox, select, text, textarea,

plugin inputs, and known context. Use an option's stable value for radio or select, an array of option values for checkbox, and concrete suggested text for free-text fields. String options use the exact option string as their value. Respect maxSelections; never substitute localized labels for stable values. The host also accepts the defaultValue alias; emit only one of these fields per question.

• default: the recommended answer inferred from the brief, project metadata,

Do not invent a missing fact or select the first option merely because it is first. A recommendation written only in description does not preselect an answer: encode it in the default field. Place that field before options so it arrives before a long option list during streaming.

• Prefill each non-visual question suitable for a recommendation; omit default only when no reasonable recommendation exists, such as a file upload.

allowed, or objects with localized label and stable value.

• options: required for choice controls; strings are

users can type their own answer instead of accepting only generated options. Set allowCustom: false only when the downstream system needs an exact machine id.

• At most 6-7 options per question; merge near-duplicates instead of listing more.
• Choose radio vs select by option count, not importance: radio for a short list, select once it runs long (languages, timezones, voices). checkbox is always a plain list.
• select options may carry group (first group expands, the rest collapse) and trailingLabel (a short end-of-row code such as ZH-CN). Both optional.
• Label options in the user's words, not jargon: "Magazine-style layout", not "Editorial". Reword only label; never change a stable value.
• Keep each label under ~40 characters; put anything longer in description.
• allowCustom: leave unset or set to true for finite-choice controls so

answer input.

• customLabel / customPlaceholder: optional localized copy for that custom

count.

• maxSelections: include this for checkbox controls with a limited selection

continue.

• required: set to true only when the answer is needed before work can

Convergence

The discovery atom completes when the next user message contains an answer for every required question. Treat those submitted answers as conversation context and do not ask the same questions again unless later input invalidates an answer.