@qa-gentic/agents 1.1.2

package/skills/qa-stlc/generate-gherkin.md

@@ -0,0 +1,550 @@
+---
+name: generate-gherkin
+description: >
+  Use this skill whenever the user asks to generate, write, or create Gherkin feature files,
+  BDD scenarios, or test cases from Azure DevOps work items. Also triggers when the user wants
+  to automate acceptance criteria into Playwright tests, create regression suites from PBIs,
+  Bugs, or Features, or produce .feature files for any web application. This skill enforces
+  navigation steps in every Gherkin scenario and links generated artefacts back to ADO work items.
+  Always use this skill when the user mentions "feature file", "Gherkin", "BDD", "scenarios",
+  "acceptance criteria automation", or asks to test a specific page/feature of a web app.
+  Works with any ADO work item type: PBI, Bug, or Feature ID.
+compatibility:
+  tools:
+    - qa-gherkin-generator:fetch_feature_hierarchy
+    - qa-gherkin-generator:fetch_work_item_for_gherkin
+    - qa-gherkin-generator:attach_gherkin_to_feature
+    - qa-gherkin-generator:attach_gherkin_to_work_item
+    - qa-gherkin-generator:validate_gherkin_content
+    - qa-playwright-generator:validate_gherkin_steps
+    - qa-playwright-generator:generate_playwright_code
+    - qa-playwright-generator:attach_code_to_work_item
+    - qa-test-case-manager:fetch_work_item
+    - qa-test-case-manager:get_linked_test_cases
+---
+
+# 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.
+
+---
+
+## 🚨 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** | Full regression suite across ALL child Features and their PBIs/Bugs | `fetch_epic_hierarchy` | `attach_gherkin_to_feature` (once per child Feature) | 5–10 scenarios per Feature |
+| **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:
+    → ALWAYS use fetch_epic_hierarchy  (never fall through to fetch_feature_hierarchy)
+    → fetch_epic_hierarchy returns ALL child Features, their PBIs/Bugs, and all linked TCs
+    → analyse every Feature and every child PBI/Bug before generating any Gherkin
+    → generate one .feature file per child Feature (5–10 scenarios each)
+    → attach each via attach_gherkin_to_feature on the respective Feature ID
+    → DO NOT create manual test cases (create_and_link_test_cases) for the Epic itself
+      → inform the user: "Test cases cannot be created for an Epic. They can only be
+        created for PBIs, Bugs, or Features. Would you like me to create test cases for
+        the individual child Features or PBIs instead?"
+
+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 **Epic path**, `fetch_epic_hierarchy` returns a `features` list where each
+entry contains the Feature's metadata plus its `child_work_items` (PBIs/Bugs) and
+`existing_test_cases`. **Read every Feature and every child PBI/Bug in this list** before
+writing a single scenario — the full cross-Feature flow is the only correct input for an
+Epic-scope suite.
+
+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:
+`skills/deduplication-protocol.md`
+
+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):**
+
+*Epic path (ALWAYS use when an Epic ID is provided):*
+```
+qa-gherkin-generator:fetch_epic_hierarchy(
+  epic_id          : <Epic ID>
+  organization_url : ...
+  project_name     : ...
+)
+```
+Extract: epic title/description, **all child Features**, each Feature's child PBIs/Bugs
+with their ACs, and all existing test cases. Analyse the ENTIRE hierarchy — every Feature
+and every PBI/Bug — before writing a single scenario. Generate one .feature file per
+child Feature.
+
+*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.
+
+---
+
+### Step 3 — Live navigation through the FULL flow using real test data
+
+Once all gaps from Step 2 are resolved (or user has granted explicit sign-off), navigate
+the live app through **every screen in the flow map** using the real test data provided.
+Never skip a screen. Never snapshot only the landing page and infer the rest.
+
+```
+playwright:browser_navigate(APP_BASE_URL)
+playwright:browser_fill_form(...)       ← login
+playwright:browser_click(...)           ← Log In
+playwright:browser_snapshot()           ← verify dashboard
+
+← Navigate prerequisite steps with real test data
+playwright:browser_click(...)           ← each step in the flow map
+playwright:browser_snapshot()           ← capture locators at each screen
+
+← For file-upload-gated screens:
+playwright:browser_file_upload(
+  files: ["<real file path provided by user>"],
+  element: "file upload input",
+  ref: "<ref from snapshot>"
+)
+playwright:browser_snapshot()           ← verify file accepted
+playwright:browser_click(...)           ← Next / Submit
+playwright:browser_snapshot()           ← capture processing screen (if any)
+playwright:browser_snapshot()           ← capture result / state-dependent screen
+                                           ← capture ALL elements on this screen
+playwright:browser_click(...)           ← any further actions (Export, Close, etc.)
+playwright:browser_snapshot()           ← capture post-action state
+```
+
+**Every element captured in a live snapshot gets `stability ≥ 60`.**
+**Every element NOT reached gets `stability: 0` and a `⚠ NOT VERIFIED — screen not reached` comment.**
+A `stability: 0` locator for a reachable screen means you missed a step — go back to Step 2.
+
+---
+
+### Step 4 — Write net-new scenarios only
+
+Map each acceptance criterion to one or more net-new scenarios (post-deduplication diff).
+Scenarios must reflect the **real flow** from Step 1 — prerequisite steps come from the
+flow map, not invented placeholders.
+
+```gherkin
+@{feature_tag} @regression
+Feature: {feature.title}
+  As a {persona}
+  I want {goal}
+  So that {benefit}
+
+  Background:
+    Given I am logged in to Amplify as "<email>"
+    And I navigate to the "<ScreenName>" page
+
+  @smoke
+  Scenario: {primary happy path — real flow, real test data}
+    Given {initial state — from flow map, not invented}
+    When  {user action — verified in live snapshot}
+    Then  {observable outcome — verified in live snapshot}
+
+  @regression
+  Scenario: {error / boundary / negative case}
+    Given {precondition from flow map}
+    When  {action}
+    Then  {expected outcome}
+
+  @regression
+  Scenario Outline: {data-driven boundary test}
+    When  {action with "<param>"}
+    Then  {expected outcome}
+    Examples:
+      | param |
+      | value |
+```
+
+**Scenario count:**
+- Feature-scoped file: **5–10 scenarios**
+- Work-item-scoped file (single PBI or Bug): **3–9 scenarios**
+
+**Coverage checklist:**
+
+| Tag | When to include |
+|---|---|
+| `@smoke` | Always — exactly one primary happy path |
+| `@regression` | Additional journeys, error cases, boundary conditions |
+| `@regression` | Cancel/discard flows (when in ACs) |
+| `@regression` | Persistence after refresh/re-login (when in ACs) |
+| `@accessibility` | When ACs or coverage hints mention keyboard nav or ARIA |
+
+**Style rules:**
+- `Given` = state, `When` = user action, `Then` = observable outcome
+- One assertion per `Then` where possible
+- `Background` only when multiple scenarios share identical preconditions
+- `Scenario Outline` + `Examples` for data-driven boundary tests
+
+---
+
+### Step 5 — Validate (two checks — both required)
+
+**5A — Structural validation (tags, scenario count, When steps):**
+```
+qa-gherkin-generator:validate_gherkin_content(
+  gherkin_content : <your .feature file content>,
+  scope           : "feature"   ← Feature path
+                  | "work_item" ← PBI/Bug path
+)
+```
+
+If `valid` is `false`, **stop and fix all errors before proceeding**. Do not call the attach
+tool with a file that failed validation — the attach tool will also block it and return the
+same errors. Correct the content and re-validate until `valid` is `true`.
+
+Review `warnings` even when valid — they are non-blocking but indicate style issues worth
+addressing (e.g. multiple @smoke tags, missing Background block).
+
+**5B — Step uniqueness check:**
+```
+qa-playwright-generator:validate_gherkin_steps(gherkin_content)
+```
+
+Check: zero duplicate step strings, every scenario has at least one `When`, navigation step
+present in every scenario or Background.
+
+---
+
+### Step 6 — Delivery gate (mandatory before attaching to ADO)
+
+Before calling any attach tool, present the following to the user and wait:
+
+```
+I've generated a .feature file for {work_item_type} #{id} — "{title}".
+
+{N} scenarios | validation: ✅ passed | scope: {feature | work_item}
+
+**Do you want me to attach this file to ADO now? (yes / no)**
+
+Note:
+- Saying yes here only attaches the Gherkin file.
+- It does NOT generate Playwright code or create manual test cases.
+- If you want those as well, say so separately after this step.
+```
+
+**Do not call any attach tool until the user replies "yes".**
+
+**If user says "yes":**
+
+Only attach if the deduplication diff confirms net-new scenarios exist.
+
+*Feature path:*
+```
+qa-gherkin-generator:attach_gherkin_to_feature(
+  organization_url, project_name,
+  feature_id, feature_title, gherkin_content
+)
+```
+File name produced: `{feature_id}_{feature_title}_regression.feature`
+Attaches to: the Feature work item.
+
+*PBI/Bug path:*
+```
+qa-gherkin-generator:attach_gherkin_to_work_item(
+  organization_url, project_name,
+  work_item_id, work_item_title, gherkin_content
+)
+```
+File name produced: `{work_item_id}_{title_kebab}.feature`
+Attaches to: the PBI or Bug work item directly.
+
+Both attach tools run `validate_gherkin_content` internally. If the file still fails
+validation at this point, the upload is blocked and errors are returned. Fix and retry.
+
+**If user says "no":** Stop. Offer the content inline. Do not create a local file
+unless the user explicitly says "save" or "download".
+
+**After attach completes — STOP. Do not proceed to Playwright.**
+Playwright code generation is a separate decision. Wait for the user to ask.
+
+---
+
+### Step 7 — Generate Playwright automation (only if user explicitly asks)
+
+**Do not start this step unless the user has explicitly requested Playwright code.**
+A "yes" at Step 6 (attach Gherkin) does not request Playwright generation.
+
+If the user does ask for Playwright code, refer to `skills/generate-playwright-code.md`
+for the full workflow. That skill has its own independent delivery gate at Step 7 of
+that document — do not carry over the Gherkin attachment confirmation.
+
+---
+
+## Quality Gates — Do Not Attach Without These
+
+- [ ] Work item type identified — **correct tool-routing path selected** (Epic vs Feature vs PBI/Bug)
+- [ ] **Epic path**: `fetch_epic_hierarchy` called — NOT `fetch_feature_hierarchy` or `fetch_work_item_for_gherkin`
+- [ ] **Epic path**: ALL child Features and ALL child PBIs/Bugs read and analysed before any Gherkin written
+- [ ] **Epic path**: One .feature file generated per child Feature (not one file for the whole Epic)
+- [ ] **Epic path**: `create_and_link_test_cases` NOT called on the Epic ID — user informed that test cases are scoped to Features/PBIs/Bugs only
+- [ ] **Feature path**: `fetch_feature_hierarchy` called — all child PBIs/Bugs reviewed
+- [ ] **Feature path**: User confirmation received before calling `create_and_link_test_cases`
+- [ ] **PBI/Bug path**: `fetch_work_item_for_gherkin` called — parent Feature context reviewed
+- [ ] Correct fetch tool called: `fetch_epic_hierarchy` for Epic, `fetch_feature_hierarchy` for Feature, `fetch_work_item_for_gherkin` for PBI/Bug
+- [ ] Parent Feature hierarchy context reviewed — all active sibling PBIs/Bugs read and flow map built
+- [ ] Gap check (Step 2) completed — every G1–G7 gap type checked
+- [ ] **All gaps answered by user before any Gherkin was written** (or explicit sign-off obtained)
+- [ ] **Real test data used** — no invented CSV content, emails, or record IDs
+- [ ] Live Playwright MCP snapshots taken of **every screen in the full flow**
+- [ ] **Zero `stability: 0` locators** for screens reachable with provided test data
+- [ ] Every unverified locator has `⚠ NOT VERIFIED` comment with explicit user sign-off
+- [ ] Deduplication report shown to user
+- [ ] Every scenario has a navigation step (Background or inline `Given`)
+- [ ] **`validate_gherkin_content` returned `valid: true`** (Step 5A — required before attach)
+- [ ] `validate_gherkin_steps` returns zero duplicate steps (Step 5B)
+- [ ] At least one `@smoke` scenario
+- [ ] At least one `@regression` scenario
+- [ ] Scenario count within range: 5–10 for Feature scope, 3–9 for PBI/Bug scope
+- [ ] All `Then` assertions verified in a live snapshot
+- [ ] Credentials sourced from `process.env` in any generated code, not hardcoded
+- [ ] Correct attach tool called: `attach_gherkin_to_work_item` for PBI/Bug, `attach_gherkin_to_feature` for Feature (also used per Feature in Epic path)
+
+---
+
+## Navigation Step Wording Catalogue
+
+Reuse these exact phrasings so a single step definition covers all scenarios:
+
+```gherkin
+# Auth
+Given I am logged in to Amplify as "<email>"
+Given I am logged in as an admin user
+
+# Navigation
+And I navigate to the "Dashboard" page
+And I navigate to the "Users" page
+And I navigate to "Users > Add Multiple"
+And I navigate to "Users > Add Multiple > Failure Summary"
+
+# Direct route
+And I navigate to "/manage/people"
+And I navigate to "/manage/people/mass-add"
+
+# Post-action state
+And I am on the "Failure Summary" screen
+And I am redirected to the "Dashboard"
+```
+---
+
+## Explicit Delivery Rules — No Inference
+
+| Decision | Rule |
+|---|---|
+| Generate Gherkin | Always: show the file content first |
+| Attach to ADO | Requires explicit "yes" at Step 6 gate |
+| User says "no" at Step 6 | Present inline; offer local download only if user asks |
+| Local file creation | Only if user says "save" or "download" |
+| Playwright code generation | Must be a separate user request — not triggered by this skill completing |
+| Manual test case creation | Must be a separate user request — not triggered by this skill completing |
+| Next work item (Epic path) | Each child Feature's attachment requires its own separate "yes" |
+
+**Each artifact delivery is independent. A yes/no for one does not answer any other.**