---
name: generate-test-cases
description: >-
  Use when creating or generating manual test cases for an Azure DevOps PBI, Bug, User Story,
  or Feature. Triggers on: "create test cases", "generate test cases", "link test cases",
  "manual tests", "TestedBy", "ADO test cases". Never creates test cases for Epics. Always
  confirms before creating test cases for a Feature.
license: MIT
compatibility: "Requires qa-test-case-manager MCP server. Azure DevOps connectivity required."
metadata:
  author: qa-gentic
  version: "1.1"
---

# Skill: Generate Test Cases from Azure DevOps Work Item

> **Read `AGENT-BEHAVIOR.md` before this skill.** The behavior rules there override any
> inference. This skill provides the step-by-step workflow only.

Use this skill when asked to generate, create, or write test cases for an Azure DevOps
PBI, Bug, User Story, or Feature.

---

## 🚨 HARD STOP RULES — Read Before Anything Else

**HARD STOP 0 — Never infer delivery destination.**
Generating test cases ≠ creating them in ADO. Show the user what you plan to create.
Get explicit confirmation. Do not auto-submit.

**HARD STOP 1 — Never create test cases for an Epic.**
Test cases in ADO are always scoped to PBIs, Bugs, or Features — never to Epics.
If the user provides an Epic ID and asks for test cases:
- Call `fetch_work_item` with the Epic ID — the tool will return `"error": "epic_not_supported"`.
- Inform the user explicitly:
  > "Manual test cases cannot be created or linked to an Epic in ADO.
  > Test cases must be attached to individual Features, PBIs, or Bugs.
  > Please look up the child Features of this Epic in Azure DevOps, then share
  > the Feature or PBI/Bug IDs and I will create test cases for each."
- Do NOT call `create_and_link_test_cases` with an Epic ID under any circumstances.

**HARD STOP 2 — Always ask for user confirmation before creating test cases for a Feature.**
When the target work item is a Feature, the server will return `"confirmation_required": true`.
At that point, **stop and ask the user**:
> "I'm about to create {N} manual test case(s) linked to Feature #{id} — "{title}".
> Please confirm (yes / no) before I proceed."
Do not call `create_and_link_test_cases` again until the user replies affirmatively.
If the user replies 'no' or 'cancel', abort and inform them no test cases were created.

## ⛔ Mandatory Pre-Flight: Deduplication Protocol

Before executing any step below, run the deduplication protocol
(see the `deduplication-protocol` skill).

The protocol is **work-item-scoped**: PHASE 1 runs once per `work_item_id` and its results
are cached. If this skill is invoked for the same `work_item_id` that another agent already
processed, skip PHASE 1 and read from `CACHE[work_item_id]` directly.
A different `work_item_id` always triggers a fresh PHASE 1.

---

## Steps

### Step 1 — Fetch the work item and existing test cases

**1A — Fetch the work item:**
Call `fetch_work_item` with the work item ID, organization URL, and project name.

The response contains:
- `work_item` — title, acceptance_criteria, description, repro_steps (for Bugs), story_points, priority, area_path, iteration_path
- `parent_feature` — parent Feature if present
- `existing_test_cases_count` — count of already-linked test cases (use as a signal only)
- `coverage_hints` — keys derived from AC text flagging areas that need coverage

**1B — Fetch existing test case titles (always, before generating):**
`existing_test_cases_count` is a count, not the actual titles. Two concurrent runs against the
same work item will duplicate test cases unless you fetch the real titles first.

```
qa-test-case-manager:get_linked_test_cases(
  organization_url : ...
  project_name     : ...
  work_item_id     : <same ID>
)
```

The response contains a `linked_test_cases` list with `id`, `title`, `state`, `priority`.
**Skip any test case whose title (or a near-identical paraphrase) already exists in this list.**
If `existing_test_cases_count` is 0 you may skip the call.

### Step 2 — Determine complexity
Use `story_points` and the count of distinct acceptance criteria:
- **Simple** (3–6 TCs): ≤ 2 points or ≤ 2 AC items
- **Medium** (6–12 TCs): 3–5 points or 3–5 AC items
- **Complex** (12–18 TCs): > 5 points or > 5 AC items

Add +1 TC for each `coverage_hint` not already addressed.

### Step 3 — Apply the granularity rule
Ask: "Does this step naturally flow into the next as part of one user journey?" If yes,
merge into ONE test case with multiple steps. Avoid micro-interaction test cases.

- ✗ BAD: TC="Slide-out opens", TC="File picker appears"
- ✓ GOOD: TC="User opens profile and initiates photo update" (multi-step)

### Step 4 — Design test cases covering all applicable categories

| Category | Description |
|---|---|
| Happy paths | Successful end-to-end flows |
| Success feedback | Toast/confirmation messages after success |
| Post-action state | UI reflects the change (photo displayed, count updated) |
| Validation errors | Invalid input, wrong format, missing required fields |
| Boundary conditions | Test AT the exact limit stated in ACs (exactly 5 MB, not 4 MB or 6 MB) |
| Edge cases | Empty state, default state, fallback display (initials avatar) |
| Negative scenarios | Failure states, error toasts, state unchanged after failure |
| Data persistence | Data survives page refresh or re-login |
| Computed/derived state | Values derived from other fields update correctly |
| Platform-specific | Mobile/webview scenarios when mentioned in ACs |
| Cancel flows | Cancel/discard discards changes without saving |

Apply every hint in `coverage_hints`. Skip titles already in the `linked_test_cases` list from Step 1B.

### Step 4B — Delivery gate (mandatory — do not skip)

Before calling `create_and_link_test_cases`, present the following to the user and wait:

```
I've designed {N} test cases for work item #{id} — "{title}".

Here is the list:
  1. {TC title}
  2. {TC title}
  ...

**Do you want me to create these in ADO now? (yes / no)**

Note:
- Saying yes here only creates test cases — it does not generate Gherkin or Playwright code.
- If you also want Gherkin or Playwright code, say so separately.
```

**Do not call `create_and_link_test_cases` until the user replies "yes".**
**Do not carry this confirmation forward to any other artifact.**

### Step 5 — Create and link
Call `create_and_link_test_cases` with your test cases. Do NOT specify `area_path` —
it is automatically inherited from the parent work item.

Each test case:
- `title` — clear, specific, describes what is being tested
- `steps` — array of `{ action, expected_result }` — at least 2 steps per TC
- `priority` — 1=Critical, 2=High (default), 3=Medium, 4=Low

**Automatic post-creation actions (server-side — no skill action required):**
- Each `TestedBy-Forward` relation is created with `"attributes": {"comment": "STLC-Agent generated test case"}` — this comment appears in the Links tab Comments column in ADO.
- The tag `STLCAgentTestCases` is appended to the parent work item (PBI/Bug/Feature).
Both are best-effort; a failure does not roll back test case creation.

## Example tool call

```json
{
  "work_item_id": 12345,
  "organization_url": "https://dev.azure.com/myorg",
  "project_name": "MyProject",
  "test_cases": [
    {
      "title": "TC_12345_01 — User uploads valid profile photo and sees success confirmation",
      "priority": 2,
      "steps": [
        {"action": "Navigate to My Profile slide-out", "expected_result": "Profile section opens showing current photo or initials"},
        {"action": "Click Update Photo and select a valid JPG file under 5 MB", "expected_result": "Image preview is shown in the crop editor"},
        {"action": "Adjust crop area and click Save", "expected_result": "Success toast 'Profile photo updated' is displayed and photo appears in the header"}
      ]
    }
  ]
}
```

---

## Explicit Delivery Rules — No Inference

| Decision | Rule |
|---|---|
| Generate test cases | Always: show the proposed list first |
| Create in ADO | Requires explicit "yes" at Step 4B gate |
| User says "no" at gate | Abort; report "No test cases created" |
| User confirms Feature test cases | Separate confirmation at HARD STOP 2 — not carried from Step 4B |
| Generate Gherkin next | Must be a separate user request — not triggered by this skill |
| Generate Playwright next | Must be a separate user request — not triggered by this skill |
| Save locally | Only if user explicitly says "save" or "download" |

**Each artifact delivery is independent. A yes/no for one does not answer any other.**
