---
name: generate-gherkin
description: >-
  Use when generating Gherkin feature files, BDD scenarios, or .feature files from Azure DevOps
  or Jira work items. Triggers on: "Gherkin", "feature file", "BDD", "scenarios", "acceptance
  criteria automation", "Given When Then", "regression suite". Enforces live navigation before
  writing any scenario and links generated files back to work items. Works with Feature,
  PBI, and Bug work item types.
license: MIT
compatibility: "Requires qa-gherkin-generator, qa-playwright-generator, qa-test-case-manager MCP servers and Playwright MCP running at localhost:8931 for live locator verification."
metadata:
  author: qa-gentic
  version: "1.1"
---

# Generate Gherkin Skill

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

Generate production-quality Gherkin regression suites from ADO work items (PBI, Bug, or Feature),
with full navigation context in every scenario, then optionally produce Playwright automation.

For the live navigation workflow, scenario writing, validation, delivery gate, quality gates,
and navigation step wording catalogue → see [references/step-by-step.md](references/step-by-step.md).

---

## 🚨 HARD STOP RULES — Read Before Anything Else

These rules override every other instruction in this skill.

**HARD STOP 1 — Never write Gherkin for a screen you have not navigated to live.**
If a scenario requires a state-dependent screen (one that only appears after an upload,
form submit, error trigger, or multi-step flow), you MUST reach that screen in the live app
before writing the scenario. If you cannot reach it with the information you currently have,
ask the user and wait. Do not proceed.

**HARD STOP 2 — Never invent test data.**
Email addresses, file contents, record IDs, duplicate rows — every piece of test data used
in a `Given` step must come from the user or be confirmed in a live snapshot.
Do not hardcode emails or file names you made up.

**HARD STOP 3 — Never proceed past the Gap Check (Step 2) with open gaps.**
If even one gap is found, output the questions and stop. Do not write Gherkin, do not
navigate, do not infer. Wait for the user's answers.

**HARD STOP 4 — Never read only the target work item.**
Always fetch the parent Feature hierarchy and all sibling PBIs/Bugs first. A single PBI or
Bug is one slice of a flow defined across multiple work items. Writing Gherkin from one item
alone produces orphaned scenarios with invented preconditions.

---

## Tool Routing — Read This First

The correct tool sequence depends on what the user gives you. **Never substitute one path
for the other — they produce different scopes, different file names, and attach to different
work items in ADO.**

| ID type given by user | Goal | Fetch tool | Attach tool | Scope |
|---|---|---|---|---|
| **Epic ID** | ⛔ Not supported — warn user | — | — | — |
| **Feature ID** | Full regression suite across all child PBIs | `fetch_feature_hierarchy` | `attach_gherkin_to_feature` | 5–10 scenarios |
| **PBI or Bug ID** | Scoped file for that single story in the current sprint | `fetch_work_item_for_gherkin` | `attach_gherkin_to_work_item` | 3–9 scenarios |

**Decision rule (apply exactly):**

```
if user_input contains an Epic ID:
    → DO NOT call any fetch tool.
    → Respond immediately with:
      "Epic-scoped Gherkin generation is not supported. An Epic spans multiple Features
       and would produce files that are too large and unfocused to be useful as a
       regression suite.

       Please provide one of the following instead:
         • A Feature ID — I will generate 5–10 scenarios covering all child PBIs
         • A PBI or Bug ID — I will generate 3–9 scenarios scoped to that work item

       To find the child Features under this Epic, look up the work item in Azure DevOps
       and note the Feature IDs, then share them with me."
    → Wait for the user to provide a Feature or PBI/Bug ID. Do not proceed.

if user_input contains a Feature ID:
    → use fetch_feature_hierarchy  +  attach_gherkin_to_feature
    → before calling create_and_link_test_cases, ALWAYS ask the user to confirm:
      "I'm about to create {N} manual test cases linked to Feature #{id} — {title}.
       Please confirm (yes/no) before I proceed."
    → do not upload until the user replies affirmatively

if user_input contains a PBI ID or Bug ID:
    → use fetch_work_item_for_gherkin  +  attach_gherkin_to_work_item

if ambiguous (no ID, just a title or description):
    → ask the user: "Is this an Epic, Feature, PBI, or Bug? Please share the work item ID."
    → do not guess or default to either path
```

When using the **PBI/Bug path**, `fetch_work_item_for_gherkin` returns `parent_feature`
metadata. Use it for context when writing scenarios — but the generated file covers **only
the PBI/Bug's own acceptance criteria**, not the full Feature. The file is attached to the
PBI/Bug, not the Feature.

---

## Core Rule: Navigation Steps in Every Scenario

Every scenario MUST include an explicit navigation step — in `Background` (when all scenarios
share the same starting screen) or as a `Given` step in each individual scenario.

```gherkin
Background:
  Given I am logged in to Amplify as "<email>"
  And I navigate to the "Users > Add Multiple" screen
```

```gherkin
Scenario: Export failed users after partial mass add
  Given I am logged in to Amplify as "<email>"
  And I navigate to the "Users > Add Multiple" screen
  ...
```

Navigation path derivation priority:
1. Figma link in work item → use the frame/page name from the URL node-id
2. Screen name in acceptance criteria → use verbatim
3. Work item title → infer path
4. Playwright MCP live inspection → read real URL and breadcrumb text
5. Unknown → placeholder: `And I navigate to the "<!-- TODO: confirm screen name -->" page`

---

## ⛔ 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 — Build the full picture (always, no exceptions)

A single work item never tells the whole story.

**1A — Route to the correct fetch tool (see Tool Routing above):**

*Feature path:*
```
qa-gherkin-generator:fetch_feature_hierarchy(
  feature_id       : <Feature ID>
  organization_url : ...
  project_name     : ...
)
```
Extract: feature title/description, **all child PBIs and Bugs** with their ACs, existing test
cases, existing `.feature` attachments.

*PBI/Bug path:*
```
qa-gherkin-generator:fetch_work_item_for_gherkin(
  work_item_id     : <PBI or Bug ID>
  organization_url : ...
  project_name     : ...
)
```
Extract: work item title, acceptance_criteria, repro_steps (for Bugs), linked test cases
with full steps, parent_feature metadata, suggested_file_name.

**1B — get_linked_test_cases on the target work item (both paths):**
```
qa-test-case-manager:get_linked_test_cases(organization_url, project_name, work_item_id)
```

**1C — Build the full flow map:**

After fetching, assemble a flow map before writing anything:

```
FEATURE: <feature title>
  PBI/Bug A: <title> — <AC summary>  ← prerequisite step?
  PBI/Bug B: <title> — <AC summary>  ← the work item you were given (PBI/Bug path)
  PBI/Bug C: <title> — <AC summary>  ← downstream step?

FLOW (inferred from ACs + titles + states):
  Step 1: <what happens — which PBI owns it>
  Step 2: <what happens — which PBI owns it>
  Step 3: <target work item's step>
  Step 4: <downstream step>

STATE-DEPENDENT SCREENS (screens only reachable after a prior action):
  - <screen name> → requires: <what action / data to reach it>
```

Scenarios for the target work item must reflect the **real prerequisites** shown in the flow
map, not invented ones. Note: only include **active** siblings (state ≠ Removed) when building
the flow; Removed PBIs are superseded and should not be relied on.

---

### Step 2 — GAP CHECK: identify unknowns and STOP to ask (mandatory, no exceptions)

After building the flow map, scan every step in the user journey for the following gap types.
**If even one gap is found, output the questions below and STOP. Do not write a single line of
Gherkin or locator code until all gaps are resolved. This is a hard stop — not a suggestion.**

#### Gap types that always trigger a user question

| # | Gap type | Example |
|---|---|---|
| G1 | **State-dependent screen** — only appears after a prior action | Failure summary only exists after a CSV upload with bad rows |
| G2 | **Required test data** — agent needs a real file, email, or record ID | "What CSV should I upload to trigger failures?" |
| G3 | **Ambiguous flow step** — AC says something happens but not what screen follows | "After clicking Next, does a loading screen appear?" |
| G4 | **Unverified screen name** — referenced in AC but not yet snapshotted | "What is the exact URL/route for the failure summary?" |
| G5 | **Unseen element** — AC references a button only visible after an action | "Export List only appears on the failure summary — I need to reach it first" |
| G6 | **Figma link present** — work item has a Figma URL not yet inspected | Fetch the Figma frame name; verify it matches a real screen |
| G7 | **Sibling PBI defines the prerequisite** — the agent must replay a step from another PBI to set up state | "Should I replay the upload step, or is there a shortcut?" |

#### Question format — use this exactly

```
Before I generate Gherkin scenarios and locators for "<work item title>", I need answers
to the following — I cannot invent these without producing inaccurate, unrunnable tests:

**G1 / G2 — [gap type]: [screen or element name]**
[One sentence describing what I observed from the flow map]
→ [Specific question asking for what I need]

**G3 — [gap type]: [ambiguous step]**
[One sentence describing the ambiguity]
→ [Specific yes/no or multiple-choice question]

Please answer these and I will then navigate the live app through the full flow,
capture real locators from every screen, and generate accurate Gherkin + code.
I will not proceed until these are answered.
```

#### Hard rules

- **NEVER invent test data.** A `buildCsv()` helper with a hardcoded email constant is
  invented test data — it will fail unless the agent confirmed that email exists in the target org.
- **NEVER write a `Given` step that sets up state the agent has not actually observed.**
- **NEVER assign `stability: 0` silently.** Every `stability: 0` locator is a screen the agent
  invented without seeing. Flag each one explicitly and get sign-off before attaching.
- **Do not proceed to Step 3 until every G1–G7 gap is answered OR the user explicitly
  accepts the gaps and grants sign-off to proceed with known limitations.**

#### Pre-navigation checklist (run before Step 3)

```
□ Parent Feature hierarchy fetched — all active sibling PBIs/Bugs read?
□ Full flow map built — which work item owns each step?
□ Every state-dependent screen identified?
□ For each state-dependent screen: real test data available to reach it?
□ If a file upload is required: has the user provided or described the file?
□ Every screen sequence after major actions (upload, submit, click) known?
□ Every email / record ID / test value confirmed from live snapshot or user input?
```

If any box is unchecked: output gap questions and stop.

---

> **Steps 3–7** (live navigation, scenario writing, validation, delivery gate), the quality
> gates checklist, and the navigation step wording catalogue are in
> [references/step-by-step.md](references/step-by-step.md).
