/testgen-flow-question-generation

name: testgen-flow-question-generation
description: "Phase 3 Question Generation of testgen-flow"
alwaysApply: false
disable-model-invocation: true
user-invocable: false
baseSchema: docs/schemas/phase.md

<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**

<questions_template> `questions.md` template:

# Clarification Questions - [TICKET-KEY]

**Created**: [DateTime]
**Phase**: 3 - Question Generation
**Source Analysis**: plans/testgen-[TICKET-KEY]/analysis.md

---

## Summary

- **Total Questions**: [Count]
- **P0 (Critical, MUST answer)**: [Count]
- **P1 (High)**: [Count]
- **P2 (Medium)**: [Count]
- **P3 (Low)**: [Count]

---

## How to Answer

For each question below, replace `[Leave blank for user]` with your answer (or `UNKNOWN — need to research with [stakeholder]` if you cannot answer right now). All **P0** must be answered before Phase 4 proceeds; P1 must be answered or marked UNKNOWN.

---

## P0 Questions (Critical)

[Insert Q-entries here using `<question_format_for_contradictions>` / `<question_format_for_gaps>` / `<question_format_for_ambiguities>` formats above, grouped under this section]

## P1 Questions (High)

[Same; if none, omit the section]

## P2 Questions (Medium)

[Same; optional, may remain blank per `<validate_answers>` rule]

## P3 Questions (Low)

[Same; optional, may remain blank per `<validate_answers>` rule]

---

## Additional Questions or Comments

[If you have information, constraints, edge cases, or context NOT covered by the questions above, add it here. This free-text is the channel for user-volunteered input and is carried in