discovery-question-form

Discovery question form

This atom defines the <question-form> 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 <question-form> 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 — <form-id>].

Activation boundary

• A first turn or new project does not by itself require a form.
• A discovery pipeline stage only makes this protocol available; declaring or entering the stage does not trigger a form.
• Missing metadata is not automatically a question. First use the request, conversation, plugin inputs, memory, active skill, and design system.
• 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 reference file if available",
      "type": "file",
      "required": false
    }
  ]
}
</question-form>