/ui-aqa-flow

name: ui-aqa-flow
description: "Workflow for automated QA: integration and end-to-end UI test automation, page objects, etc."

<ui_aqa_flow>

<description_and_purpose>

End-to-end test automation from requirements gathering to test implementation. Uses test cases, project documentation to create automated tests following existing architecture and coding standards.

Prerequisite: Rosetta Prep Steps.

**Terminology.** External systems are named by role throughout this workflow and its phases: **Test Management System (TMS)**, **Issue Tracker**, and **Wiki**. TestRail, Jira, and Confluence are canonical examples only — adapt identifiers, URLs, requests, calls, and query syntax to the systems resolved for the current project (from repository-root `gain.json`, explicit user input, recognizable URLs/handles, and available integrations).

</description_and_purpose>

<workflow_phases>

**Execution cadence:**

• All Rosetta prep steps MUST be FULLY completed
• USE SKILL `load-project-context`, `orchestration`, `hitl`
• MUST ALWAYS use todo tasks ledger, ASAP. Phases are sequential. Independent tasks can run in parallel.
• Execute every in-scope phase in strict 1-8 order (never skip without explicit HITL confirmation): APPLY PHASE the phase file → update `agents/TEMP/<FEATURE>/ui-aqa-state.md` → next; never start a phase until the previous is marked done in `ui-aqa-state.md`.
• MUST follow JIT phase-by-phase: do not load/act IN ADVANCE.
• Skip gates, transitions, and escalation → `<orchestration_and_escalation>`.
• MUST ALWAYS use todo tasks ledger, ASAP. Prioritize ACCURACY over SPEED. Proactively use available tools/MCPs, if question can be answered from code or MCP call - do that first.

**No assumptions:**

• NO ASSUMPTIONS: never assume selectors, flows, or data — ask the user when information is missing.

**Customization:**

• If the user gave no preferences, perform all steps except optional.
• User CAN customize specific phases / already-done phases / goals / cases — LISTEN and ADOPT.

**Authoritative rules (do not skim past):**

• USE SKILL `coding` before any work touching repository tests, page objects, or shared helpers — authoritative for conventions; repository docs win over skill snippets.
• Default: reuse existing page objects/tests first; create new files only when no suitable match exists.
• Explicit assertions: every test validation traces to a requirement — owned by Phase 2 (`### Explicit Assertions` in the test plan), enforced when Phase 6 implements tests.
• **Blocking infeasibility = HARD-STOP + HITL (NOT waived by a clarification skip):** if any phase finds the feature/elements under test do not exist such that the test cannot be authored without inventing selectors/flows/data or modifying product source, STOP and escalate with the options — point at the real feature/URL · author the missing UI as a separate approved task · a clearly-marked pending/`fixme` spec · abort — and WAIT for the user's explicit choice. "Skip clarification" waives clarification *questions* only; it never authorizes this feasibility/scope call.

<data_collection phase="1" applies="ALL" subagent="discoverer" role="UI-AQA data collector" subagent_required_model="inherit">

• APPLY SKILL FILE `phases/ui-aqa-flow-data-collection.md`
• Input: user request + repository-root `gain.json` + project context at its configured paths (canonical: `docs/CONTEXT.md`, `docs/ARCHITECTURE.md`, `agents/IMPLEMENTATION.md`). Output: test plan at `plans/ui-aqa-<test-name>/test-plan.md`
• Required skills: `data-collection`, `sensitive-data`, `qa-structure`, `qa-knowledge`
• Update `agents/TEMP/<FEATURE>/ui-aqa-state.md`; Phase 1 is not complete until its output spot-check passes.

</data_collection>

<requirements_clarification phase="2" applies="ALL" subagent="architect" role="Test requirements analyst" subagent_required_model="inherit" type="HITL">

• APPLY SKILL FILE `phases/ui-aqa-flow-requirements-clarification.md`
• Input: user request + collected data from Phase 1. Output: clarified requirements + typed assertion list in the test plan
• **WAIT FOR USER ANSWERS** to the clarifying questions before Phase 3.
• Required skills: `qa-knowledge` (`gap_analysis` mode), `qa-structure`
• Recommended skills: `questioning`
• Update `agents/TEMP/<FEATURE>/ui-aqa-state.md`; Phase 2 is not complete until its output spot-check passes.

</requirements_clarification>

<code_analysis phase="3" applies="ALL" subagent="discoverer" role="Test architecture analyst" subagent_required_model="inherit">

• APPLY SKILL FILE `phases/ui-aqa-flow-code-analysis.md`
• Input: repo docs + test plan. Output: code analysis report at `plans/ui-aqa-<test-name>/code-analysis.md` (architecture patterns, existing page objects, test patterns)
• Required skills: `qa-knowledge` (`code_analysis` mode), `reverse-engineering`, `sensitive-data`, `qa-structure`
• Update `agents/TEMP/<FEATURE>/ui-aqa-state.md`; Phase 3 is not complete until its output spot-check passes.

</code_analysis>

<selector_identification phase="4" applies="ALL" subagent="engineer" role="Selector identification specialist" subagent_required_model="inherit" type="HITL-CONDITIONAL">

• APPLY SKILL FILE `phases/ui-aqa-flow-selector-identification.md`
• Input: code analysis report + frontend code (or user-provided page source). Output: identified selectors for test targets
• **WAIT FOR USER TO PROVIDE PAGE SOURCE** only if frontend code unavailable or selectors not found.
• Required skills: `qa-knowledge` (`implementation_modes` — selector mode Part A), `qa-structure`, `sensitive-data`
• Recommended skills: `testing`
• Update `agents/TEMP/<FEATURE>/ui-aqa-state.md`; Phase 4 is not complete until its output spot-check passes.

</selector_identification>

<selector_implementation phase="5" applies="ALL" subagent="engineer" role="Selector implementation specialist" subagent_required_model="inherit">

• APPLY SKILL FILE `phases/ui-aqa-flow-selector-implementation.md`
• Input: identified selectors + existi