qa-flow

OhadRubin 的头像作者 OhadRubin

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".

📖 中文导读: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". 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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.