generate-gherkin

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.

---

🚨 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.

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

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.