qa-flow
Present structured multi-choice questions to users via MCP-based QA artifacts.Use when: (1) Need to ask user multiple structured questions, (2) Gathering preferencesor requirements through multi-choice options, (3) Clarifying ambiguous instructions withstructured choices, (4) Getting decisions on implementation choices. Triggers on: "UAUQ","ask me questions", "I need to ask the user", "gather requirements", "clarify with user".
name: qa-flow description: | Present structured multi-choice questions to users via MCP-based QA artifacts. Use when: (1) Need to ask user multiple structured questions, (2) Gathering preferences or requirements through multi-choice options, (3) Clarifying ambiguous instructions with structured choices, (4) Getting decisions on implementation choices. Triggers on: "UAUQ", "ask me questions", "I need to ask the user", "gather requirements", "clarify with user".
QA Flow
Present structured questions to users via MCP artifacts and wait for responses.
Critical: Blocking Wait
wait_for_user_answer is a BLOCKING call. You must actually wait for the result to return - do not fire-and-forget. The call will block until the user submits their answers via the browser.
# CORRECT: Wait for the result
result = await wait_for_user_answer(artifact_id=artifact_id)
answers = result["answers"] # Now process the answers
# WRONG: Don't just call and move on
await wait_for_user_answer(artifact_id=artifact_id)
# ...continuing without using the result
Workflow
1. Register questions
result = await qa_register(questions=[
{
"question": "Which database should we use?",
"header": "Database",
"multiSelect": False,
"options": [
{"label": "PostgreSQL (Recommended)", "description": "Relational, complex queries"},
{"label": "MongoDB", "description": "Document store, flexible schema"}
]
}
])
artifact_id = result["artifact_id"]
2. Present artifact to user
Copy assets/qa_template.html and inject only the artifact_id:
cp assets/qa_template.html qa_abc123.html
sed -i 's/{{ARTIFACT_ID}}/abc123/' qa_abc123.html
The HTML will automatically fetch questions from the server via qa_get_questions.
3. Wait for answers
result = await wait_for_user_answer(artifact_id=artifact_id, timeout_seconds=300)
answers = result["answers"]
# answers = {"q0": "PostgreSQL (Recommended)", "q1": ["Auth", "Caching"]}
Question Schema
| Field | Type | Required | Notes |
|---|---|---|---|
question |
string | Yes | Ends with ? |
header |
string | Yes | Max 12 chars |
multiSelect |
bool | Yes | true for checkboxes |
options |
array | Yes | 2-4 items |
options[].label |
string | Yes | 1-5 words |
options[].description |
string | Yes | Trade-offs |
Constraints
- 1-4 questions per artifact
- 2-4 options per question
- "Other" option added automatically (free text)
- Recommended option: put first with "(Recommended)" suffix
- Default timeout: 5 minutes
Answer Format
Single-select returns string, multi-select returns array:
{
"q0": "PostgreSQL (Recommended)",
"q1": ["Auth", "Caching"]
}
If user selected "Other", the value is their custom text input.