questionnaire

questionnaire

Batch the conversation's unresolved decisions into one HTML form; consume the markdown answers it emits. The answers file is the alignment contract — every question comes back as answered, open, or skipped-by-branching; nothing is silently dropped.

Workflow

1. Mine the discussion, notes, and memory for decisions still open, not topics. Points already settled go into intro as a "current understanding" summary — add one leading text question asking what in it is wrong, instead of re-asking each settled point.

2. Write questions.json (schema below), then build:

   python3 scripts/build.py questions.json -o alignment.html
   

3. Deliver: write the HTML somewhere the user can open it (project dir or scratchpad) and give them the path; in a remote/claude.ai session, publish it as an Artifact instead.

4. Consume: the page's Generate answers button emits markdown the user pastes back or downloads as .md. Parse by the (`id`) keys, not question numbers or wording. Treat open — no answer given as still-undecided — never fill those in yourself. Record ruled decisions wherever the project keeps them (design doc, ADR, memory), quoting the answer.

questions.json

{
  "title": "Mitate — design alignment",
  "intro": "Current understanding (flag anything wrong in Q1):\n- ...",
  "outro": "Closing instruction echoed to the agent under the answers.",
  "questions": [
    {
      "id": "storage",
      "label": "Storage layout",
      "section": "Architecture",
      "question": "One JSONB table, or normalized?",
      "why": "What hangs on this decision, in the user's terms.",
      "ref": "SPEC.md §3",
      "type": "single",
      "options": [
        {"value": "Single JSONB table", "detail": "Consequence of picking this.", "recommended": true},
        "Normalized from day one",
        "Other — see note"
      ],
      "note": true,
      "optional": false,
      "showIf": {"q": "earlier-id", "is": "that question's option value"}
    }
  ]
}

• type: single (default) | multi | text. Choice types need ≥2 options (plain strings allowed); text renders a textarea.
• note: true adds an optional free-text field under the choices; optional: true excludes the question from the answered count; section renders a heading when it changes; showIf supports is or not against an earlier question's option value.

Composing questions

• One decision per question. If a stem contains "and", split it.
• Options must be mutually exclusive and each detail states the consequence of picking it, not a restatement. Mark your recommended pick — you have an opinion and hiding it wastes the user's time — and include an "Other / needs discussion" escape so no one is forced into a false choice.
• why says what downstream work changes with the answer; ref points at the file/line or note that proves the framing, so the user can check you.
• showIf only for real dependencies (e.g. "what replaces the gate?" only if they skip the gate). Skipped questions still appear in the answers, marked skipped.
• Keep decision alignment to ~15 questions or fewer. For large elicitation (requirements, preferences for a doc you'll draft), group with section, mark nice-to-haves optional, and tell the user they can answer in sittings — drafts autosave.

Notes

• The HTML is dependency-free and offline: strict CSP, no network, drafts in localStorage. When content is personal (finances, health), say so — answers never leave their machine until they hand them back.
• Storage key includes the question-id list, so regenerating with changed questions starts a clean draft rather than restoring stale answers.
• Build output like alignment.html: 12 questions, 2 conditional confirms parse + validation; errors list the failing questions[i] and exit non-zero.