questionnaire

Questionnaire

Ask related structured questions in one native dialog flow and read the answers back as stable IDs.

The questionnaire tool runs Pi's native selector and text-input dialogs sequentially. It works in the TUI (Up/Down + Enter) and in the WebUI (options are ordinary clickable buttons).

When to use

Use questionnaire when:

• two or more related choices must be settled before work can continue;
• the choices have a known, bounded option set you can name;
• the user asked to be prompted with a menu, list, form, or dialog;
• a prior questionnaire result returned QUESTIONNAIRE_NEEDS_CLARIFICATION.

Do not use questionnaire when:

• the question is genuinely open-ended and better answered in prose;
• one trivial confirmation is enough — just ask in normal text;
• you are requesting secrets, passwords, tokens, or other credentials;
• you already have the answer in context, or can determine it by reading files or running a read-only command.

Never invent a questionnaire to look thorough. Ask only what actually changes what you will do.

Question design rules

1. Combine. Put every related question into one start call. Do not run several sequential questionnaires for one decision.
2. Stable IDs. Give each question and option a stable, descriptive, non-empty id (deploy_target, target_staging). IDs are what you read back; labels are only display text.
3. Unique IDs. Question IDs must be unique in the call; option IDs must be unique within their question.
4. Concise text. Short label, one clear prompt sentence, and an optional short description per option only when the label is not self-explanatory.
5. Honest types. Use single when exactly one answer is valid, multi when several are. Do not fake multi-select with several single questions.
6. Realistic bounds. A multi question defaults to minSelections: 0; set minSelections: 1 whenever an empty answer is not useful. Set maxSelections only when the task needs a ceiling. Selection bounds are rejected on single questions.
7. Other. allowOther defaults to true. Set it to false when a custom answer is meaningless or unusable.
8. Bounded size. 1–20 questions, 1–50 options per question, IDs ≤128 chars, labels ≤200, prompts ≤2000, option descriptions ≤500.