qaa-agent 1.9.5 → 1.9.7

package/commands/qa-create-test.md

@@ -165,6 +165,58 @@ SUGGESTED_MODE=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').re
 
 The detector resolves the mode automatically when possible (from-ticket, from-aut, ado, etc.) and surfaces it in `SUGGESTED_MODE`. The mode detection logic in Step 1 below uses these resolved values.
 
+## Pre-flight checks
+
+Run these BEFORE the main flow. A **[STOP]** check that fails: print the error EXACTLY as shown (fill in the `{...}` placeholders) and STOP. A **[WARN]** check that fails: print the notice and continue in degraded mode.
+
+### Dev-repo path does not exist [STOP]
+If the resolved `--dev-repo` path is not an existing directory:
+```
+❌ Dev-repo path not found: {path}
+
+The --dev-repo path you gave does not exist (or is not a directory), so there's
+nothing to read the code from.
+
+Options:
+  1. Re-run with a correct path: /qa-create-test <feature> --dev-repo <path>
+  2. Run from inside the repo with no --dev-repo (defaults to the current directory)
+  3. Check for a typo or an unexpanded ~ in the path
+
+Try: ls {path}
+```
+
+### Playwright MCP not connected — from-aut mode [STOP]
+If MODE is from-aut and the Playwright MCP tools are unavailable:
+```
+❌ Playwright MCP is not connected — from-aut mode needs it to explore the app.
+
+from-aut generates tests by driving the live app with Playwright MCP. Without
+it, there's no way to discover real elements and locators.
+
+Options:
+  1. Connect Playwright MCP (it ships with QAA — check ~/.claude.json), then re-run
+  2. Reinstall to re-register the MCP servers: npx qaa-agent
+  3. Generate from the code instead (no live app needed): /qa-create-test <feature>
+
+Try: /mcp   (to see connected MCP servers)
+```
+
+### Framework not detectable — from-code mode [STOP]
+If MODE is from-code and no framework can be detected:
+```
+❌ Could not detect a test framework in {dev-repo}.
+
+from-code needs to know which framework to generate for. No config files or
+manifest entries pointed to one.
+
+Options:
+  1. Pass it explicitly: /qa-create-test <feature> --framework <playwright|cypress|jest|vitest|pytest|selenium|robot-framework>
+  2. Run /qa-map first to build the codebase map, then re-run
+  3. Add a framework to the repo (e.g. `npm i -D cypress`) and re-run
+
+Try: /qa-map   (to scan and detect the stack first)
+```
+
 ## Instructions
 
 ### Step 1: Detect Mode
@@ -227,6 +279,7 @@ App URL: {url or "auto-detect"}
 5. Invoke executor agent to generate test files:
 
 Task(
+  subagent_type="qaa-executor",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -280,6 +333,7 @@ Task(
 6. If E2E test files were generated AND `--skip-run` was NOT passed, invoke E2E runner:
 
 Task(
+  subagent_type="qaa-e2e-runner",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -366,6 +420,7 @@ Generate tests directly from a running application URL — no ticket, no spec, n
 6. After approval, invoke the executor to generate specs + POMs + fixtures:
 
 Task(
+  subagent_type="qaa-executor",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -485,6 +540,7 @@ For the complete step-by-step process, see `@commands/qa-create-test-ado.md`.
 2. Invoke validator agent in audit mode:
 
 Task(
+  subagent_type="qaa-validator",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -528,6 +584,7 @@ Task(
 4. Invoke executor agent to apply approved improvements:
 
 Task(
+  subagent_type="qaa-executor",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -587,6 +644,7 @@ Generate only Page Object Model files — no test specs.
 2. Invoke executor agent in POM-only mode:
 
 Task(
+  subagent_type="qaa-executor",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read

package/commands/qa-fix.md

@@ -115,6 +115,69 @@ TICKET=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSy
 
 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.
 
+## Pre-flight checks
+
+Run these BEFORE the main flow. If a **[STOP]** check fails, print the error EXACTLY as shown (fill in the `{...}` placeholders) and STOP.
+
+### Test files not found [STOP]
+- If a path/directory WAS passed but does not exist, print:
+```
+❌ Test path not found: {path}
+
+The path you passed to /qa-fix doesn't exist.
+
+Options:
+  1. Point at an existing file or directory: /qa-fix <path/to/tests>
+  2. Run from your QA repo root and pass no path (it auto-detects the suite)
+  3. Check for a typo or an unexpanded ~ in the path
+
+Try: ls {path}
+```
+- If NO path was passed and auto-detection found no test files, print (no `Try:` line — there's no path to show):
+```
+❌ No test files found to fix.
+
+/qa-fix auto-detected from the current directory but found no test files.
+
+Options:
+  1. Point at your tests explicitly: /qa-fix <path/to/tests>
+  2. Run from your QA repo root so auto-detection can find the suite
+  3. If you haven't generated tests yet, create them first: /qa-create-test <feature>
+```
+
+### Test runner can't execute [STOP]
+If the test runner binary is missing or fails to launch (an infra failure, not a test failure):
+```
+❌ The test runner could not start.
+
+The framework's runner (npx playwright / cypress / jest / vitest / pytest) is
+missing, misconfigured, or its dependencies aren't installed — so tests never
+ran. This is an ENVIRONMENT ISSUE, not a test failure.
+
+Options:
+  1. Install dependencies in the repo first: npm install  (or the project's equivalent)
+  2. Verify the runner works on its own before re-running /qa-fix
+  3. Run static validation only (no execution): /qa-fix --validate-only
+
+Try: npx {runner} --version   (to confirm the runner is installed)
+```
+
+### Playwright MCP not connected — E2E run requested [STOP]
+If `--run` / `--app-url` was passed (E2E reproduction against the live app) but Playwright MCP is unavailable:
+```
+❌ Playwright MCP is not connected — E2E reproduction against the app needs it.
+
+You asked to run E2E tests against the live app (--run / --app-url), which uses
+Playwright MCP to reproduce failures in the browser. It isn't available.
+
+Options:
+  1. Connect Playwright MCP (ships with QAA — check ~/.claude.json), then re-run
+  2. Reinstall to re-register the MCP servers: npx qaa-agent
+  3. Skip execution and only classify or validate: /qa-fix --classify  (or --validate-only)
+
+Try: /mcp
+```
+
 ## Instructions
 
 ### Step 1: Detect Mode and Test Directory
@@ -396,9 +459,9 @@ The validator runs 4 layers per file:
 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):**
+**Conditional Layer 5 — labeled DOM-probe locator cross-check (runs ONLY 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:
+This layer is a STATIC locator cross-check via DOM probe. It is NOT test execution, MUST NEVER be substituted for a real test run, and never reports that tests passed:
 
 ```
 [DOM_PROBE — NOT_TEST_EXECUTION]
@@ -429,6 +492,7 @@ 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(
+  subagent_type="qaa-e2e-runner",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -490,6 +554,7 @@ Fix mode runs in two phases: **analyze first, then fix after user confirmation.*
 2. Invoke bug-detective agent in **classify-only mode** (no auto-fixes):
 
 Task(
+  subagent_type="qaa-bug-detective",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -536,6 +601,8 @@ Task(
   "
 )
 
+**HARD STOP on broken runner (#48):** If the bug-detective returns `runner_executed: false` / `runner_status: BROKEN` (the suite never executed — ENVIRONMENT ISSUE), do NOT present a FIX PLAN and do NOT proceed to Phase 2. Surface the ENVIRONMENT ISSUE with the runner's startup error and stop. A DOM probe is NEVER a substitute for a real run; a report claiming classifications with `runner_executed: false` is INVALID.
+
 3. Present the analysis to the user as a **fix plan**:
 
 ```
@@ -564,7 +631,7 @@ 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:
+4. **HARD STOP — Phase 1 → Phase 2 gate.** Do NOT enter Phase 2 (execute fixes) until the user EXPLICITLY approves the FIX PLAN. No approval = no fixes — this gate is mandatory and cannot be skipped, assumed, or auto-satisfied by silence. 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)
@@ -582,9 +649,12 @@ Proceed with auto-fixes? [yes / modify / cancel]
 
 #### Phase 2: Execute Fixes (only after user confirmation)
 
+**Do NOT reach this phase without an explicit "yes" / "proceed" / "dale" from the Phase 1 → Phase 2 gate above.** If you have not received explicit approval, STOP — you are still in Phase 1.
+
 5. Invoke bug-detective agent in **fix mode** with the confirmed plan:
 
 Task(
+  subagent_type="qaa-bug-detective",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read

package/commands/qa-map.md

@@ -2,6 +2,40 @@
 
 Deep-scan a codebase for QA-relevant information, produce a complete analysis, and generate test inventory. Runs codebase mapping (4 parallel agents) followed by full repository analysis. One command to fully understand a codebase before writing tests.
 
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps. This command is flag-driven — there is no intent
+detector; read the flags from `$ARGUMENTS` literally.
+
+1. Read `CLAUDE.md` (QA standards) before anything else.
+2. Create the output directory: `mkdir -p .qa-output/codebase`.
+3. STAGE 1 — Codebase Mapping (see "## Instructions" Step 3):
+   - If neither `--skip-map` nor `--focus` was passed: spawn ALL 4
+     codebase-mapper agents IN PARALLEL (testability, risk, patterns,
+     existing-tests), each via Task() with its `<critical_directive>` block.
+   - If `--focus <area>` was passed: spawn ONLY that one agent, then STOP
+     (skip Stage 2 entirely).
+   - If `--skip-map` was passed: skip Stage 1 and go straight to Stage 2.
+4. Print the summary of documents produced by Stage 1.
+5. STAGE 2 — Repository Analysis: initialize pipeline context, then invoke the
+   scanner agent, then the analyzer agent — IN THAT ORDER, each via Task() with
+   its `<critical_directive>` block. Do NOT start the analyzer before the
+   scanner has produced SCAN_MANIFEST.md.
+6. Print the final summary of all documents produced across both stages.
+
+### DO NOT
+- Skip Stage 1 unless `--skip-map` was explicitly passed
+- Run Stage 2 when `--focus` was passed (focus mode stops after Stage 1)
+- Start the analyzer before the scanner completes
+- Run any git operation or generate any test files — this command only maps and
+  analyzes
+- Spawn the map/scan/analyze work inline instead of through the sub-agents
+- Invent steps not in this command, or reorder the ones that are
+
+If you find yourself improvising, reordering the stages, or generating tests —
+STOP and restart from step 1.
+
 ## Usage
 
 ```
@@ -39,6 +73,42 @@ All documents written to `.qa-output/codebase/`.
 | QA_REPO_BLUEPRINT.md | If no QA repo — full repo structure, configs, CI/CD strategy |
 | GAP_ANALYSIS.md | If QA repo provided — coverage map, missing tests, broken tests, quality assessment |
 
+## Pre-flight checks
+
+Run these BEFORE the main flow. If a **[STOP]** check fails, print the error EXACTLY as shown (fill in the `{...}` placeholders) and STOP.
+
+### Dev-repo path does not exist [STOP]
+If the resolved `--dev-repo` path is not an existing directory:
+```
+❌ Dev-repo path not found: {path}
+
+/qa-map scans a repository; the --dev-repo path you gave does not exist (or is
+not a directory).
+
+Options:
+  1. Re-run with a correct path: /qa-map --dev-repo <path>
+  2. Run from inside the repo with no --dev-repo (defaults to the current directory)
+  3. Check for a typo or an unexpanded ~ in the path
+
+Try: ls {path}
+```
+
+### No framework or testable surfaces detected [STOP]
+If the scan finds no framework and no source it can classify as a testable surface:
+```
+❌ Nothing testable detected in {dev-repo}.
+
+The scan found no test framework and no source it can classify as a testable
+surface, so there's nothing to map or analyze.
+
+Options:
+  1. Point at the app sub-directory if this is a monorepo: /qa-map --dev-repo <path/to/app>
+  2. Add a framework config to the repo first (playwright/cypress/jest/vitest/pytest), then re-run
+  3. To analyze an existing test suite, pass a QA repo: /qa-map --qa-repo <path>
+
+Try: ls {dev-repo}   (to confirm you're pointing at the right directory)
+```
+
 ## Instructions
 
 1. Read `CLAUDE.md` — QA standards.
@@ -79,7 +149,7 @@ Agent(
   trusted.
   </critical_directive>
 
-  subagent_type="general-purpose",
+  subagent_type="qaa-codebase-mapper",
   execution_context="~/.claude/qaa/agents/qaa-codebase-mapper.md"
 )
 
@@ -109,7 +179,7 @@ Agent(
   trusted.
   </critical_directive>
 
-  subagent_type="general-purpose",
+  subagent_type="qaa-codebase-mapper",
   execution_context="~/.claude/qaa/agents/qaa-codebase-mapper.md"
 )
 
@@ -139,7 +209,7 @@ Agent(
   trusted.
   </critical_directive>
 
-  subagent_type="general-purpose",
+  subagent_type="qaa-codebase-mapper",
   execution_context="~/.claude/qaa/agents/qaa-codebase-mapper.md"
 )
 
@@ -169,7 +239,7 @@ Agent(
   trusted.
   </critical_directive>
 
-  subagent_type="general-purpose",
+  subagent_type="qaa-codebase-mapper",
   execution_context="~/.claude/qaa/agents/qaa-codebase-mapper.md"
 )
 ```
@@ -190,6 +260,7 @@ node bin/qaa-tools.cjs init qa-start 2>/dev/null || true
 Invoke scanner agent:
 
 Task(
+  subagent_type="qaa-scanner",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -230,6 +301,7 @@ Task(
 Invoke analyzer agent:
 
 Task(
+  subagent_type="qaa-analyzer",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read

package/commands/qa-pr.md

@@ -75,6 +75,42 @@ TICKET=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSy
 
 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.
 
+## Pre-flight checks
+
+Run these BEFORE the main flow. If a **[STOP]** check fails, print the error EXACTLY as shown and STOP.
+
+### Not a git repository [STOP]
+If the current directory is not inside a git repository:
+```
+❌ Not a git repository.
+
+/qa-pr creates a branch, commits QA artifacts, and opens a pull request — all of
+which need a git repo. The current directory isn't one.
+
+Options:
+  1. Run from inside your QA repo (or the repo where the artifacts live)
+  2. Initialize git if this is a new repo: git init && git remote add origin <url>
+  3. If you just want the files locally, skip /qa-pr — the artifacts are already in .qa-output/
+
+Try: git status   (to confirm you're in a repo)
+```
+
+### GitHub CLI not available or not signed in [STOP]
+If `gh` is not installed or `gh auth status` fails:
+```
+❌ GitHub CLI (gh) is not available or not signed in.
+
+/qa-pr uses `gh` to open the draft pull request. It's either not installed or
+not authenticated, so the PR step can't run.
+
+Options:
+  1. Authenticate: gh auth login
+  2. Install the GitHub CLI first (https://cli.github.com), then re-run
+  3. Create the branch and commits locally, then open the PR by hand in your git host
+
+Try: gh auth status
+```
+
 ## Instructions
 
 1. Read `CLAUDE.md` -- git workflow, commit conventions.

package/commands/qa-research.md

@@ -2,6 +2,36 @@
 
 Research the testing ecosystem for the current project. Investigates framework capabilities, best practices, selector syntax, and testing patterns using Context7 MCP and official documentation. Produces research files consumed by all downstream QA agents (analyzer, planner, executor, validator).
 
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps. This command is flag-driven — there is no intent
+detector; parse the flags from `$ARGUMENTS` literally.
+
+1. STEP 1 — Initialize (see "## Instructions"): parse `$ARGUMENTS` for `--focus`
+   and `--dev-repo`, resolve MODE (default `stack-testing`) and DEV_REPO
+   (default: current directory), create `.qa-output/research/`, and print the
+   `=== QA Research ===` banner.
+2. STEP 2 — Read existing context if present: `.qa-output/SCAN_MANIFEST.md`,
+   `CLAUDE.md`, `~/.claude/qaa/MY_PREFERENCES.md`.
+3. STEP 3 — Spawn the project-researcher via Task() with its `<critical_directive>`
+   block, passing the resolved MODE and DEV_REPO. Do NOT do the research inline.
+4. STEP 4 — After the researcher returns, print the `=== Research Complete ===`
+   summary.
+5. Run the "## MANDATORY verification" checklist at the bottom of this file
+   before returning control.
+
+### DO NOT
+- Skip the `=== QA Research ===` banner
+- Do the research yourself inline instead of spawning the project-researcher
+- Invent a mode not in the `--focus` list, or reorder the steps
+- Skip the bottom verification checklist
+- Assume dev-repo path or mode from a previous command invocation — each
+  /qa-research call is self-contained
+
+If you find yourself improvising, doing the research inline, or skipping the
+verification checklist — STOP and restart from step 1.
+
 ## Usage
 
 ```
@@ -50,6 +80,42 @@ These files are consumed by downstream agents:
 | `API_TESTING_STRATEGY.md` | Planner (API test case design), Executor (implementation patterns) |
 | `E2E_STRATEGY.md` | Planner (E2E scope decisions), Executor (POM and selector patterns) |
 
+## Pre-flight checks
+
+Run these BEFORE the main flow. If a **[STOP]** check fails, print the error EXACTLY as shown (fill in the `{...}` placeholders) and STOP.
+
+### Context7 MCP not connected [STOP]
+If the Context7 MCP tools are unavailable:
+```
+❌ Context7 MCP is not connected — research needs it as the primary source.
+
+/qa-research relies on Context7 to fetch current framework and library docs.
+Without it, findings would fall back to training data and could be stale or wrong.
+
+Options:
+  1. Connect Context7 (it ships with QAA — check that it registered in ~/.claude.json)
+  2. Reinstall to re-register the MCP servers: npx qaa-agent
+  3. Skip research for now — downstream agents fall back to cache/training data if no research docs exist
+
+Try: /mcp   (to see connected MCP servers)
+```
+
+### Dev-repo path does not exist [STOP]
+If `--dev-repo` was passed but the path does not exist (default is the current directory):
+```
+❌ Dev-repo path not found: {path}
+
+/qa-research reads the project's stack to focus its research. The --dev-repo path
+you gave does not exist (or is not a directory).
+
+Options:
+  1. Re-run with a correct path: /qa-research --dev-repo <path>
+  2. Run from inside the repo with no --dev-repo (defaults to the current directory)
+  3. Check for a typo or an unexpanded ~ in the path
+
+Try: ls {path}
+```
+
 ## Instructions
 
 ### Step 1: Initialize
@@ -95,6 +161,7 @@ Read these files if they exist — they provide context to the researcher:
 ### Step 3: Spawn Researcher Agent
 
 Task(
+  subagent_type="qaa-project-researcher",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read

package/commands/qa-start.md

@@ -67,6 +67,43 @@ When the workflow's Step 1 invokes the intent detector with `$ARGUMENTS`, you mu
 
 If you pre-translate, the detector sees only flags and reports every value as `source: flag`, which causes `ALL_FROM_FLAGS=true` and bypasses the confirmation checkpoint — defeating its purpose. Always pass raw input.
 
+## Pre-flight checks
+
+Run these BEFORE spawning any agent. A **[STOP]** check that fails: print the error EXACTLY as shown (fill in the `{...}` placeholders) and STOP. A **[WARN]** check that fails: print the notice and continue in degraded mode.
+
+### Dev-repo path does not exist [STOP]
+If the resolved `--dev-repo` path is not an existing directory:
+```
+❌ Dev-repo path not found: {path}
+
+/qa-start needs a real directory to scan. The path resolved from your input
+does not exist (or is not a directory).
+
+Options:
+  1. Re-run with a correct path: /qa-start --dev-repo <path-to-your-repo>
+  2. Run from inside the repo with no path (defaults to the current directory)
+  3. Double-check the path — a typo or a ~ that did not expand is the usual cause
+
+Try: ls {path}
+```
+
+### Framework not detectable [STOP]
+If the scanner finds no test framework and no language/config it can map to one:
+```
+❌ Could not detect a test framework in {dev-repo}.
+
+QAA looks for a framework via config files (playwright.config, cypress.config,
+jest/vitest config, pytest.ini, etc.) and package manifests. None were found,
+so it can't decide how to write tests.
+
+Options:
+  1. Pass it explicitly: /qa-start --framework <playwright|cypress|jest|vitest|pytest|selenium|robot-framework>
+  2. Point at the app sub-directory if this is a monorepo: /qa-start --dev-repo <path/to/app>
+  3. Add a framework to the repo first (e.g. `npm i -D @playwright/test`), then re-run
+
+Try: /qa-research   (to investigate the stack before generating tests)
+```
+
 ## Instructions
 
 1. Read `CLAUDE.md` — all QA standards that govern the pipeline.

package/commands/qa-test-report.md

@@ -2,6 +2,41 @@
 
 Generate a per-ticket QA execution summary and append it to the Azure DevOps work item's `Custom.QATestCasesReport` field. For each test case linked to the work item, pull the execution status from ADO Test Runs — or prompt the user when ADO has no run result — then render a bulleted "Tested Scenarios" list (with a separate "Failures" section when anything failed).
 
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps. This command reads Azure DevOps and writes ONLY
+the `Custom.QATestCasesReport` field; it spawns no sub-agents and creates no
+test cases.
+
+1. PHASE 1 — Resolve the work item: if `$ARGUMENTS` has no work item ID, ask the
+   user before proceeding. Fetch it with `wit_get_work_item` (relations) plus
+   its comments.
+2. PHASE 2 — Resolve the test-case list. ADO is authoritative: build the list
+   from the *Tested By* links; a local `test-cases.md` is only a hint. If no TCs
+   are linked, print "nothing to report" and STOP.
+3. PHASE 3 — Resolve each TC's status (Passed/Failed/Blocked): try the ADO Test
+   Points REST endpoint first; for any TC that doesn't resolve, ask the user. For
+   Failed TCs, capture a reason (run data → comments → ask the user).
+4. PHASE 4 — Synthesize a readable one-line scenario description per TC (not the
+   raw TC title).
+5. PHASE 5 — Build BOTH the markdown (for chat) and HTML (for the field) reports.
+   Include the Failures section only if something failed.
+6. PHASE 6 — APPEND the HTML report to `Custom.QATestCasesReport`: re-read the
+   current value and preserve it (existing + `<br><br>` + new). Update ONLY that
+   field — never overwrite others.
+7. PHASE 7 — Print the markdown report + the append confirmation to the user.
+
+### DO NOT
+- OVERWRITE `Custom.QATestCasesReport` — always append, preserving prior content
+- Write to any field other than `Custom.QATestCasesReport`
+- Create test cases, change TC state, or create Test Runs (this command is read-mostly)
+- Copy raw TC titles as scenario descriptions when they are terse
+- Invent steps not in this command, or reorder the phases
+
+If you find yourself overwriting the field, touching other fields, or creating or
+modifying test cases — STOP and restart from step 1.
+
 ## Usage
 
 ```
@@ -22,6 +57,53 @@ Generate a per-ticket QA execution summary and append it to the Azure DevOps wor
 
 ---
 
+## Pre-flight checks
+
+Run these BEFORE the main flow. If a **[STOP]** check fails, print the error EXACTLY as shown (fill in the `{...}` placeholders) and STOP.
+
+### Azure DevOps MCP not connected [STOP]
+If the ADO MCP tools are unavailable:
+```
+❌ Azure DevOps MCP is not connected — this command reads from ADO.
+
+/qa-test-report pulls test-case execution status from Azure DevOps via the ADO
+MCP tools and REST API. They aren't available in this session.
+
+Options:
+  1. Connect the Azure DevOps MCP server, then re-run
+  2. Verify it's configured in your Claude Code MCP settings
+  3. Confirm ADO_MCP_AUTH_TOKEN is set if you also need the REST fallback for run outcomes
+
+Try: /mcp   (to see connected MCP servers)
+```
+
+### Work item ID missing or not found [STOP]
+- If NO work item ID was provided, print:
+```
+❌ No work item ID provided.
+
+/qa-test-report needs an Azure DevOps work item ID to build the report from its
+linked test cases.
+
+Options:
+  1. Pass one: /qa-test-report <work-item-id>
+  2. Copy the numeric ID from the work item's ADO URL
+  3. Confirm you have access to that work item's project
+
+Try: /qa-test-report 85508   (example)
+```
+- If an ID WAS provided but `wit_get_work_item` returns nothing for it, print:
+```
+❌ Work item not found: {id}
+
+The ID you gave doesn't resolve to a work item you can access.
+
+Options:
+  1. Double-check the numeric ID from the work item's ADO URL
+  2. Confirm you have access to that work item's project
+  3. Re-run with the correct ID: /qa-test-report <work-item-id>
+```
+
 ## Process
 
 ### Phase 1 — Resolve the Work Item