api-aqa-flow-gap-and-requirements-clarification

<api_aqa_flow_gap_and_requirements_clarification>

<description_and_purpose> Cross-reference test cases, documentation, and API spec to identify gaps, contradictions, and ambiguities. Clarify all unknowns with user before test specification. </description_and_purpose>

<workflow_context>

• Phase 3 of 8 in api-aqa-flow
• Input: raw data (Phase 1) + API analysis (Phase 2) + project config
• Output: plans/api-aqa-{IDENTIFIER}/analysis.md with gaps resolved, user answers documented
• Prerequisite: Phases 1 and 2 complete
• HITL: user answers required before Phase 4
• Required skills: qa-knowledge (gap_analysis mode + G/C/A finding forms), qa-structure ({IDENTIFIER} + analysis path)
• Recommended skills: questioning (clarification batch) </workflow_context>

<phase_steps>

1. Execute gap analysis
2. Present questions and wait for user answers
3. Document clarifications and update state </phase_steps>

<execute_gap_analysis step="3.1" subagent="architect" role="Test requirements analyst">

1. USE SKILL qa-knowledge (gap_analysis mode). Run all three variants against the inputs and EMIT findings into the phase-owned sections of <analysis_md_contract>; the mode is analysis-only and never invents the artifact shape:
   • Test-cases-vs-API-spec variant → Gaps (G[N] entries; test step vs API analysis cross-reference).
   • General multi-source variant → Contradictions (C[N]; cross-source disagreements between raw-data, api-analysis, docs) + Ambiguities (A[N]; vague statements).
2. Finding-entry shapes (G[N] / C[N] / A[N], each with verbatim source quote + citation + impact + suggested question) are qa-knowledge's gap-finding templates — the skill loads its own asset at point of use.
3. If a finding fits more than one bucket, record it once under the section that owns its emit shape (G/C/A) and add a cross-reference note rather than duplicating.
4. Prepare a prioritized list of gaps, contradictions, ambiguities for step 3.2.

</execute_gap_analysis>

<ask_user step="3.2">

1. USE SKILL questioning
2. Present structured questions to user (Critical / Important / Optional)
3. STOP AND WAIT for user to provide all answers
4. Unknown-answer branches by priority:
   • Critical unknown: mark as BLOCKING ASSUMPTION in analysis.md, stop Phase 3, do not advance to Phase 4 until the user provides an answer or explicitly approves proceeding with the assumption.
   • Important unknown: mark as ASSUMPTION with rationale, flag in agents/TEMP/<FEATURE>/api-aqa-state.md under Open Assumptions, proceed.
   • Optional unknown: mark as SKIPPED with reason, proceed.
   • Partial answer: record what was answered; treat the unanswered portion per the matching priority branch above.
   • User defers / marks out-of-scope: record as DEFERRED — user out-of-scope and treat as Optional (proceed). </ask_user>

<update_plan step="3.3">

1. Process user answers
2. Update analysis document with questions, answers, and resolved items
3. Verify plans/api-aqa-{IDENTIFIER}/analysis.md created with all required sections (see <analysis_md_contract> below) </update_plan>

<analysis_md_contract> analysis.md must include these sections in order; missing or empty sections fail validation:

1. Gaps — items not covered by raw-data or API analysis (one bullet per gap, with source citation)
2. Contradictions — places where raw-data and api-analysis disagree (with both sources cited)
3. Ambiguities — wording or behavior open to interpretation
4. Questions — full list of structured questions asked (with priority tag: Critical / Important / Optional)
5. Answers — user responses; for each, indicate ANSWERED / ASSUMPTION / BLOCKING ASSUMPTION / SKIPPED / DEFERRED per <ask_user> step 4
6. Resolutions — final disposition for each gap/contradiction/ambiguity (resolved, accepted as assumption, deferred to a later phase)
7. Open Assumptions — explicit list of every unresolved item carried forward (mirrors the count in api-aqa-state.md) </analysis_md_contract>