qaa-agent 1.9.2 → 1.9.6

package/commands/qa-create-test-ado.md

@@ -1,404 +1,439 @@
-# QA Create Test — Azure DevOps
-
-Retrieve an Azure DevOps work item, analyze its content, and generate well-structured Test Cases directly in Azure DevOps using the ADO MCP tools. Each test case is tagged for test plan membership (Smoke, Regression, Critical) and linked back to the source work item for full traceability. Integrates with the QAA pipeline: reads codebase map, locator registry, and user preferences for context-aware test case generation.
-
-## Usage
-
-```
-/qa-create-test-ado <work-item-id> [--area-path=<path>] [--iteration-path=<path>] [--skip-map] [--skip-dedup] [--app-url <url>]
-```
-
-### Arguments
-
-| Parameter | Purpose | Default |
-|-----------|---------|---------|
-| `<work-item-id>` | Azure DevOps work item ID to generate test cases from | Required |
-| `--area-path=<path>` | Override area path for all created test artifacts | Source work item's area path |
-| `--iteration-path=<path>` | Override iteration path for all created test artifacts | Source work item's iteration path |
-| `--skip-map` | Skip codebase map check and proceed without project context | false |
-| `--skip-dedup` | Skip deduplication check against existing linked test cases | false |
-| `--app-url <url>` | URL of running application for locator extraction via Playwright MCP | auto-detect |
-
-## What It Produces
-
-- Test Cases created directly in Azure DevOps (via `testplan_create_test_case`)
-- Test Cases linked to source work item via *Tested By* relationship
-- Tags applied: `Smoke`, `Regression`, `Critical`, `AutomationCandidate`, `NeedsReview`
-- `ai-tasks/ticket-{id}/test-cases.md` — structured report
-- Report attached to work item (if `ADO_MCP_AUTH_TOKEN` is set) or written to `Custom.QATestCasesReport` field (fallback)
-
----
-
-## Process
-
-### Phase 1: Read Pipeline Context
-
-Before retrieving the work item, read QAA pipeline artifacts for context-aware generation.
-
-1. **Read `CLAUDE.md`** — POM rules, locator tiers, assertion rules, naming conventions, quality gates, test spec rules.
-
-2. **Read user preferences** — `~/.claude/qaa/MY_PREFERENCES.md` (if exists). User overrides win over defaults.
-
-3. **Check for codebase map** (`.qa-output/codebase/`):
-   - Look for: `CODE_PATTERNS.md`, `API_CONTRACTS.md`, `TEST_SURFACE.md`, `TESTABILITY.md`, `RISK_MAP.md`, `CRITICAL_PATHS.md`
-   - If at least 2 exist: read them all for project context (naming conventions, API shapes, testable surfaces, risk areas).
-   - If NONE exist and `--skip-map` not passed: warn the user that test cases will lack project context, suggest running `/qa-map` first. Continue anyway (ADO test cases are higher-level than code-level tests).
-
-4. **Check locator registry** — `.qa-output/locators/LOCATOR_REGISTRY.md` (if exists):
-   - If locators exist for pages related to the work item's feature: reference them in test step expected results (e.g., "Verify element `[data-testid='login-submit-btn']` is visible").
-   - If `--app-url` provided and locators missing: use Playwright MCP to extract locators from the live app before designing test steps:
-     ```
-     mcp__playwright__browser_navigate({ url: "{app_url}/{feature_path}" })
-     mcp__playwright__browser_snapshot()
-     ```
-   - Write extracted locators to `.qa-output/locators/{feature}.locators.md` and update the registry.
-
----
-
-### Phase 2: Retrieve the Work Item
-
-Use `wit_get_work_item` with `expand: "relations"` to fetch the full work item:
-
-- Capture: **title**, **type** (`Bug`, `User Story`, `Ticket`), **state**, **assigned-to**, **area path**, **iteration path**
-- Capture all relevant content fields based on type (see Phase 3)
-- Note the project for all subsequent calls
-
-**Also retrieve comments** using `wit_list_work_item_comments`:
-
-- Read all comments in chronological order
-- Look for: acceptance criteria added in comments, QA notes, scope clarifications, tester feedback, or any conditions of satisfaction mentioned informally
-- These often contain implied test cases not captured in the formal fields
-
-**Also check attachments** from the relations list (entries where `rel` equals `AttachedFile`):
-
-- Filter to `.csv` and `.txt` files (case-insensitive) by inspecting `attributes.name`
-- If found, download via:
-  ```bash
-  curl -s --user ":{AZURE_DEVOPS_PAT}" "{attachment-url}"
-  ```
-- Read content for test data, expected values, error logs, or sample datasets that define expected behavior
-
----
-
-### Phase 2b: Deduplication Check — Query Existing Test Cases
-
-Before generating any new test cases, check whether the source work item already has linked test cases to prevent duplicates.
-
-1. Inspect the relations returned in Phase 2 — filter for link type `"Microsoft.VSTS.Common.TestedBy-Forward"` (i.e., *Tested By* links).
-2. For each linked test case ID found, call `wit_get_work_item` to retrieve its **title** and **state**.
-3. Build an **existing TC registry** — a list of `{ id, title, state }` for all currently linked test cases.
-4. In Phase 5, before calling `testplan_create_test_case` for each planned TC, compare its title (normalized: lowercase, trimmed) against every title in the registry.
-   - **If match found** and existing TC is in state `Design`, `Ready`, or `Closed`: skip creation, log `"Skipped — duplicate of TC #{id}"`.
-   - **If match found** but existing TC is in state `Removed`: create the new TC anyway (the old one was intentionally discarded).
-   - **If no match**: proceed with creation.
-5. Include a **Dedup Summary** section in the output report.
-
-Skip this check with `--skip-dedup`.
-
----
-
-### Phase 3: Identify Work Item Type and Extract Test Source Content
-
-Apply the correct extraction strategy based on work item type:
-
-#### If type is `Bug` or `Ticket`:
-
-Primary source — **Repro Steps** (`Microsoft.VSTS.TCM.ReproSteps`):
-- Each distinct action sequence is a candidate test case
-- The repro steps define the *negative path* (what triggers the bug)
-- Derive the *positive/fix-verification path* by inverting the expected outcome
-- Also read: **System Info** (`Microsoft.VSTS.TCM.SystemInfo`), **Description**, **QA Notes** (`CIIScrum.QANotes`)
-- Check `Custom.Whatisexpectedtohappen` and `Custom.Whatisactuallyhappening` to anchor pass/fail assertions
-
-Secondary sources:
-- Comments for tester observations or specific scenarios to cover
-- Attachments for error data or sample inputs
-
-#### If type is `User Story`:
-
-Primary source — **Acceptance Criteria** (`Microsoft.VSTS.Common.AcceptanceCriteria`):
-- Each acceptance criterion (Given/When/Then or checklist) maps to one or more test cases
-- Also read: **Description** for context and implied behaviors
-
-Secondary sources:
-- Comments for clarifications, edge cases raised in refinement, or stakeholder scenarios
-- Attachments for wireframes described in text, sample data, or business rules documents
-
-#### If type is unrecognized or fields are empty:
-
-Fall back to **Description** as the primary source. Extract any stated behaviors, expected outcomes, or constraints. Note the fallback in the output.
-
-**Cross-reference with codebase map** (if available):
-- Match mentioned components/features against `TEST_SURFACE.md` entry points
-- Check `RISK_MAP.md` for risk level of affected areas
-- Use `API_CONTRACTS.md` for exact endpoint shapes if the work item mentions API behavior
-- Use `CODE_PATTERNS.md` to align test step language with project conventions
-
----
-
-### Phase 4: Analyze and Design Test Cases
-
-Before creating anything in Azure DevOps, plan out all test cases:
-
-**For each distinct scenario identified, determine:**
-
-1. **Test Case Title** — concise action-oriented name (e.g., "Verify guest pass entry counter resets at midnight")
-2. **Steps** — formatted as `{step action} | {expected result}` per step, using `|` as the delimiter
-3. **Priority** — 1 (Critical), 2 (High), 3 (Medium), 4 (Low)
-4. **Tags** — one or more of: `Smoke`, `Regression`, `Critical`, `AutomationCandidate`, `NeedsReview`
-5. **Preconditions** — required setup before executing the test
-6. **Confidence** — `Specified` or `Draft`
-
-**Minimum test case coverage per work item type:**
-
-| Scenario Type | Bug/Ticket | User Story |
-|---------------|-----------|------------|
-| Happy path (fix verified / AC met) | Required | Required per AC item |
-| Negative / error path | Required (original repro) | Where AC implies failure states |
-| Boundary / edge cases | If data-driven | If AC contains limits or conditions |
-| Boundary value triplets (n-1, n, n+1) | If limits detected | If AC contains limits/ranges |
-| Regression guard (related area) | Required | Required |
-
-#### Boundary Value Detection
-
-Scan all source content for **boundary keyword triggers**:
-
-> `max`, `min`, `limit`, `threshold`, `cap`, `ceiling`, `floor`, `range`, `between`, `up to`, `at most`, `at least`, `no more than`, `no fewer than`, `maximum`, `minimum`, `exactly`, `exceeds`, `boundary`
-
-When a trigger is found alongside a numeric value **N**:
-
-1. **Generate three test cases** (the boundary triplet):
-   - **N - 1** — just below the boundary
-   - **N** — exactly at the boundary
-   - **N + 1** — just above the boundary
-2. Title them clearly: e.g., `"Verify entry limit at 99 (below threshold)"`, `"...at 100 (at threshold)"`, `"...at 101 (above threshold)"`.
-3. Tag all three with `Regression`.
-4. If the boundary is on a critical-path field (per `CRITICAL_PATHS.md` or keyword detection), also tag `Critical`.
-
-If the source mentions a range, generate boundary triplets for **both** ends.
-
-#### Tagging Rules
-
-| Tag | Assign when... |
-|-----|---------------|
-| `Smoke` | Verifies core, user-facing functionality that must work for the app to be usable at all. Limit to the most essential 1-2 cases per work item. |
-| `Regression` | Guards against the specific bug or behavior being re-introduced. Every fix-verification test for a Bug/Ticket should be tagged. For User Stories, tag tests covering AC that touches shared or high-traffic code paths. |
-| `Critical` | Covers functionality whose failure would directly impact revenue, security, data integrity, or legal compliance. **Also apply when critical keywords are detected** (see Keyword-Based Critical Tagging below). Apply conservatively. |
-| `AutomationCandidate` | Test has: (a) deterministic steps with no subjective judgment, (b) assertions based on concrete data/state, (c) no manual-only prerequisites. Advisory only — QA confirms. |
-
-**Do not assign Smoke to every test case.** Smoke tests are a small, fast-running set.
-
-#### Keyword-Based Critical Tagging
-
-Automatically tag as `Critical` when any of the following keywords appear in the source content:
-
-> `auth`, `authentication`, `login`, `password`, `OAuth`, `SSO`, `payment`, `billing`, `charge`, `invoice`, `PII`, `personal data`, `SSN`, `date of birth`, `security`, `encryption`, `token`, `certificate`, `data integrity`, `transaction`, `rollback`, `compliance`, `HIPAA`, `GDPR`, `SOC`, `audit`, `permission`, `role-based`, `access control`
-
-Cross-reference with `RISK_MAP.md` (if available) for additional risk-based tagging.
-
-#### Confidence Scoring
-
-| Confidence | Criteria | Behavior |
-|------------|----------|----------|
-| **Specified** | Source content explicitly describes the scenario, expected outcome, and data. | Create the TC normally. |
-| **Draft** | Scenario is implied or partially described — inferred from context or sparse source. | Prefix TC title with `[DRAFT]`. Add `NeedsReview` tag. Add final step: `"Review — this test case was auto-generated from sparse source material and requires QA validation before execution." | "QA has reviewed and confirmed or updated the steps."` |
-
-**Threshold**: If more than 50% of the source content fields are empty or contain fewer than 20 words, default all inferred TCs to Draft.
-
-#### Preconditions Block
-
-Every test case documents preconditions:
-
-| Field | Description | Example |
-|-------|-------------|--------|
-| **Required Role(s)** | User role(s) or permission level(s) needed | `Admin`, `Property Manager`, `Resident` |
-| **Application State** | System/feature state that must be true before step 1 | `User is logged in`, `Feature flag X is enabled` |
-| **Test Data** | Specific data that must exist or be created | `Resident account with active lease` |
-| **Environment** | Environment-specific requirements | `Staging`, `API key configured` |
-
-Prepend preconditions to the TC description field in Azure DevOps:
-
-```
-**Preconditions**
-- Role(s): {roles}
-- State: {state}
-- Test Data: {data}
-- Environment: {env}
-```
-
-If locator registry data is available, include relevant locator references in test steps for E2E-related scenarios.
-
----
-
-### Phase 5: Create Test Cases in Azure DevOps
-
-**Dedup gate**: Before creating each TC, check against the registry from Phase 2b.
-
-For each planned test case, call `testplan_create_test_case` with:
-
-- `project`: the work item's project
-- `title`: the test case title — prefixed with `[DRAFT]` if confidence is Draft
-- `steps`: formatted as `1. {action}|{expected result}\n2. {action}|{expected result}` — use `|` as delimiter. **Never pass XML or pre-formatted `<steps>` markup** — the tool generates XML from plain-text format.
-- `priority`: numeric priority (1-4)
-- `iterationPath`: use `--iteration-path` override if provided, otherwise source work item's iteration path
-- `areaPath`: use `--area-path` override if provided, otherwise source work item's area path
-
-**After creating each test case:**
-
-1. Call `wit_add_artifact_link` or `wit_work_items_link` to link the new TC to the source work item using link type `"tested by"`:
-   ```
-   source work item  --[Tested By]-->  test case
-   ```
-
-2. Call `wit_update_work_item` on the new TC to set `System.Tags` to semicolon-separated tags (e.g., `"Regression; Critical; AutomationCandidate"`).
-   - Draft TCs always include `NeedsReview`.
-
-Create all test cases sequentially — capture each new TC ID before proceeding.
-
----
-
-### Phase 6: Synthesize the Output Report
-
-Save the report to `ai-tasks/ticket-$ARGUMENTS/test-cases.md`.
-
-**Required document structure:**
-
-```markdown
-# Test Cases: {work-item-id} — {Work Item Title}
-
-**Generated**: {current date}
-**Work Item**: [{work-item-id}]({azure-devops-url}) — {type} | {state}
-**Assigned To**: {assigned-to}
-**Area Path**: {area path}
-**Iteration**: {iteration path}
-**Test Source**: {Repro Steps / Acceptance Criteria / Description (fallback)}
-**Pipeline Context**: Codebase map: {yes/no}, Locator registry: {yes/no}, Preferences: {yes/no}
-
----
-
-## Source Analysis
-
-### Work Item Summary
-{2-3 sentences describing the work item and what behavior needed to be tested.}
-
-### Key Scenarios Identified
-{Bulleted list of distinct testable scenarios extracted before designing test cases.}
-
-### Source Content Notes
-{Observations about quality/completeness of source material. Were repro steps/AC clear? Did comments add scenarios?}
-
-### Codebase Context Used
-{If codebase map was available: list which documents were read and what context they provided. If not available: note that test cases were generated without codebase context.}
-
----
-
-## Test Cases Created
-
-### TC-{azure-devops-id}: {title}
-
-**Confidence**: `Specified` or `[DRAFT] — NeedsReview`
-**Tags**: `{Smoke}` · `{Regression}` · `{Critical}` · `{AutomationCandidate}` · `{NeedsReview}` *(show only tags that apply)*
-**Priority**: {1 – Critical / 2 – High / 3 – Medium / 4 – Low}
-**Linked To**: Work Item #{work-item-id} via *Tested By*
-**Azure DevOps ID**: {test-case-id}
-
-**Preconditions:**
-- **Role(s)**: {required roles or N/A}
-- **State**: {required application state or N/A}
-- **Test Data**: {required data or N/A}
-- **Environment**: {environment requirements or N/A}
-
-**Test Steps:**
-
-| # | Action | Expected Result |
-|---|--------|-----------------|
-| 1 | {action} | {expected result} |
-| 2 | {action} | {expected result} |
-
-{Repeat for each test case.}
-
----
-
-## Tag Summary
-
-| Tag | Count | Test Case IDs |
-|-----|-------|---------------|
-| Smoke | {n} | {comma-separated IDs} |
-| Regression | {n} | {comma-separated IDs} |
-| Critical | {n} | {comma-separated IDs} |
-| AutomationCandidate | {n} | {comma-separated IDs} |
-| NeedsReview | {n} | {comma-separated IDs} |
-
----
-
-## Dedup Summary
-
-| Planned Title | Skipped Reason | Existing TC |
-|---------------|---------------|-------------|
-| {title} | Duplicate of TC #{id} | #{id} — {state} |
-
-{If no duplicates: "No duplicates detected — all test cases were created."}
-
----
-
-## Traceability
-
-All test cases linked to work item **#{work-item-id}** via *Tested By*.
-
-**Path Overrides Applied**: {If --area-path or --iteration-path provided, state them. Otherwise: "None — used source work item paths."}
-**Confidence Breakdown**: {n} Specified, {n} Draft (NeedsReview)
-**Boundary Triplets Generated**: {n} (from {n} detected boundaries)
-```
-
----
-
-### Phase 7: Attach Report to Source Work Item
-
-**If `ADO_MCP_AUTH_TOKEN` is set:**
-
-Upload `test-cases.md` as an attachment:
-
-```bash
-# Step 1: Upload file
-ATTACHMENT_URL=$(curl -s \
-  --header "Authorization: Basic $(echo -n :${ADO_MCP_AUTH_TOKEN} | base64)" \
-  --header "Content-Type: application/octet-stream" \
-  --request POST \
-  --data-binary "@ai-tasks/ticket-$ARGUMENTS/test-cases.md" \
-  "https://dev.azure.com/{org}/{project}/_apis/wit/attachments?fileName=test-cases.md&api-version=7.1" \
-  | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")
-
-# Step 2: Link attachment to work item
-curl -s \
-  --header "Authorization: Basic $(echo -n :${ADO_MCP_AUTH_TOKEN} | base64)" \
-  --header "Content-Type: application/json-patch+json" \
-  --request PATCH \
-  --data "[{\"op\":\"add\",\"path\":\"/relations/-\",\"value\":{\"rel\":\"AttachedFile\",\"url\":\"${ATTACHMENT_URL}\",\"attributes\":{\"comment\":\"Generated test cases report\"}}}]" \
-  "https://dev.azure.com/{org}/{project}/_apis/wit/workItems/$ARGUMENTS?api-version=7.1"
-```
-
-**If `ADO_MCP_AUTH_TOKEN` is NOT set (fallback):**
-
-Write the full report as HTML to the work item's `Custom.QATestCasesReport` field via `wit_update_work_item`. Include all sections converted to HTML.
-
-Note in the final report which method was used.
-
----
-
-## Final Report to User
-
-After completing all phases, provide:
-
-1. Brief inline summary (2-3 sentences) of scenarios covered
-2. Full path to generated file: `ai-tasks/ticket-{id}/test-cases.md`
-3. Table of every created TC: ID, title, tags, confidence
-4. Counts by tag: Smoke, Regression, Critical, AutomationCandidate, NeedsReview
-5. Dedup summary: how many planned TCs were skipped
-6. Confidence summary: Specified vs Draft counts
-7. Boundary summary: how many boundary triplets generated
-8. Pipeline context: which codebase map documents and locator registry data were used
-9. Gaps or assumptions made
-10. Path override confirmation (if used)
-11. Report delivery confirmation (attached as file or written to custom field)
-
-$ARGUMENTS
+# QA Create Test — Azure DevOps
+
+Retrieve an Azure DevOps work item, analyze its content, and generate well-structured Test Cases directly in Azure DevOps using the ADO MCP tools. Each test case is tagged for test plan membership (Smoke, Regression, Critical) and linked back to the source work item for full traceability. Integrates with the QAA pipeline: reads codebase map, locator registry, and user preferences for context-aware test case generation.
+
+## ⚠ 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 talks to Azure DevOps via the ADO
+MCP tools; it spawns no sub-agents.
+
+1. Resolve the work item ID from `$ARGUMENTS` — it is REQUIRED. If missing, ask
+   the user before doing anything else.
+2. PHASE 1 — Read pipeline context: `CLAUDE.md`, `~/.claude/qaa/MY_PREFERENCES.md`
+   (if it exists), the codebase map (`.qa-output/codebase/`), and the locator
+   registry. If no codebase map and `--skip-map` was not passed, warn and continue.
+3. PHASE 2 — Retrieve the work item (`wit_get_work_item` with relations), its
+   comments, and its attachments.
+4. PHASE 2b — Deduplication check: build the registry of already-linked test
+   cases (unless `--skip-dedup`). This gate is mandatory before creating anything.
+5. PHASE 3-4 — Identify the work item type, extract test-source content, and
+   design ALL test cases (titles, steps, priority, tags, preconditions,
+   confidence) BEFORE creating anything in ADO.
+6. PHASE 5 — Create the test cases in ADO: apply the dedup gate before each one,
+   link every new TC to the source work item via *Tested By*, and set its tags.
+   Pass steps as plain text with `|` delimiters — NEVER XML / `<steps>` markup.
+7. PHASE 6-7 — Synthesize the report to `ai-tasks/ticket-{id}/test-cases.md`,
+   attach it to the work item (or write to `Custom.QATestCasesReport` as a
+   fallback), then give the final summary to the user.
+
+### DO NOT
+- Create any test case before the deduplication check (unless `--skip-dedup`)
+- Skip linking each new TC via *Tested By*, or skip setting its tags
+- Pass pre-formatted XML / `<steps>` to `testplan_create_test_case` (plain text + `|`)
+- Overwrite unrelated work-item fields
+- Invent steps not in this command, or reorder the phases
+
+If you find yourself creating test cases before dedup, skipping the *Tested By*
+links, or passing XML steps — STOP and restart from step 1.
+
+## Usage
+
+```
+/qa-create-test-ado <work-item-id> [--area-path=<path>] [--iteration-path=<path>] [--skip-map] [--skip-dedup] [--app-url <url>]
+```
+
+### Arguments
+
+| Parameter | Purpose | Default |
+|-----------|---------|---------|
+| `<work-item-id>` | Azure DevOps work item ID to generate test cases from | Required |
+| `--area-path=<path>` | Override area path for all created test artifacts | Source work item's area path |
+| `--iteration-path=<path>` | Override iteration path for all created test artifacts | Source work item's iteration path |
+| `--skip-map` | Skip codebase map check and proceed without project context | false |
+| `--skip-dedup` | Skip deduplication check against existing linked test cases | false |
+| `--app-url <url>` | URL of running application for locator extraction via Playwright MCP | auto-detect |
+
+## What It Produces
+
+- Test Cases created directly in Azure DevOps (via `testplan_create_test_case`)
+- Test Cases linked to source work item via *Tested By* relationship
+- Tags applied: `Smoke`, `Regression`, `Critical`, `AutomationCandidate`, `NeedsReview`
+- `ai-tasks/ticket-{id}/test-cases.md` — structured report
+- Report attached to work item (if `ADO_MCP_AUTH_TOKEN` is set) or written to `Custom.QATestCasesReport` field (fallback)
+
+---
+
+## Process
+
+### Phase 1: Read Pipeline Context
+
+Before retrieving the work item, read QAA pipeline artifacts for context-aware generation.
+
+1. **Read `CLAUDE.md`** — POM rules, locator tiers, assertion rules, naming conventions, quality gates, test spec rules.
+
+2. **Read user preferences** — `~/.claude/qaa/MY_PREFERENCES.md` (if exists). User overrides win over defaults.
+
+3. **Check for codebase map** (`.qa-output/codebase/`):
+   - Look for: `CODE_PATTERNS.md`, `API_CONTRACTS.md`, `TEST_SURFACE.md`, `TESTABILITY.md`, `RISK_MAP.md`, `CRITICAL_PATHS.md`
+   - If at least 2 exist: read them all for project context (naming conventions, API shapes, testable surfaces, risk areas).
+   - If NONE exist and `--skip-map` not passed: warn the user that test cases will lack project context, suggest running `/qa-map` first. Continue anyway (ADO test cases are higher-level than code-level tests).
+
+4. **Check locator registry** — `.qa-output/locators/LOCATOR_REGISTRY.md` (if exists):
+   - If locators exist for pages related to the work item's feature: reference them in test step expected results (e.g., "Verify element `[data-testid='login-submit-btn']` is visible").
+   - If `--app-url` provided and locators missing: use Playwright MCP to extract locators from the live app before designing test steps:
+     ```
+     mcp__playwright__browser_navigate({ url: "{app_url}/{feature_path}" })
+     mcp__playwright__browser_snapshot()
+     ```
+   - Write extracted locators to `.qa-output/locators/{feature}.locators.md` and update the registry.
+
+---
+
+### Phase 2: Retrieve the Work Item
+
+Use `wit_get_work_item` with `expand: "relations"` to fetch the full work item:
+
+- Capture: **title**, **type** (`Bug`, `User Story`, `Ticket`), **state**, **assigned-to**, **area path**, **iteration path**
+- Capture all relevant content fields based on type (see Phase 3)
+- Note the project for all subsequent calls
+
+**Also retrieve comments** using `wit_list_work_item_comments`:
+
+- Read all comments in chronological order
+- Look for: acceptance criteria added in comments, QA notes, scope clarifications, tester feedback, or any conditions of satisfaction mentioned informally
+- These often contain implied test cases not captured in the formal fields
+
+**Also check attachments** from the relations list (entries where `rel` equals `AttachedFile`):
+
+- Filter to `.csv` and `.txt` files (case-insensitive) by inspecting `attributes.name`
+- If found, download via:
+  ```bash
+  curl -s --user ":{AZURE_DEVOPS_PAT}" "{attachment-url}"
+  ```
+- Read content for test data, expected values, error logs, or sample datasets that define expected behavior
+
+---
+
+### Phase 2b: Deduplication Check — Query Existing Test Cases
+
+Before generating any new test cases, check whether the source work item already has linked test cases to prevent duplicates.
+
+1. Inspect the relations returned in Phase 2 — filter for link type `"Microsoft.VSTS.Common.TestedBy-Forward"` (i.e., *Tested By* links).
+2. For each linked test case ID found, call `wit_get_work_item` to retrieve its **title** and **state**.
+3. Build an **existing TC registry** — a list of `{ id, title, state }` for all currently linked test cases.
+4. In Phase 5, before calling `testplan_create_test_case` for each planned TC, compare its title (normalized: lowercase, trimmed) against every title in the registry.
+   - **If match found** and existing TC is in state `Design`, `Ready`, or `Closed`: skip creation, log `"Skipped — duplicate of TC #{id}"`.
+   - **If match found** but existing TC is in state `Removed`: create the new TC anyway (the old one was intentionally discarded).
+   - **If no match**: proceed with creation.
+5. Include a **Dedup Summary** section in the output report.
+
+Skip this check with `--skip-dedup`.
+
+---
+
+### Phase 3: Identify Work Item Type and Extract Test Source Content
+
+Apply the correct extraction strategy based on work item type:
+
+#### If type is `Bug` or `Ticket`:
+
+Primary source — **Repro Steps** (`Microsoft.VSTS.TCM.ReproSteps`):
+- Each distinct action sequence is a candidate test case
+- The repro steps define the *negative path* (what triggers the bug)
+- Derive the *positive/fix-verification path* by inverting the expected outcome
+- Also read: **System Info** (`Microsoft.VSTS.TCM.SystemInfo`), **Description**, **QA Notes** (`CIIScrum.QANotes`)
+- Check `Custom.Whatisexpectedtohappen` and `Custom.Whatisactuallyhappening` to anchor pass/fail assertions
+
+Secondary sources:
+- Comments for tester observations or specific scenarios to cover
+- Attachments for error data or sample inputs
+
+#### If type is `User Story`:
+
+Primary source — **Acceptance Criteria** (`Microsoft.VSTS.Common.AcceptanceCriteria`):
+- Each acceptance criterion (Given/When/Then or checklist) maps to one or more test cases
+- Also read: **Description** for context and implied behaviors
+
+Secondary sources:
+- Comments for clarifications, edge cases raised in refinement, or stakeholder scenarios
+- Attachments for wireframes described in text, sample data, or business rules documents
+
+#### If type is unrecognized or fields are empty:
+
+Fall back to **Description** as the primary source. Extract any stated behaviors, expected outcomes, or constraints. Note the fallback in the output.
+
+**Cross-reference with codebase map** (if available):
+- Match mentioned components/features against `TEST_SURFACE.md` entry points
+- Check `RISK_MAP.md` for risk level of affected areas
+- Use `API_CONTRACTS.md` for exact endpoint shapes if the work item mentions API behavior
+- Use `CODE_PATTERNS.md` to align test step language with project conventions
+
+---
+
+### Phase 4: Analyze and Design Test Cases
+
+Before creating anything in Azure DevOps, plan out all test cases:
+
+**For each distinct scenario identified, determine:**
+
+1. **Test Case Title** — concise action-oriented name (e.g., "Verify guest pass entry counter resets at midnight")
+2. **Steps** — formatted as `{step action} | {expected result}` per step, using `|` as the delimiter
+3. **Priority** — 1 (Critical), 2 (High), 3 (Medium), 4 (Low)
+4. **Tags** — one or more of: `Smoke`, `Regression`, `Critical`, `AutomationCandidate`, `NeedsReview`
+5. **Preconditions** — required setup before executing the test
+6. **Confidence** — `Specified` or `Draft`
+
+**Minimum test case coverage per work item type:**
+
+| Scenario Type | Bug/Ticket | User Story |
+|---------------|-----------|------------|
+| Happy path (fix verified / AC met) | Required | Required per AC item |
+| Negative / error path | Required (original repro) | Where AC implies failure states |
+| Boundary / edge cases | If data-driven | If AC contains limits or conditions |
+| Boundary value triplets (n-1, n, n+1) | If limits detected | If AC contains limits/ranges |
+| Regression guard (related area) | Required | Required |
+
+#### Boundary Value Detection
+
+Scan all source content for **boundary keyword triggers**:
+
+> `max`, `min`, `limit`, `threshold`, `cap`, `ceiling`, `floor`, `range`, `between`, `up to`, `at most`, `at least`, `no more than`, `no fewer than`, `maximum`, `minimum`, `exactly`, `exceeds`, `boundary`
+
+When a trigger is found alongside a numeric value **N**:
+
+1. **Generate three test cases** (the boundary triplet):
+   - **N - 1** — just below the boundary
+   - **N** — exactly at the boundary
+   - **N + 1** — just above the boundary
+2. Title them clearly: e.g., `"Verify entry limit at 99 (below threshold)"`, `"...at 100 (at threshold)"`, `"...at 101 (above threshold)"`.
+3. Tag all three with `Regression`.
+4. If the boundary is on a critical-path field (per `CRITICAL_PATHS.md` or keyword detection), also tag `Critical`.
+
+If the source mentions a range, generate boundary triplets for **both** ends.
+
+#### Tagging Rules
+
+| Tag | Assign when... |
+|-----|---------------|
+| `Smoke` | Verifies core, user-facing functionality that must work for the app to be usable at all. Limit to the most essential 1-2 cases per work item. |
+| `Regression` | Guards against the specific bug or behavior being re-introduced. Every fix-verification test for a Bug/Ticket should be tagged. For User Stories, tag tests covering AC that touches shared or high-traffic code paths. |
+| `Critical` | Covers functionality whose failure would directly impact revenue, security, data integrity, or legal compliance. **Also apply when critical keywords are detected** (see Keyword-Based Critical Tagging below). Apply conservatively. |
+| `AutomationCandidate` | Test has: (a) deterministic steps with no subjective judgment, (b) assertions based on concrete data/state, (c) no manual-only prerequisites. Advisory only — QA confirms. |
+
+**Do not assign Smoke to every test case.** Smoke tests are a small, fast-running set.
+
+#### Keyword-Based Critical Tagging
+
+Automatically tag as `Critical` when any of the following keywords appear in the source content:
+
+> `auth`, `authentication`, `login`, `password`, `OAuth`, `SSO`, `payment`, `billing`, `charge`, `invoice`, `PII`, `personal data`, `SSN`, `date of birth`, `security`, `encryption`, `token`, `certificate`, `data integrity`, `transaction`, `rollback`, `compliance`, `HIPAA`, `GDPR`, `SOC`, `audit`, `permission`, `role-based`, `access control`
+
+Cross-reference with `RISK_MAP.md` (if available) for additional risk-based tagging.
+
+#### Confidence Scoring
+
+| Confidence | Criteria | Behavior |
+|------------|----------|----------|
+| **Specified** | Source content explicitly describes the scenario, expected outcome, and data. | Create the TC normally. |
+| **Draft** | Scenario is implied or partially described — inferred from context or sparse source. | Prefix TC title with `[DRAFT]`. Add `NeedsReview` tag. Add final step: `"Review — this test case was auto-generated from sparse source material and requires QA validation before execution." | "QA has reviewed and confirmed or updated the steps."` |
+
+**Threshold**: If more than 50% of the source content fields are empty or contain fewer than 20 words, default all inferred TCs to Draft.
+
+#### Preconditions Block
+
+Every test case documents preconditions:
+
+| Field | Description | Example |
+|-------|-------------|--------|
+| **Required Role(s)** | User role(s) or permission level(s) needed | `Admin`, `Property Manager`, `Resident` |
+| **Application State** | System/feature state that must be true before step 1 | `User is logged in`, `Feature flag X is enabled` |
+| **Test Data** | Specific data that must exist or be created | `Resident account with active lease` |
+| **Environment** | Environment-specific requirements | `Staging`, `API key configured` |
+
+Prepend preconditions to the TC description field in Azure DevOps:
+
+```
+**Preconditions**
+- Role(s): {roles}
+- State: {state}
+- Test Data: {data}
+- Environment: {env}
+```
+
+If locator registry data is available, include relevant locator references in test steps for E2E-related scenarios.
+
+---
+
+### Phase 5: Create Test Cases in Azure DevOps
+
+**Dedup gate**: Before creating each TC, check against the registry from Phase 2b.
+
+For each planned test case, call `testplan_create_test_case` with:
+
+- `project`: the work item's project
+- `title`: the test case title — prefixed with `[DRAFT]` if confidence is Draft
+- `steps`: formatted as `1. {action}|{expected result}\n2. {action}|{expected result}` — use `|` as delimiter. **Never pass XML or pre-formatted `<steps>` markup** — the tool generates XML from plain-text format.
+- `priority`: numeric priority (1-4)
+- `iterationPath`: use `--iteration-path` override if provided, otherwise source work item's iteration path
+- `areaPath`: use `--area-path` override if provided, otherwise source work item's area path
+
+**After creating each test case:**
+
+1. Call `wit_add_artifact_link` or `wit_work_items_link` to link the new TC to the source work item using link type `"tested by"`:
+   ```
+   source work item  --[Tested By]-->  test case
+   ```
+
+2. Call `wit_update_work_item` on the new TC to set `System.Tags` to semicolon-separated tags (e.g., `"Regression; Critical; AutomationCandidate"`).
+   - Draft TCs always include `NeedsReview`.
+
+Create all test cases sequentially — capture each new TC ID before proceeding.
+
+---
+
+### Phase 6: Synthesize the Output Report
+
+Save the report to `ai-tasks/ticket-$ARGUMENTS/test-cases.md`.
+
+**Required document structure:**
+
+```markdown
+# Test Cases: {work-item-id} — {Work Item Title}
+
+**Generated**: {current date}
+**Work Item**: [{work-item-id}]({azure-devops-url}) — {type} | {state}
+**Assigned To**: {assigned-to}
+**Area Path**: {area path}
+**Iteration**: {iteration path}
+**Test Source**: {Repro Steps / Acceptance Criteria / Description (fallback)}
+**Pipeline Context**: Codebase map: {yes/no}, Locator registry: {yes/no}, Preferences: {yes/no}
+
+---
+
+## Source Analysis
+
+### Work Item Summary
+{2-3 sentences describing the work item and what behavior needed to be tested.}
+
+### Key Scenarios Identified
+{Bulleted list of distinct testable scenarios extracted before designing test cases.}
+
+### Source Content Notes
+{Observations about quality/completeness of source material. Were repro steps/AC clear? Did comments add scenarios?}
+
+### Codebase Context Used
+{If codebase map was available: list which documents were read and what context they provided. If not available: note that test cases were generated without codebase context.}
+
+---
+
+## Test Cases Created
+
+### TC-{azure-devops-id}: {title}
+
+**Confidence**: `Specified` or `[DRAFT] — NeedsReview`
+**Tags**: `{Smoke}` · `{Regression}` · `{Critical}` · `{AutomationCandidate}` · `{NeedsReview}` *(show only tags that apply)*
+**Priority**: {1 – Critical / 2 – High / 3 – Medium / 4 – Low}
+**Linked To**: Work Item #{work-item-id} via *Tested By*
+**Azure DevOps ID**: {test-case-id}
+
+**Preconditions:**
+- **Role(s)**: {required roles or N/A}
+- **State**: {required application state or N/A}
+- **Test Data**: {required data or N/A}
+- **Environment**: {environment requirements or N/A}
+
+**Test Steps:**
+
+| # | Action | Expected Result |
+|---|--------|-----------------|
+| 1 | {action} | {expected result} |
+| 2 | {action} | {expected result} |
+
+{Repeat for each test case.}
+
+---
+
+## Tag Summary
+
+| Tag | Count | Test Case IDs |
+|-----|-------|---------------|
+| Smoke | {n} | {comma-separated IDs} |
+| Regression | {n} | {comma-separated IDs} |
+| Critical | {n} | {comma-separated IDs} |
+| AutomationCandidate | {n} | {comma-separated IDs} |
+| NeedsReview | {n} | {comma-separated IDs} |
+
+---
+
+## Dedup Summary
+
+| Planned Title | Skipped Reason | Existing TC |
+|---------------|---------------|-------------|
+| {title} | Duplicate of TC #{id} | #{id} — {state} |
+
+{If no duplicates: "No duplicates detected — all test cases were created."}
+
+---
+
+## Traceability
+
+All test cases linked to work item **#{work-item-id}** via *Tested By*.
+
+**Path Overrides Applied**: {If --area-path or --iteration-path provided, state them. Otherwise: "None — used source work item paths."}
+**Confidence Breakdown**: {n} Specified, {n} Draft (NeedsReview)
+**Boundary Triplets Generated**: {n} (from {n} detected boundaries)
+```
+
+---
+
+### Phase 7: Attach Report to Source Work Item
+
+**If `ADO_MCP_AUTH_TOKEN` is set:**
+
+Upload `test-cases.md` as an attachment:
+
+```bash
+# Step 1: Upload file
+ATTACHMENT_URL=$(curl -s \
+  --header "Authorization: Basic $(echo -n :${ADO_MCP_AUTH_TOKEN} | base64)" \
+  --header "Content-Type: application/octet-stream" \
+  --request POST \
+  --data-binary "@ai-tasks/ticket-$ARGUMENTS/test-cases.md" \
+  "https://dev.azure.com/{org}/{project}/_apis/wit/attachments?fileName=test-cases.md&api-version=7.1" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['url'])")
+
+# Step 2: Link attachment to work item
+curl -s \
+  --header "Authorization: Basic $(echo -n :${ADO_MCP_AUTH_TOKEN} | base64)" \
+  --header "Content-Type: application/json-patch+json" \
+  --request PATCH \
+  --data "[{\"op\":\"add\",\"path\":\"/relations/-\",\"value\":{\"rel\":\"AttachedFile\",\"url\":\"${ATTACHMENT_URL}\",\"attributes\":{\"comment\":\"Generated test cases report\"}}}]" \
+  "https://dev.azure.com/{org}/{project}/_apis/wit/workItems/$ARGUMENTS?api-version=7.1"
+```
+
+**If `ADO_MCP_AUTH_TOKEN` is NOT set (fallback):**
+
+Write the full report as HTML to the work item's `Custom.QATestCasesReport` field via `wit_update_work_item`. Include all sections converted to HTML.
+
+Note in the final report which method was used.
+
+---
+
+## Final Report to User
+
+After completing all phases, provide:
+
+1. Brief inline summary (2-3 sentences) of scenarios covered
+2. Full path to generated file: `ai-tasks/ticket-{id}/test-cases.md`
+3. Table of every created TC: ID, title, tags, confidence
+4. Counts by tag: Smoke, Regression, Critical, AutomationCandidate, NeedsReview
+5. Dedup summary: how many planned TCs were skipped
+6. Confidence summary: Specified vs Draft counts
+7. Boundary summary: how many boundary triplets generated
+8. Pipeline context: which codebase map documents and locator registry data were used
+9. Gaps or assumptions made
+10. Path override confirmation (if used)
+11. Report delivery confirmation (attached as file or written to custom field)
+
+$ARGUMENTS