qaa-agent 1.9.2 → 1.9.5

package/commands/qa-fix.md

@@ -1,513 +1,684 @@
-# QA Fix & Validate
-
-Validate, diagnose, and fix test files — all in one command. Runs 4-layer static validation (syntax, structure, dependencies, logic), classifies failures, and auto-fixes TEST CODE ERRORS. Uses Playwright MCP to reproduce E2E failures and verify locators against the live app when available. Never touches application code.
-
-## Usage
-
-```
-/qa-fix [<test-files-or-directory>] [options]
-```
-
-### Options
-
-- `<test-files-or-directory>` — one or more test file paths or a directory (auto-detects if omitted)
-- `--check` — **final check mode**: full quality verification against company preferences, codebase conventions, and execution
-- `--validate-only` — run 4-layer static validation only, no test execution or classification
-- `--classify` — run tests and classify failures, but do NOT auto-fix
-- `--run --app-url <url>` — also execute E2E tests against live app after static validation
-- `--app-url <url>` — URL of running application (auto-detects if not provided)
-- `[error output]` — paste test runner output directly (skips running tests, classifies the pasted output)
-
-### Mode Detection
-
-```
-if --check:
-  MODE = "check"           → full quality check + execution + QA_CHECK_REPORT.md
-elif --validate-only:
-  MODE = "validate"        → 4-layer static validation + VALIDATION_REPORT.md
-elif --classify:
-  MODE = "classify"        → run tests + classify failures (no auto-fix)
-else:
-  MODE = "fix"             → run tests + classify + auto-fix TEST CODE ERRORS (default)
-```
-
-## What It Produces
-
-| Mode | Artifacts |
-|------|-----------|
-| check | QA_CHECK_REPORT.md (full quality verification with pass/fail per test file) |
-| check --ticket | QA_CHECK_REPORT.md + UAT_VERIFICATION.md (step-by-step screenshots vs ticket acceptance criteria) |
-| validate | VALIDATION_REPORT.md (syntax, structure, dependencies, logic per file) |
-| classify | FAILURE_CLASSIFICATION_REPORT.md (per-failure evidence, no fixes) |
-| fix | FAILURE_CLASSIFICATION_REPORT.md + auto-fixed test files |
-
-## Instructions
-
-### Step 1: Detect Mode and Test Directory
-
-Parse `$ARGUMENTS` for mode flags and test directory path.
-
-If no test directory provided, auto-detect:
-- Check for `tests/`, `cypress/`, `__tests__/`, `e2e/`, `spec/` directories
-- Check test config files for `testDir` setting
-
-Print banner:
-```
-=== QA Fix & Validate ===
-Mode: {validate | classify | fix}
-Test Directory: {path}
-App URL: {url or "auto-detect"}
-==========================
-```
-
----
-
-### CHECK MODE (`--check`) — Final Quality Verification
-
-Full quality check for specific test files. Reads ALL context sources, verifies every aspect of the tests, runs them, and produces a pass/fail report. Use this as a final gate before delivering tests.
-
-**Accepts specific files:**
-```
-/qa-fix --check tests/e2e/login.e2e.spec.ts tests/e2e/checkout.e2e.spec.ts
-/qa-fix --check tests/unit/auth.unit.spec.ts
-/qa-fix --check tests/e2e/ --app-url http://localhost:3000
-```
-
-**Step 1: Read ALL context sources**
-
-Read every available context source — this is not optional, all must be read:
-
-1. **CLAUDE.md** — QA standards, POM rules, locator tiers, assertion rules, naming conventions, quality gates
-2. **~/.claude/qaa/MY_PREFERENCES.md** — company/user preferences that OVERRIDE CLAUDE.md rules
-3. **Codebase map** (`.qa-output/codebase/`):
-   - `CODE_PATTERNS.md` — naming conventions, import style, file organization (are tests matching the project's style?)
-   - `API_CONTRACTS.md` — real API shapes (are API test payloads correct?)
-   - `TEST_SURFACE.md` — function signatures (are test targets real?)
-   - `TESTABILITY.md` — mock boundaries (are mocks set up correctly?)
-4. **Locator Registry** (`.qa-output/locators/`) — real locators from the app (are POM locators accurate?)
-5. **Existing test patterns** — read 2-3 existing test files in the same repo to understand current conventions (describe block style, import patterns, assertion patterns, fixture usage)
-
-If codebase map is missing, STOP and tell the user to run `/qa-map` first.
-
-**Step 2: Verify each test file across 7 dimensions**
-
-For EACH selected test file, check:
-
-| # | Dimension | What to check | Source |
-|---|-----------|---------------|--------|
-| 1 | **Naming** | File name, test IDs, describe/it names follow conventions | CLAUDE.md + CODE_PATTERNS.md + MY_PREFERENCES.md |
-| 2 | **Structure** | Correct directory, imports resolve, follows repo patterns | CODE_PATTERNS.md + existing tests in repo |
-| 3 | **Locators** | POM locators match registry, Tier 1 preferred, no stale selectors | LOCATOR_REGISTRY.md |
-| 4 | **Assertions** | Concrete values (no toBeTruthy alone), match API contracts | CLAUDE.md + API_CONTRACTS.md |
-| 5 | **POM compliance** | No assertions in POMs, locators as properties, extends BasePage | CLAUDE.md |
-| 6 | **Code quality** | No redundant code, no dead code, no hardcoded credentials, no copy-paste | Code review |
-| 7 | **Company conventions** | Matches all rules in MY_PREFERENCES.md | MY_PREFERENCES.md |
-
-**Step 3: Run the tests**
-
-Execute the selected test files:
-
-```bash
-# Detect test runner from project config
-npx playwright test {files} --reporter=json 2>&1    # if Playwright
-npx cypress run --spec {files} 2>&1                  # if Cypress
-npx jest {files} --json 2>&1                         # if Jest
-npx vitest run {files} --reporter=json 2>&1          # if Vitest
-```
-
-If E2E tests and app URL available, also verify with Playwright MCP:
-- Navigate to each page referenced in the tests
-- `browser_snapshot()` to verify elements exist in DOM
-- Cross-reference locators against real page
-
-**Step 4: Fix issues found**
-
-For each issue found:
-- **AUTO-FIX** (HIGH confidence): naming, imports, locator mismatches, missing await, Tier 4→Tier 1 upgrade when registry has the value
-- **FLAG for review** (MEDIUM/LOW): logic changes, assertion value changes, structural refactors
-- Re-run tests after fixes (max 5 loops)
-
-**Step 5: Produce QA_CHECK_REPORT.md**
-
-```markdown
-# QA Check Report
-
-## Summary
-
-| Metric | Value |
-|--------|-------|
-| Files checked | {N} |
-| Dimensions checked | 7 |
-| Issues found | {N} |
-| Auto-fixed | {N} |
-| Flagged for review | {N} |
-| Tests passed | {N}/{total} |
-| Overall | PASS / PASS WITH WARNINGS / FAIL |
-
-## Per-File Results
-
-### {file_path}
-
-| Dimension | Status | Details |
-|-----------|--------|---------|
-| Naming | PASS/FAIL | {specific details} |
-| Structure | PASS/FAIL | {specific details} |
-| Locators | PASS/FAIL | {specific details} |
-| Assertions | PASS/FAIL | {specific details} |
-| POM compliance | PASS/FAIL | {specific details} |
-| Code quality | PASS/FAIL | {specific details} |
-| Company conventions | PASS/FAIL | {specific details} |
-
-**Test execution:** PASS / FAIL ({error if failed})
-**Fixes applied:** {list of auto-fixes}
-**Flagged for review:** {list of items needing human review}
-
-[... repeat per file ...]
-
-## Flagged Items (Needs Human Review)
-
-| File | Dimension | Issue | Suggested Fix |
-|------|-----------|-------|---------------|
-| ... | ... | ... | ... |
-```
-
-Write to `.qa-output/QA_CHECK_REPORT.md`.
-
-Present results to user with clear PASS/FAIL per file and overall status.
-
-**Step 6 (optional): Ticket Verification (`--ticket <source>`)**
-
-If `--ticket` flag is provided, perform UAT verification — walk through the test flow step-by-step in the browser, take screenshots at each step, and compare against the ticket's acceptance criteria.
-
-**Usage:**
-```
-/qa-fix --check --ticket #123 tests/e2e/login.e2e.spec.ts --app-url http://localhost:3000
-/qa-fix --check --ticket https://company.atlassian.net/browse/PROJ-456 tests/e2e/checkout.e2e.spec.ts
-/qa-fix --check --ticket "User logs in, sees dashboard with welcome message, clicks profile" tests/e2e/login.e2e.spec.ts
-```
-
-**Requires:** `--app-url` or auto-detected running app. Cannot do ticket verification without a live app.
-
-**Step 6a: Fetch and parse the ticket**
-
-Same ticket parsing as `/qa-create-test` from-ticket mode:
-- GitHub Issue: `gh issue view` → extract title, body, ACs
-- Jira/Linear URL: `WebFetch` → extract content
-- Plain text: use directly as acceptance criteria
-- File path: read file content
-
-Extract:
-- Acceptance criteria (AC-1, AC-2, ...)
-- Expected user flow (step-by-step)
-- Expected outcomes per step
-
-**Step 6b: Walk through the flow with Playwright MCP**
-
-For each E2E test file being checked, replay the user journey manually in the browser step-by-step:
-
-```
-For each step in the ticket's user flow:
-
-  1. Execute the action described in the step:
-     - Navigate: mcp__playwright__browser_navigate({ url: "{page}" })
-     - Fill form: mcp__playwright__browser_fill_form({ ... })
-     - Click: mcp__playwright__browser_click({ element: "..." })
-     - Wait: mcp__playwright__browser_wait_for({ text: "..." })
-
-  2. Take screenshot AFTER the action:
-     mcp__playwright__browser_take_screenshot()
-     → Save to .qa-output/uat-screenshots/{test-name}-step-{N}.png
-
-  3. Take accessibility snapshot to read page state:
-     mcp__playwright__browser_snapshot()
-
-  4. Record what the page shows:
-     - URL after action
-     - Visible text/headings
-     - Form state
-     - Error messages (if any)
-     - Elements visible/hidden
-```
-
-**Step 6c: Compare actual vs ticket**
-
-For each acceptance criterion from the ticket:
-
-| AC | Expected (from ticket) | Actual (from browser) | Screenshot | Verdict |
-|----|----------------------|---------------------|------------|---------|
-| AC-1 | User sees login form | Login form visible with email/password fields | step-1.png | MATCH |
-| AC-2 | After login, redirect to dashboard | Redirected to /dashboard, "Welcome" visible | step-3.png | MATCH |
-| AC-3 | Error message for wrong password | "Invalid credentials" alert shown | step-5.png | MATCH |
-| AC-4 | Remember me keeps session | Session persists after browser close | step-7.png | MISMATCH — session expired |
-
-Verdicts:
-- **MATCH** — actual behavior matches what the ticket describes
-- **MISMATCH** — actual behavior differs from ticket (could be app bug OR test not covering this AC)
-- **NOT TESTED** — ticket has an AC but no test step covers it
-- **EXTRA** — test covers something not in the ticket (informational, not a failure)
-
-**Step 6d: Produce UAT_VERIFICATION.md**
-
-```markdown
-# UAT Verification Report
-
-## Ticket Info
-
-| Field | Value |
-|-------|-------|
-| Source | {ticket URL or text} |
-| Title | {ticket title} |
-| ACs extracted | {count} |
-| Test files verified | {count} |
-
-## Step-by-Step Walkthrough
-
-### Step 1: {action description}
-- **Action:** Navigate to /login
-- **Screenshot:** [step-1.png](.qa-output/uat-screenshots/{test}-step-1.png)
-- **Page state:** Login form visible, email and password fields empty, "Log in" button enabled
-- **Matches AC:** AC-1 ✓
-
-### Step 2: {action description}
-- **Action:** Fill email "test@example.com", password "SecureP@ss123!"
-- **Screenshot:** [step-2.png]
-- **Page state:** Fields filled, button still enabled
-- **Matches AC:** (intermediate step, no AC)
-
-[... repeat per step ...]
-
-## AC Coverage Matrix
-
-| AC | Description | Tested | Verdict | Evidence |
-|----|-------------|--------|---------|----------|
-| AC-1 | Login form visible | Yes | MATCH | step-1.png |
-| AC-2 | Redirect to dashboard | Yes | MATCH | step-3.png |
-| AC-3 | Error on wrong password | Yes | MATCH | step-5.png |
-| AC-4 | Remember me session | No | NOT TESTED | — |
-
-## Summary
-
-| Metric | Value |
-|--------|-------|
-| ACs from ticket | {N} |
-| ACs matched | {N} |
-| ACs mismatched | {N} |
-| ACs not tested | {N} |
-| Screenshots captured | {N} |
-| Overall | PASS / PARTIAL / FAIL |
-```
-
-Write to `.qa-output/UAT_VERIFICATION.md`.
-
-If any AC is MISMATCH or NOT TESTED, present to user with recommendation:
-- MISMATCH → "AC-4 says X but the app does Y — either the app has a bug or the test needs updating"
-- NOT TESTED → "AC-4 is not covered by any test step — consider adding a test case"
-
----
-
-### VALIDATE MODE (`--validate-only`)
-
-1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules.
-2. Execute static validation workflow:
-
-Follow the workflow defined in `@workflows/qa-validate.md` end-to-end.
-Preserve all workflow gates (fix loops, layer checks).
-
-The validator runs 4 layers per file:
-1. **Syntax** — code compiles without errors
-2. **Structure** — naming, folders, POM compliance
-3. **Dependencies** — all imports resolve
-4. **Logic** — concrete assertions, Tier 1-2 locators, no assertions in POMs
-
-**Optional Layer 5 (if Playwright MCP connected + app URL available):**
-- Navigate to each page referenced in E2E tests via `mcp__playwright__browser_navigate`
-- Take accessibility snapshot via `mcp__playwright__browser_snapshot`
-- Cross-reference test locators against real DOM elements
-- Flag locators that don't match, auto-fix mismatches
-
-Max 5 fix loop iterations. Produces VALIDATION_REPORT.md.
-
-If `--run` flag is also present and E2E test files exist, invoke E2E runner after static validation:
-
-Task(
-  prompt="
-    <objective>Run E2E tests against live application, capture real locators, fix mismatches, loop until pass. Query Context7 MCP to verify framework selector syntax before fixing locators.</objective>
-    <execution_context>@agents/qaa-e2e-runner.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
-    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
-    - .qa-output/research/E2E_STRATEGY.md (if exists)
-    - {E2E test files from validated directory}
-    - {POM files from validated directory}
-    </files_to_read>
-    <parameters>
-    app_url: {from --app-url flag or auto-detect}
-    output_dir: .qa-output
-    </parameters>
-  "
-)
-
----
-
-### CLASSIFY MODE (`--classify`)
-
-Same as fix mode below but skip Step 4 (auto-fix). Only classify and report.
-
----
-
-### FIX MODE (default)
-
-Fix mode runs in two phases: **analyze first, then fix after user confirmation.**
-
-#### Phase 1: Analyze & Present Plan (always runs)
-
-1. Read `CLAUDE.md` — classification rules, locator tiers, assertion quality.
-2. Invoke bug-detective agent in **classify-only mode** (no auto-fixes):
-
-Task(
-  prompt="
-    <objective>Run tests and classify failures. Do NOT auto-fix anything yet — this is the analysis phase. Use Playwright MCP to reproduce E2E failures in the browser when available — navigate to failing pages, snapshot DOM, reproduce actions, and screenshot failure state for evidence. Query Context7 MCP to verify framework syntax when diagnosing failures.</objective>
-    <execution_context>@agents/qaa-bug-detective.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
-    - .qa-output/codebase/CODE_PATTERNS.md (if exists)
-    - .qa-output/codebase/API_CONTRACTS.md (if exists)
-    - .qa-output/codebase/TEST_SURFACE.md (if exists)
-    - .qa-output/codebase/TESTABILITY.md (if exists)
-    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
-    - .qa-output/research/TESTING_STACK.md (if exists)
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: classify-only
-    app_url: {auto-detect from test config baseURL, or ask user}
-    </parameters>
-  "
-)
-
-3. Present the analysis to the user as a **fix plan**:
-
-```
-=== FIX PLAN ===
-
-Tests run: {N}
-Passed: {N}
-Failed: {N}
-
-Failures classified:
-  APPLICATION BUG:    {N} (will NOT be touched)
-  TEST CODE ERROR:    {N} (can auto-fix)
-  ENVIRONMENT ISSUE:  {N} (resolution steps provided)
-  INCONCLUSIVE:       {N} (needs more info)
-
-Proposed auto-fixes (TEST CODE ERRORS only):
-  1. {file}:{line} — {description of fix} [HIGH confidence]
-  2. {file}:{line} — {description of fix} [HIGH confidence]
-  3. {file}:{line} — {description of fix} [MEDIUM — flagged for review]
-
-APPLICATION BUGs found (for developer action):
-  1. {file}:{line} — {description}
-  2. {file}:{line} — {description}
-
-Proceed with auto-fixes? [yes / modify / cancel]
-================
-```
-
-4. **Wait for user confirmation.** Do NOT proceed until the user approves. This is a refinement loop — repeat until the user is satisfied:
-
-   - **"yes"** / **"proceed"** / **"dale"** → continue to Phase 2
-   - **"cancel"** / **"no"** → stop, deliver only the FAILURE_CLASSIFICATION_REPORT.md (same as --classify)
-   - **Any other response** (feedback, modifications, additions) → treat as a refinement request:
-     - Adjust the fix plan based on the user's instructions (add fixes, remove fixes, change approach, add new checks)
-     - Re-present the updated Fix Plan showing what changed
-     - Wait for user confirmation again
-     - Repeat this loop until the user says "yes" or "cancel"
-
-   **Examples of refinement requests:**
-   - "esto está bien pero también quiero que arregles los imports de utils" → add that fix to the plan
-   - "no toques el archivo de login, dejalo como está" → remove that file from the plan
-   - "cambiá el selector por getByRole en vez de getByTestId" → update the proposed fix
-   - "agregá también una validación de que el status sea 200" → add assertion fix to the plan
-
-#### Phase 2: Execute Fixes (only after user confirmation)
-
-5. Invoke bug-detective agent in **fix mode** with the confirmed plan:
-
-Task(
-  prompt="
-    <objective>Auto-fix the confirmed TEST CODE ERRORS from the analysis phase. Use Playwright MCP to reproduce E2E failures in the browser when available. Query Context7 MCP to verify correct framework syntax before applying any fix.</objective>
-    <execution_context>@agents/qaa-bug-detective.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
-    - .qa-output/codebase/CODE_PATTERNS.md (if exists)
-    - .qa-output/codebase/API_CONTRACTS.md (if exists)
-    - .qa-output/codebase/TEST_SURFACE.md (if exists)
-    - .qa-output/codebase/TESTABILITY.md (if exists)
-    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
-    - .qa-output/research/TESTING_STACK.md (if exists)
-    - .qa-output/FAILURE_CLASSIFICATION_REPORT.md
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: fix
-    app_url: {auto-detect from test config baseURL, or ask user}
-    </parameters>
-  "
-)
-
-**Classification categories:**
-- **APPLICATION BUG** — error in production code → Report only, NEVER auto-fix
-- **TEST CODE ERROR** — error in test code → Auto-fix if HIGH confidence
-- **ENVIRONMENT ISSUE** — missing env, connection refused → Report with resolution steps
-- **INCONCLUSIVE** — ambiguous → Report what's known, ask for more info
-
-**Auto-fix rules:**
-- Only TEST CODE ERROR at HIGH confidence
-- Allowed fixes: import paths, selectors, assertion values, config, missing await, fixture paths
-- Every fix verified by re-running the specific test
-- Never modify application code (src/, app/, lib/)
-
-**Browser reproduction (when Playwright MCP connected):**
-- Navigate to failing page → snapshot DOM → reproduce action → screenshot
-- Element not in DOM → TEST CODE ERROR (HIGH confidence)
-- Element exists, wrong behavior → APPLICATION BUG
-- Page doesn't load → ENVIRONMENT ISSUE
-
-6. Present results. APPLICATION BUGs are reported for developer action, not auto-fixed.
-
-$ARGUMENTS
-
-## MANDATORY verification — run ALL commands below, no exceptions, no skipping
-
-Before returning control, copy-paste and run this ENTIRE block. Do NOT decide which commands "apply" — run all of them every time. The output confirms what happened; you do not get to assume the answer.
-
-```bash
-echo "=== QA-FIX CHECKLIST START ==="
-echo "1. Failure classification report:"
-ls .qa-output/FAILURE_CLASSIFICATION_REPORT.md 2>/dev/null || echo "NO_CLASSIFICATION_REPORT"
-echo "2. Locator Registry:"
-ls .qa-output/locators/ 2>/dev/null || echo "NO_LOCATORS_FOUND"
-echo "3. MY_PREFERENCES.md:"
-cat ~/.claude/qaa/MY_PREFERENCES.md 2>/dev/null || echo "FILE_NOT_FOUND"
-echo "4. Codebase map (context for bug-detective):"
-ls .qa-output/codebase/ 2>/dev/null || echo "NO_CODEBASE_MAP"
-echo "5. Test files in scope:"
-find tests/ cypress/ __tests__/ e2e/ spec/ -type f -name "*.spec.*" -o -name "*.test.*" -o -name "*.e2e.*" 2>/dev/null | head -20 || echo "NO_TEST_FILES_FOUND"
-echo "6. MCP evidence (if browser was used):"
-ls .qa-output/mcp-evidence/ 2>/dev/null || echo "NO_MCP_EVIDENCE"
-echo "7. Classification categories in report:"
-grep -cE "APPLICATION BUG|TEST CODE ERROR|ENVIRONMENT ISSUE|INCONCLUSIVE" .qa-output/FAILURE_CLASSIFICATION_REPORT.md 2>/dev/null || echo "NO_CLASSIFICATIONS"
-echo "=== QA-FIX CHECKLIST END ==="
-```
-
-**Rules:**
-- Run the block AS-IS. Do not modify it. Do not split it. Do not skip lines.
-- If any output shows a problem (NO_CLASSIFICATION_REPORT after fix mode completed), fix it before returning.
-- If output shows expected "not found" results (e.g., NO_MCP_EVIDENCE when no browser was used), that is fine — the point is you RAN the command instead of assuming the answer.
-- Do NOT mark this task as complete until the block has been executed and you have read every line of output.
+# QA Fix & Validate
+
+Validate, diagnose, and fix test files — all in one command. Runs 4-layer static validation (syntax, structure, dependencies, logic), classifies failures, and auto-fixes TEST CODE ERRORS. Uses Playwright MCP to reproduce E2E failures and verify locators against the live app when available. Never touches application code.
+
+
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps.
+
+1. FIRST tool call: run the intent detector with `$ARGUMENTS` passed LITERALLY
+   (the actual command lives in the "## Intent Detection" section below).
+2. Print the INPUT DETECTION banner (exact output from intent-detector.cjs).
+3. Determine `ALL_FROM_FLAGS`. If interactive (`IS_AUTO=false`) AND any value
+   came from NL/default (`ALL_FROM_FLAGS=false`), PAUSE for yes/no confirmation.
+   Do NOT proceed without it.
+   ```bash
+   ALL_FROM_FLAGS=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); const sources=Object.values(j.resolved).map(v=>v.source); console.log(sources.length>0 && sources.every(s=>s==='flag') ? 'true' : 'false')")
+   ```
+   Pause prompt (when applicable):
+   ```
+   The values above were resolved from natural language and/or defaults.
+   Do you want to continue with these inputs? (yes/no)
+   ```
+4. Determine MODE from the resolved values (not from your own NL parsing).
+5. Print the "=== QA Fix & Validate ===" banner (Step 1 of Instructions).
+6. Execute the mode's flow IN ORDER. For FIX MODE specifically:
+   Phase 1 includes invoking the bug-detective via Task() in classify-only
+   mode. Phase 2 includes invoking the bug-detective via Task() in fix mode.
+   Do NOT apply fixes inline with Edit/Write — always go through the sub-agent.
+   Phase 1 (analyze → present FIX PLAN → WAIT for user confirmation) MUST
+   complete before Phase 2 (execute fixes).
+
+### DO NOT
+- Skip the INPUT DETECTION banner or the "=== QA Fix ===" banner
+- Run AskUserQuestion or any tool before the intent detector
+- Present an AskUserQuestion in place of the FIX PLAN confirmation checkpoint
+- Auto-fix anything before the user approves the FIX PLAN (Phase 1 → Phase 2 gate)
+- Apply fixes inline with Edit/Write instead of spawning the bug-detective sub-agent
+- Invent steps not in this command, or reorder the ones that are
+- Assume context, app URL, framework, or any value from previous command
+  invocations (/qa-start, prior /qa-fix calls, etc.). Each /qa-fix invocation
+  is self-contained — the detector returns defaults precisely because the user
+  did not pass them.
+- Modify the FIX PLAN scope after user approval without re-confirming. If the
+  analysis reveals the approved fix is insufficient or incorrect, STOP, present
+  the updated plan to the user, and wait for re-confirmation before applying.
+
+If you find yourself improvising, presenting results before running the
+analysis phase, applying fixes inline, or asking questions out of order —
+STOP and restart from step 1.
+
+### Pass user input literally to the intent detector
+
+When you run the intent detector with `$ARGUMENTS`, substitute that placeholder
+with the RAW user input as received, NOT a pre-translated flag string. If you
+pre-translate, the detector reports every value as `source: flag`, sets
+`ALL_FROM_FLAGS=true`, and bypasses the confirmation checkpoint.
+
+
+## Usage
+
+```
+/qa-fix [<test-files-or-directory>] [options]
+```
+
+### Options
+
+- `<test-files-or-directory>` — one or more test file paths or a directory (auto-detects if omitted)
+- `--check` — **final check mode**: full quality verification against company preferences, codebase conventions, and execution
+- `--validate-only` — run 4-layer static validation only, no test execution or classification
+- `--classify` — run tests and classify failures, but do NOT auto-fix
+- `--run --app-url <url>` — also execute E2E tests against live app after static validation
+- `--app-url <url>` — URL of running application (auto-detects if not provided)
+- `[error output]` — paste test runner output directly (skips running tests, classifies the pasted output)
+
+### Mode Detection
+
+```
+if --check:
+  MODE = "check"           → full quality check + execution + QA_CHECK_REPORT.md
+elif --validate-only:
+  MODE = "validate"        → 4-layer static validation + VALIDATION_REPORT.md
+elif --classify:
+  MODE = "classify"        → run tests + classify failures (no auto-fix)
+else:
+  MODE = "fix"             → run tests + classify + auto-fix TEST CODE ERRORS (default)
+```
+
+## What It Produces
+
+| Mode | Artifacts |
+|------|-----------|
+| check | QA_CHECK_REPORT.md (full quality verification with pass/fail per test file) |
+| check --ticket | QA_CHECK_REPORT.md + UAT_VERIFICATION.md (step-by-step screenshots vs ticket acceptance criteria) |
+| validate | VALIDATION_REPORT.md (syntax, structure, dependencies, logic per file) |
+| classify | FAILURE_CLASSIFICATION_REPORT.md (per-failure evidence, no fixes) |
+| fix | FAILURE_CLASSIFICATION_REPORT.md + auto-fixed test files |
+
+
+## Intent Detection
+
+Before processing arguments, run the intent detector to support natural-language input alongside flags. Flags always win over NL.
+
+```bash
+RESOLVED=$(node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve "$ARGUMENTS" --aliases '{"app_url":"app-url","ticket":"ticket","check":"check","validate_only":"validate-only","classify":"classify","run":"run"}')
+
+# Print INPUT DETECTION banner (always shown, even if defaults are used)
+echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.banner)"
+
+# Extract resolved values for use below
+APP_URL=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.app_url?.value || '')")
+TICKET=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.ticket?.value || '')")
+```
+
+If you see values you didn't intend in the banner above (interactive mode), you can press Ctrl-C and re-run with explicit flags.
+
+## Instructions
+
+### Step 1: Detect Mode and Test Directory
+
+Parse `$ARGUMENTS` for mode flags and test directory path.
+
+If no test directory provided, auto-detect:
+- Check for `tests/`, `cypress/`, `__tests__/`, `e2e/`, `spec/` directories
+- Check test config files for `testDir` setting
+
+Print banner:
+```
+=== QA Fix & Validate ===
+Mode: {validate | classify | fix}
+Test Directory: {path}
+App URL: {url or "auto-detect"}
+==========================
+```
+
+---
+
+### CHECK MODE (`--check`) — Final Quality Verification
+
+Full quality check for specific test files. Reads ALL context sources, verifies every aspect of the tests, runs them, and produces a pass/fail report. Use this as a final gate before delivering tests.
+
+**Accepts specific files:**
+```
+/qa-fix --check tests/e2e/login.e2e.spec.ts tests/e2e/checkout.e2e.spec.ts
+/qa-fix --check tests/unit/auth.unit.spec.ts
+/qa-fix --check tests/e2e/ --app-url http://localhost:3000
+```
+
+**Step 1: Read ALL context sources**
+
+Read every available context source — this is not optional, all must be read:
+
+1. **CLAUDE.md** — QA standards, POM rules, locator tiers, assertion rules, naming conventions, quality gates
+2. **~/.claude/qaa/MY_PREFERENCES.md** — company/user preferences that OVERRIDE CLAUDE.md rules
+3. **Codebase map** (`.qa-output/codebase/`):
+   - `CODE_PATTERNS.md` — naming conventions, import style, file organization (are tests matching the project's style?)
+   - `API_CONTRACTS.md` — real API shapes (are API test payloads correct?)
+   - `TEST_SURFACE.md` — function signatures (are test targets real?)
+   - `TESTABILITY.md` — mock boundaries (are mocks set up correctly?)
+4. **Locator Registry** (`.qa-output/locators/`) — real locators from the app (are POM locators accurate?)
+5. **Existing test patterns** — read 2-3 existing test files in the same repo to understand current conventions (describe block style, import patterns, assertion patterns, fixture usage)
+
+If codebase map is missing, STOP and tell the user to run `/qa-map` first.
+
+**Step 2: Verify each test file across 7 dimensions**
+
+For EACH selected test file, check:
+
+| # | Dimension | What to check | Source |
+|---|-----------|---------------|--------|
+| 1 | **Naming** | File name, test IDs, describe/it names follow conventions | CLAUDE.md + CODE_PATTERNS.md + MY_PREFERENCES.md |
+| 2 | **Structure** | Correct directory, imports resolve, follows repo patterns | CODE_PATTERNS.md + existing tests in repo |
+| 3 | **Locators** | POM locators match registry, Tier 1 preferred, no stale selectors | LOCATOR_REGISTRY.md |
+| 4 | **Assertions** | Concrete values (no toBeTruthy alone), match API contracts | CLAUDE.md + API_CONTRACTS.md |
+| 5 | **POM compliance** | No assertions in POMs, locators as properties, extends BasePage | CLAUDE.md |
+| 6 | **Code quality** | No redundant code, no dead code, no hardcoded credentials, no copy-paste | Code review |
+| 7 | **Company conventions** | Matches all rules in MY_PREFERENCES.md | MY_PREFERENCES.md |
+
+**Step 3: Run the tests**
+
+Execute the selected test files:
+
+```bash
+# Detect test runner from project config
+npx playwright test {files} --reporter=json 2>&1    # if Playwright
+npx cypress run --spec {files} 2>&1                  # if Cypress
+npx jest {files} --json 2>&1                         # if Jest
+npx vitest run {files} --reporter=json 2>&1          # if Vitest
+```
+
+If E2E tests and app URL available, you MAY also probe the DOM with Playwright MCP as supplementary evidence — but this is NOT test execution:
+
+`[DOM_PROBE — NOT_TEST_EXECUTION]` — MCP DOM inspection only. It MAY confirm an element is present in the DOM; it MUST NOT be reported as a passing/verified test. The real test result comes from the runner above (npx playwright / cypress / jest / vitest). If the runner could NOT execute (binary missing, config error, host won't boot, ECONNREFUSED), HARD STOP: report ENVIRONMENT ISSUE, set `runner_executed: false`, and do NOT substitute the MCP probe for the run.
+
+- Navigate to each page referenced in the tests
+- `browser_snapshot()` to confirm elements exist in the DOM (probe, not a pass)
+- Cross-reference locators against real page
+
+**Step 4: Fix issues found**
+
+For each issue found:
+- **AUTO-FIX** (HIGH confidence): naming, imports, locator mismatches, missing await, Tier 4→Tier 1 upgrade when registry has the value
+- **FLAG for review** (MEDIUM/LOW): logic changes, assertion value changes, structural refactors
+- Re-run tests after fixes (max 5 loops)
+
+**Step 5: Produce QA_CHECK_REPORT.md**
+
+```markdown
+# QA Check Report
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Files checked | {N} |
+| Dimensions checked | 7 |
+| Issues found | {N} |
+| Auto-fixed | {N} |
+| Flagged for review | {N} |
+| Tests passed | {N}/{total} |
+| Overall | PASS / PASS WITH WARNINGS / FAIL |
+
+## Per-File Results
+
+### {file_path}
+
+| Dimension | Status | Details |
+|-----------|--------|---------|
+| Naming | PASS/FAIL | {specific details} |
+| Structure | PASS/FAIL | {specific details} |
+| Locators | PASS/FAIL | {specific details} |
+| Assertions | PASS/FAIL | {specific details} |
+| POM compliance | PASS/FAIL | {specific details} |
+| Code quality | PASS/FAIL | {specific details} |
+| Company conventions | PASS/FAIL | {specific details} |
+
+**Test execution:** PASS / FAIL ({error if failed})
+**Fixes applied:** {list of auto-fixes}
+**Flagged for review:** {list of items needing human review}
+
+[... repeat per file ...]
+
+## Flagged Items (Needs Human Review)
+
+| File | Dimension | Issue | Suggested Fix |
+|------|-----------|-------|---------------|
+| ... | ... | ... | ... |
+```
+
+Write to `.qa-output/QA_CHECK_REPORT.md`.
+
+Present results to user with clear PASS/FAIL per file and overall status.
+
+**Step 6 (optional): Ticket Verification (`--ticket <source>`)**
+
+If `--ticket` flag is provided, perform UAT verification — walk through the test flow step-by-step in the browser, take screenshots at each step, and compare against the ticket's acceptance criteria.
+
+**Usage:**
+```
+/qa-fix --check --ticket #123 tests/e2e/login.e2e.spec.ts --app-url http://localhost:3000
+/qa-fix --check --ticket https://company.atlassian.net/browse/PROJ-456 tests/e2e/checkout.e2e.spec.ts
+/qa-fix --check --ticket "User logs in, sees dashboard with welcome message, clicks profile" tests/e2e/login.e2e.spec.ts
+```
+
+**Requires:** `--app-url` or auto-detected running app. Cannot do ticket verification without a live app.
+
+**Step 6a: Fetch and parse the ticket**
+
+Same ticket parsing as `/qa-create-test` from-ticket mode:
+- GitHub Issue: `gh issue view` → extract title, body, ACs
+- Jira/Linear URL: `WebFetch` → extract content
+- Plain text: use directly as acceptance criteria
+- File path: read file content
+
+Extract:
+- Acceptance criteria (AC-1, AC-2, ...)
+- Expected user flow (step-by-step)
+- Expected outcomes per step
+
+**Step 6b: Walk through the flow with Playwright MCP**
+
+For each E2E test file being checked, replay the user journey manually in the browser step-by-step:
+
+```
+For each step in the ticket's user flow:
+
+  1. Execute the action described in the step:
+     - Navigate: mcp__playwright__browser_navigate({ url: "{page}" })
+     - Fill form: mcp__playwright__browser_fill_form({ ... })
+     - Click: mcp__playwright__browser_click({ element: "..." })
+     - Wait: mcp__playwright__browser_wait_for({ text: "..." })
+
+  2. Take screenshot AFTER the action:
+     mcp__playwright__browser_take_screenshot()
+     → Save to .qa-output/uat-screenshots/{test-name}-step-{N}.png
+
+  3. Take accessibility snapshot to read page state:
+     mcp__playwright__browser_snapshot()
+
+  4. Record what the page shows:
+     - URL after action
+     - Visible text/headings
+     - Form state
+     - Error messages (if any)
+     - Elements visible/hidden
+```
+
+**Step 6c: Compare actual vs ticket**
+
+For each acceptance criterion from the ticket:
+
+| AC | Expected (from ticket) | Actual (from browser) | Screenshot | Verdict |
+|----|----------------------|---------------------|------------|---------|
+| AC-1 | User sees login form | Login form visible with email/password fields | step-1.png | MATCH |
+| AC-2 | After login, redirect to dashboard | Redirected to /dashboard, "Welcome" visible | step-3.png | MATCH |
+| AC-3 | Error message for wrong password | "Invalid credentials" alert shown | step-5.png | MATCH |
+| AC-4 | Remember me keeps session | Session persists after browser close | step-7.png | MISMATCH — session expired |
+
+Verdicts:
+- **MATCH** — actual behavior matches what the ticket describes
+- **MISMATCH** — actual behavior differs from ticket (could be app bug OR test not covering this AC)
+- **NOT TESTED** — ticket has an AC but no test step covers it
+- **EXTRA** — test covers something not in the ticket (informational, not a failure)
+
+**Step 6d: Produce UAT_VERIFICATION.md**
+
+```markdown
+# UAT Verification Report
+
+## Ticket Info
+
+| Field | Value |
+|-------|-------|
+| Source | {ticket URL or text} |
+| Title | {ticket title} |
+| ACs extracted | {count} |
+| Test files verified | {count} |
+
+## Step-by-Step Walkthrough
+
+### Step 1: {action description}
+- **Action:** Navigate to /login
+- **Screenshot:** [step-1.png](.qa-output/uat-screenshots/{test}-step-1.png)
+- **Page state:** Login form visible, email and password fields empty, "Log in" button enabled
+- **Matches AC:** AC-1 ✓
+
+### Step 2: {action description}
+- **Action:** Fill email "test@example.com", password "SecureP@ss123!"
+- **Screenshot:** [step-2.png]
+- **Page state:** Fields filled, button still enabled
+- **Matches AC:** (intermediate step, no AC)
+
+[... repeat per step ...]
+
+## AC Coverage Matrix
+
+| AC | Description | Tested | Verdict | Evidence |
+|----|-------------|--------|---------|----------|
+| AC-1 | Login form visible | Yes | MATCH | step-1.png |
+| AC-2 | Redirect to dashboard | Yes | MATCH | step-3.png |
+| AC-3 | Error on wrong password | Yes | MATCH | step-5.png |
+| AC-4 | Remember me session | No | NOT TESTED | — |
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| ACs from ticket | {N} |
+| ACs matched | {N} |
+| ACs mismatched | {N} |
+| ACs not tested | {N} |
+| Screenshots captured | {N} |
+| Overall | PASS / PARTIAL / FAIL |
+```
+
+Write to `.qa-output/UAT_VERIFICATION.md`.
+
+If any AC is MISMATCH or NOT TESTED, present to user with recommendation:
+- MISMATCH → "AC-4 says X but the app does Y — either the app has a bug or the test needs updating"
+- NOT TESTED → "AC-4 is not covered by any test step — consider adding a test case"
+
+---
+
+### VALIDATE MODE (`--validate-only`)
+
+1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules.
+2. Execute static validation workflow:
+
+Follow the workflow defined in `@workflows/qa-validate.md` end-to-end.
+Preserve all workflow gates (fix loops, layer checks).
+
+The validator runs 4 layers per file:
+1. **Syntax** — code compiles without errors
+2. **Structure** — naming, folders, POM compliance
+3. **Dependencies** — all imports resolve
+4. **Logic** — concrete assertions, Tier 1-2 locators, no assertions in POMs
+
+**Optional Layer 5 — labeled DOM-probe locator cross-check (if Playwright MCP connected + app URL available):**
+
+This layer is a STATIC locator cross-check via DOM probe. It is NOT test execution and never reports that tests passed:
+
+```
+[DOM_PROBE — NOT_TEST_EXECUTION]
+MCP DOM probe — NOT test execution.
+
+This observation comes from mcp__playwright__browser_* (live DOM inspection),
+NOT from the test runner (cypress run / npx playwright test / jest / vitest).
+
+It MAY assert ONLY: that the element was present in the DOM at the moment of
+the probe.
+
+It MUST NOT assert: that any test passes, that a proposed fix works, or that
+the element is visible/actionable under the framework's own rules (Cypress
+retry-ability, Playwright actionability checks, etc.).
+
+Any classification resting SOLELY on this probe MUST be marked LOW confidence.
+HIGH confidence requires a real test-runner execution with captured stdout/
+stderr and exit code.
+```
+
+- Navigate to each page referenced in E2E tests via `mcp__playwright__browser_navigate`
+- Take accessibility snapshot via `mcp__playwright__browser_snapshot`
+- Cross-reference test locators against real DOM elements
+- Flag locators that don't match, auto-fix mismatches
+
+Max 5 fix loop iterations. Produces VALIDATION_REPORT.md.
+
+If `--run` flag is also present and E2E test files exist, invoke E2E runner after static validation:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-e2e-runner.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-e2e-runner.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <objective>Run E2E tests against live application, capture real locators, fix mismatches, loop until pass. Query Context7 MCP to verify framework selector syntax before fixing locators.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-e2e-runner.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - .qa-output/research/E2E_STRATEGY.md (if exists)
+    - {E2E test files from validated directory}
+    - {POM files from validated directory}
+    </files_to_read>
+    <parameters>
+    app_url: {from --app-url flag or auto-detect}
+    output_dir: .qa-output
+    </parameters>
+  "
+)
+
+---
+
+### CLASSIFY MODE (`--classify`)
+
+Same as fix mode below but skip Step 4 (auto-fix). Only classify and report.
+
+---
+
+### FIX MODE (default)
+
+Fix mode runs in two phases: **analyze first, then fix after user confirmation.**
+
+#### Phase 1: Analyze & Present Plan (always runs)
+
+1. Read `CLAUDE.md` — classification rules, locator tiers, assertion quality.
+2. Invoke bug-detective agent in **classify-only mode** (no auto-fixes):
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-bug-detective.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-bug-detective.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <objective>Run tests and classify failures. Do NOT auto-fix anything yet — this is the analysis phase. Use Playwright MCP to reproduce E2E failures in the browser when available — navigate to failing pages, snapshot DOM, reproduce actions, and screenshot failure state for evidence. Query Context7 MCP to verify framework syntax when diagnosing failures.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-bug-detective.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists)
+    - .qa-output/codebase/API_CONTRACTS.md (if exists)
+    - .qa-output/codebase/TEST_SURFACE.md (if exists)
+    - .qa-output/codebase/TESTABILITY.md (if exists)
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - .qa-output/research/TESTING_STACK.md (if exists)
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: classify-only
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+3. Present the analysis to the user as a **fix plan**:
+
+```
+=== FIX PLAN ===
+
+Tests run: {N}
+Passed: {N}
+Failed: {N}
+
+Failures classified:
+  APPLICATION BUG:    {N} (will NOT be touched)
+  TEST CODE ERROR:    {N} (can auto-fix)
+  ENVIRONMENT ISSUE:  {N} (resolution steps provided)
+  INCONCLUSIVE:       {N} (needs more info)
+
+Proposed auto-fixes (TEST CODE ERRORS only):
+  1. {file}:{line} — {description of fix} [HIGH confidence]
+  2. {file}:{line} — {description of fix} [HIGH confidence]
+  3. {file}:{line} — {description of fix} [MEDIUM — flagged for review]
+
+APPLICATION BUGs found (for developer action):
+  1. {file}:{line} — {description}
+  2. {file}:{line} — {description}
+
+Proceed with auto-fixes? [yes / modify / cancel]
+================
+```
+
+4. **Wait for user confirmation.** Do NOT proceed until the user approves. This is a refinement loop — repeat until the user is satisfied:
+
+   - **"yes"** / **"proceed"** / **"dale"** → continue to Phase 2
+   - **"cancel"** / **"no"** → stop, deliver only the FAILURE_CLASSIFICATION_REPORT.md (same as --classify)
+   - **Any other response** (feedback, modifications, additions) → treat as a refinement request:
+     - Adjust the fix plan based on the user's instructions (add fixes, remove fixes, change approach, add new checks)
+     - Re-present the updated Fix Plan showing what changed
+     - Wait for user confirmation again
+     - Repeat this loop until the user says "yes" or "cancel"
+
+   **Examples of refinement requests:**
+   - "esto está bien pero también quiero que arregles los imports de utils" → add that fix to the plan
+   - "no toques el archivo de login, dejalo como está" → remove that file from the plan
+   - "cambiá el selector por getByRole en vez de getByTestId" → update the proposed fix
+   - "agregá también una validación de que el status sea 200" → add assertion fix to the plan
+
+#### Phase 2: Execute Fixes (only after user confirmation)
+
+5. Invoke bug-detective agent in **fix mode** with the confirmed plan:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-bug-detective.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-bug-detective.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <objective>Auto-fix the confirmed TEST CODE ERRORS from the analysis phase. Use Playwright MCP to reproduce E2E failures in the browser when available. Query Context7 MCP to verify correct framework syntax before applying any fix.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-bug-detective.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists)
+    - .qa-output/codebase/API_CONTRACTS.md (if exists)
+    - .qa-output/codebase/TEST_SURFACE.md (if exists)
+    - .qa-output/codebase/TESTABILITY.md (if exists)
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - .qa-output/research/TESTING_STACK.md (if exists)
+    - .qa-output/FAILURE_CLASSIFICATION_REPORT.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: fix
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+**Classification categories:**
+- **APPLICATION BUG** — error in production code → Report only, NEVER auto-fix
+- **TEST CODE ERROR** — error in test code → Auto-fix if HIGH confidence
+- **ENVIRONMENT ISSUE** — missing env, connection refused → Report with resolution steps
+- **INCONCLUSIVE** — ambiguous → Report what's known, ask for more info
+
+**Auto-fix rules:**
+- Only TEST CODE ERROR at HIGH confidence
+- Allowed fixes: import paths, selectors, assertion values, config, missing await, fixture paths
+- Every fix verified by re-running the specific test
+- Never modify application code (src/, app/, lib/)
+
+**Browser reproduction (when Playwright MCP connected):**
+- Navigate to failing page → snapshot DOM → reproduce action → screenshot
+- Element not in DOM → TEST CODE ERROR (HIGH confidence)
+- Element exists, wrong behavior → APPLICATION BUG
+- Page doesn't load → ENVIRONMENT ISSUE
+
+6. Present results. APPLICATION BUGs are reported for developer action, not auto-fixed.
+
+$ARGUMENTS
+
+## MANDATORY verification — run ALL commands below, no exceptions, no skipping
+
+Before returning control, copy-paste and run this ENTIRE block. Do NOT decide which commands "apply" — run all of them every time. The output confirms what happened; you do not get to assume the answer.
+
+```bash
+echo "=== QA-FIX CHECKLIST START ==="
+echo "1. Failure classification report:"
+ls .qa-output/FAILURE_CLASSIFICATION_REPORT.md 2>/dev/null || echo "NO_CLASSIFICATION_REPORT"
+echo "2. Locator Registry:"
+ls .qa-output/locators/ 2>/dev/null || echo "NO_LOCATORS_FOUND"
+echo "3. MY_PREFERENCES.md:"
+cat ~/.claude/qaa/MY_PREFERENCES.md 2>/dev/null || echo "FILE_NOT_FOUND"
+echo "4. Codebase map (context for bug-detective):"
+ls .qa-output/codebase/ 2>/dev/null || echo "NO_CODEBASE_MAP"
+echo "5. Test files in scope:"
+find tests/ cypress/ __tests__/ e2e/ spec/ -type f -name "*.spec.*" -o -name "*.test.*" -o -name "*.e2e.*" 2>/dev/null | head -20 || echo "NO_TEST_FILES_FOUND"
+echo "6. MCP evidence (if browser was used):"
+ls .qa-output/mcp-evidence/ 2>/dev/null || echo "NO_MCP_EVIDENCE"
+echo "7. Classification categories in report:"
+grep -cE "APPLICATION BUG|TEST CODE ERROR|ENVIRONMENT ISSUE|INCONCLUSIVE" .qa-output/FAILURE_CLASSIFICATION_REPORT.md 2>/dev/null || echo "NO_CLASSIFICATIONS"
+echo "=== QA-FIX CHECKLIST END ==="
+```
+
+**Rules:**
+- Run the block AS-IS. Do not modify it. Do not split it. Do not skip lines.
+- If any output shows a problem (NO_CLASSIFICATION_REPORT after fix mode completed), fix it before returning.
+- If output shows expected "not found" results (e.g., NO_MCP_EVIDENCE when no browser was used), that is fine — the point is you RAN the command instead of assuming the answer.
+- Do NOT mark this task as complete until the block has been executed and you have read every line of output.