testgen-flow-question-generation

<testgen_flow_question_generation>

<description_and_purpose> Generate specific, actionable clarification questions based on analysis findings, collect user answers, and validate completeness. This is the primary HITL gate — user input is required before proceeding to requirements generation. </description_and_purpose>

<workflow_context>

• Phase 3 of 7 in testgen-flow
• Input: analysis.md from Phase 2
• Output: questions.md (for user), answers.md (structured user responses by AI based on answers in questions.md)
• Recommended skills: questioning
• Prerequisite: Phase 0, 1, 2 complete
• HITL GATE: MUST WAIT for user to provide answers. Explicit approval required. Do not assume user approved — if user sends questions or suggestions, that is reviewing, not approval. </workflow_context>

<phase_steps>

1. Generate clarification questions (loads analysis + formats by issue type) → step 3.1
2. Prioritize and create questions document → step 3.2
3. Validate user answers → step 3.3
4. Create answers document → step 3.4
5. Update state file → step 3.5 </phase_steps>

<generate_questions step="3.1">

1. Read plans/testgen-{TICKET-KEY}/analysis.md
2. USE SKILL questioning to formulate targeted clarification questions from analysis findings
3. For each contradiction: present both conflicting source quotes, ask which is correct, offer options (a/b/c/other)
4. For each gap: explain what's missing and why needed, provide examples or options
5. For each ambiguity: quote vague statement, ask for specific definition or measurement
6. Related issues can be combined: e.g., Q5: G3, G4, A2 - User Permissions Model
7. Quality rules: specific, actionable, includes context, offers options — NOT vague or open-ended

<question_format_for_contradictions>

### Q[N]: [Issue ID] - [Brief Title]
**Issue Type**: Contradiction
**Context**: 
- Ticket states: "[quote]"
- Wiki states: "[quote]"

**Question**: Which statement is correct, or should we use a different approach?
**Options**:
  a) Use the ticket version: [specific value]
  b) Use the Wiki version: [specific value]
  c) Use alternative: [specify]
  d) Other (please specify)

**Your Answer**: 
[Leave blank for user]

</question_format_for_contradictions> <question_format_for_gaps>

### Q[N]: [Issue ID] - [Brief Title]
**Issue Type**: Gap (Functional/Non-Functional/Data/Business Logic/Dependency)
**Context**: [Where this is needed in implementation]

**Question**: [Specific question about missing information]
**Examples/Options** (if applicable):
  - Option 1: [example]
  - Option 2: [example]
  - Other: [allow free text]

**Your Answer**: 
[Leave blank for user]

</question_format_for_gaps> <question_format_for_ambiguities>

### Q[N]: [Issue ID] - [Brief Title]
**Issue Type**: Ambiguity
**Vague Statement**: "[quote from source]"

**Question**: Can you clarify what "[vague term]" means specifically?
**Need to Know**:
  - [Specific aspect 1]
  - [Specific aspect 2]

**Your Answer**: 
[Leave blank for user]

</question_format_for_ambiguities>

<good_questions>

• "Should the authentication use OAuth 2.0, SAML, or Basic Auth?"
• "What is the maximum response time requirement (in milliseconds)?"
• "Should users be able to delete records permanently, or soft-delete only?" </good_questions>

<poor_questions>

• "How should authentication work?" (too broad)
• "Should it be fast?" (vague)
• "Tell me about the feature." (not specific) </poor_questions> </generate_questions>

<create_questions_document step="3.2">

1. Group questions by priority: P0 (Critical, MUST answer), P1 (High), P2 (Medium), P3 (Low)
2. Create plans/testgen-{TICKET-KEY}/questions.md using the questions.md template defined in <questions_template> below
3. Update state to "AWAITING USER INPUT"
4. Notify the user and direct them to give answers by editing the file: give the questions.md path and ask them to fill the [Leave blank for user] fields there. A short chat summary of the questions is fine for orientation, but the authoritative answers are collected in questions.md — do NOT run a chat Q&A in its place, and do NOT accept chat replies as a substitute for the file (validate_answers, step 3.3, reads the file, not the chat). This keeps every question visible and answerable to the user, instead of only the ones the agent chose to surface in chat.
5. PAUSE — WAIT FOR USER INPUT