# Generate Gherkin — Steps 3–7 Reference

> Companion to [SKILL.md](../SKILL.md). Covers live navigation, scenario writing,
> validation, delivery gate, quality gates, and the navigation step wording catalogue.

---

### 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, use the `generate-playwright-code` skill
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** (Feature vs PBI/Bug)
- [ ] **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_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.**
