evizi-kit 1.0.0

package/kits/shared/skills/web-auto-generate-project-blueprint/templates/web-auto-project-blueprint.template.md

@@ -0,0 +1,161 @@
+# Web Automation Project Blueprint
+
+> **Purpose**: Describes what this automation project is — its tech stack, directory structure, naming conventions, selector strategy, configuration, global setup, integrations, and CI/CD pipeline. This is the foundational reference for understanding the project before writing any tests.
+>
+> **Related documents**:
+> - `.documents-design/web-auto-best-practices.md` — coding standards, rules, and anti-patterns
+> - `.documents-design/web-auto-instructions.md` — copy-paste code templates from the actual codebase
+
+## 1. Tech Stack
+
+| Aspect | Value |
+|--------|-------|
+| Framework | [framework name and version] |
+| Language | [language and version] |
+| Test runner | [test runner name] |
+| Assertion library | [assertion library name] |
+| Reporter | [reporter name, e.g., Allure, HTML, JUnit XML] |
+| Package manager | [e.g., npm, yarn, pip, Maven] |
+
+### Multiple Frameworks
+
+[If the project uses more than one test framework (e.g., Cypress for component tests + Playwright for E2E), document each one here with its scope. Remove this subsection if only one framework is used.]
+
+| Framework | Scope | Config File |
+|-----------|-------|-------------|
+| [framework 1] | [e.g., E2E tests] | [config path] |
+| [framework 2] | [e.g., component tests] | [config path] |
+
+## 2. Key Configuration
+
+Source: `[config file path]`
+
+| Setting | Value |
+|---------|-------|
+| Base URL | [value] |
+| Test directory | [path] |
+| Global timeout | [value] |
+| Retries | [value] |
+| Workers / parallelism | [value] |
+| Browsers / devices | [list] |
+| Headless | [yes / no / env-controlled] |
+| Screenshots | [when captured] |
+| Video / trace | [when captured] |
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| [variable name] | [what it controls] |
+
+## 3. Global Setup, Fixtures, and Auth
+
+### Global Setup / Teardown
+
+| Mechanism | File | Purpose |
+|-----------|------|---------|
+| [e.g., globalSetup] | [file path] | [what it does] |
+
+### Authentication Strategy
+
+[Describe how the project handles login for tests — e.g., stored `storageState` from a setup project, API-based auth in `beforeAll`, environment-based credentials, etc.]
+
+### Shared Fixtures / Test Data
+
+| Fixture Type | Location | Description |
+|--------------|----------|-------------|
+| [e.g., auth state] | [path] | [what it provides] |
+| [e.g., test data factory] | [path] | [what it provides] |
+
+### Custom Test Abstractions
+
+| Abstraction | File | Purpose |
+|-------------|------|---------|
+| [e.g., BasePage class] | [path] | [what it provides to subclasses] |
+| [e.g., custom test wrapper] | [path] | [what it adds to the base test runner] |
+
+## 4. Directory Structure
+
+```
+[Full test-related directory tree from the project root]
+```
+
+## 5. File & Naming Conventions
+
+| File Type | Location | Naming Pattern | Example |
+|-----------|----------|----------------|---------|
+| Test spec | [path] | [pattern] | [real example] |
+| Page Object | [path] | [pattern] | [real example] |
+| Test data / fixture | [path] | [pattern] | [real example] |
+| API / backend helper | [path] | [pattern] | [real example] |
+| Type definition / model | [path] | [pattern] | [real example] |
+| Utility / helper | [path] | [pattern] | [real example] |
+
+### Class & Module Naming
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Page Object class | [pattern] | [real example] |
+| Helper module | [pattern] | [real example] |
+| Test data constant | [pattern] | [real example] |
+
+### Test ID Scheme
+
+[Describe the test ID convention used, e.g., `[ABBR]-[NUM]: Description` where ABBR is a 2-4 letter feature abbreviation. Omit this subsection if no test ID scheme exists.]
+
+## 6. Selector Strategy
+
+> This defines the priority order for locating elements. Follow this order when writing new selectors.
+
+| Priority | Strategy | Real Example from This Project |
+|----------|----------|-------------------------------|
+| 1 | [highest priority — e.g., `data-testid`] | [real selector] |
+| 2 | [second priority — e.g., ARIA role] | [real selector] |
+| 3 | [third priority — e.g., semantic CSS] | [real selector] |
+| 4 | [last resort — e.g., XPath] | [real selector] |
+
+### Framework-Specific Selector Constraints
+
+[Document any constraints imposed by the framework on how selectors must be declared — e.g., sync vs async rules, locator API usage. Omit if none.]
+
+## 7. Third-Party Integrations
+
+| Category | Library | Purpose |
+|----------|---------|---------|
+| [e.g., API mocking] | [library name] | [what it's used for in this project] |
+| [e.g., Visual testing] | [library name] | [what it's used for] |
+| [e.g., Accessibility] | [library name] | [what it's used for] |
+| [e.g., BDD] | [library name] | [what it's used for] |
+
+## 8. CI/CD Pipeline
+
+| Aspect | Value |
+|--------|-------|
+| Platform | [e.g., GitHub Actions, GitLab CI, Jenkins] |
+| Config file | [path to CI config] |
+| Trigger events | [e.g., push to main, PR, nightly schedule] |
+
+### Pipeline Steps (test-related)
+
+| Step | Description |
+|------|-------------|
+| [step name] | [what it does] |
+
+### CI Environment
+
+| Variable / Secret | Purpose |
+|-------------------|---------|
+| [variable name] | [what it controls] |
+
+## 9. Test Execution Commands
+
+| Action | Command |
+|--------|---------|
+| Run all tests | [command] |
+| Run a specific file | [command] |
+| Run by tag / suite | [command] |
+| Run in headed mode | [command, if applicable] |
+| Debug a test | [command, if applicable] |
+| View report | [command, if applicable] |
+| Lint / format | [command] |
+| Type / static check | [command, if applicable] |

package/kits/shared/skills/web-auto-playwright-mcp-extract-selectors/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: web-auto-playwright-mcp-extract-selectors
+description: Update placeholder selectors in a ticket-design.md file by using a Playwright MCP server to navigate the running application and extract actual selectors from the live DOM. Reads ticket-design.md, finds all steps with "Update selector for this element" placeholders, operates the test case steps via the Playwright MCP browser, takes accessibility-tree snapshots to identify elements, and replaces each placeholder with the real selector. Use this skill whenever someone asks to update selectors using Playwright MCP, fill in missing selectors via Playwright, resolve placeholder selectors by browsing the app, extract real selectors from a running app via Playwright, or navigate the live page to find element locators — even if phrased casually like "open the app and grab the selectors", "use Playwright to find the test IDs", or "browse and fill in selectors". Triggers on requests like "update selectors via MCP for TKT-001", "fill in selectors using Playwright for ABC-123", "resolve missing selectors by browsing for ticket fe-2026", "use playwright to extract selectors", "browse the app and find selectors for ticket X".
+---
+
+# Web Automation Update Selectors (Playwright MCP)
+
+Read a `ticket-design.md` file for a given ticket ID, find all steps that contain the `<-- Update selector for this element -->` placeholder, use a Playwright MCP server to navigate through the application following the test case steps, extract actual selectors from the live DOM, and update the ticket design in place.
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `TICKET_ID` | string | Yes | The ticket identifier (e.g., TKT-001, ABC-123) |
+
+**If `TICKET_ID` is not provided:** Ask the user for the ticket ID before proceeding.
+
+## Prerequisites
+
+- A Playwright MCP server must be available and configured in the agent profile
+- The application under test must be running and accessible in a browser
+
+## Playwright MCP Tool Reference
+
+This skill uses the Playwright MCP server. The key tools and their signatures are:
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `browser_navigate` | Navigate to a URL | `url` (required) |
+| `browser_snapshot` | Capture the page's accessibility tree with element references | — |
+| `browser_click` | Click on an element identified by its `ref` from snapshot | `element` (human-readable description), `ref` (element reference from snapshot) |
+| `browser_type` | Type text into an input element | `element` (description), `ref` (element reference), `text` (value to type), `submit` (optional, press Enter after) |
+| `browser_select_option` | Select an option from a `<select>` element | `element` (description), `ref` (element reference), `values` (array of option values) |
+| `browser_hover` | Hover over an element | `element` (description), `ref` (element reference) |
+| `browser_drag` | Drag an element to a target location | `startElement` (description), `startRef`, `endElement`, `endRef` |
+| `browser_press_key` | Press a key or key combination | `key` (e.g., `"Enter"`, `"Control+A"`) |
+| `browser_run_javascript` | Execute JavaScript in the browser context | `code` (JavaScript code string) |
+| `browser_tab_list` | List all open browser tabs | — |
+| `browser_tab_new` | Open a new tab | `url` (optional) |
+| `browser_tab_select` | Select a tab by index | `index` (required) |
+| `browser_tab_close` | Close a tab | `index` (optional, defaults to current) |
+| `browser_file_upload` | Upload files to a file input | `paths` (array of file paths) |
+| `browser_pdf_save` | Save the current page as PDF | — |
+| `browser_wait` | Wait for a specified duration | `time` (seconds, max 10) |
+| `browser_close` | Close the browser | — |
+| `browser_resize` | Resize the browser window | `width`, `height` |
+
+**Critical concept:** Playwright MCP operates through an **accessibility-tree snapshot** model. Every `browser_snapshot` call returns a tree of elements, each with a unique `ref`. All interaction tools (`browser_click`, `browser_type`, `browser_hover`, etc.) require both a human-readable `element` description and the `ref` from the **most recent snapshot**. Always take a fresh snapshot before interacting with elements.
+
+## Workflow
+
+### Step 1: Locate and Read Ticket Design
+
+Search for the ticket design file using this glob pattern:
+
+```
+.tickets/{TICKET_ID}/ticket-design.md
+```
+
+**If not found:** Inform the user and stop:
+
+```
+Error: ticket-design.md not found for ticket {TICKET_ID}.
+Run the web-auto-ticket-design skill first to create it.
+```
+
+**If found:** Read the full file. For each test case, collect:
+- **All steps in order** — to replay them in the browser
+- **Steps with placeholders** — steps containing `- Selector: <-- Update selector for this element -->` and their element names, descriptions, and action context
+
+If no placeholder selectors are found, inform the user and stop:
+
+```
+No placeholder selectors found in ticket-design.md for ticket {TICKET_ID}.
+All selectors are already populated.
+```
+
+### Step 2: Read Project Locator Strategy
+
+Before extracting selectors, read the project's selector strategy from the source instructions.
+
+**Locate the instructions file:**
+
+`.documents-design/web-auto-project-blueprint.md`
+
+**If found:** Read the **Selector Strategy** section. Extract:
+- The priority order of locator types (e.g., `data-testid` first, then ARIA roles, etc.)
+- The locator format examples from the codebase
+- Any project-specific conventions or exceptions
+
+Use this strategy for all selector extraction in subsequent steps.
+
+**If not found:** Fall back to this default priority: `data-testid` > `role` + name > `aria-label` > CSS selectors.
+
+### Step 3: Verify Playwright MCP Connection
+
+Before starting the test run, verify the Playwright MCP server is available:
+
+1. Call `browser_navigate` with `url: "about:blank"` to check that the browser is connected
+2. If the call fails → report error and **stop**:
+   ```
+   Error: Playwright MCP server is not available.
+   Ensure the Playwright MCP server is running and the browser is connected.
+   ```
+3. If successful, the browser is ready for use
+
+### Step 4: Navigate and Extract Selectors
+
+Process **one test case at a time** — complete all steps of one test case before moving to the next. Browser state is cumulative (logged-in sessions, navigation history, form data), so jumping between test cases would corrupt the application state.
+
+**4.1 — Navigate to the starting point**
+
+Use `browser_navigate` with the application URL to navigate to the page where the test case begins (using the first step's action context — typically a navigation action).
+
+After navigation, call `browser_snapshot` to verify the page has loaded and capture the initial accessibility tree. If the snapshot doesn't show the expected content, use `browser_wait` briefly and re-snapshot. If the page still doesn't match expectations, use `browser_run_javascript` to check the current URL and document title for diagnosis before proceeding.
+
+**4.2 — Walk through each step**
+
+Process each step in the test case sequentially. Before interacting with any element, **always take a fresh snapshot** using `browser_snapshot` to get current element `ref`s.
+
+- **Steps with existing selectors or actions** — execute the action in the browser to advance the application state:
+  - **Click** → identify the element in the snapshot by matching its description, then call `browser_click` with the element's `ref` and a human-readable `element` description
+  - **Type/Fill** → identify the input element, then call `browser_type` with the element's `ref`, `element` description, and `text` value
+  - **Select option** → call `browser_select_option` with the element's `ref` and the option `values`
+  - **Navigate** → call `browser_navigate` with the target URL
+  - **Key press** → call `browser_press_key` with the key combination
+  - **Hover** → call `browser_hover` with the element's `ref` (useful for revealing tooltips, dropdowns)
+  - **Wait** → call `browser_wait` with a duration if explicit wait is needed
+
+  This ensures the page is in the correct state for subsequent steps.
+
+- **Steps with placeholder selectors** — before executing, pause and extract the selector:
+
+  1. **Take a snapshot** — call `browser_snapshot` to capture the current page accessibility tree
+  2. **Identify the target element** — match the element from the ticket design to a node in the accessibility tree using these heuristics (in order):
+     - **Role + name match** — the ticket says "Login button" → look for a node with `role: button` and name containing "Login"
+     - **Label match** — the ticket says "Email input" → look for a node with label/placeholder "Email"
+     - **Text match** — the ticket says "Submit link" → look for a link node with text "Submit"
+     - **Structural match** — the ticket says "First name in the form" → find the form section in the tree, then locate the input that corresponds structurally
+     - When multiple nodes match, use the page context from the test case (which section, which modal, which form) to disambiguate
+  3. **Extract selector attributes** — once the element is identified from the snapshot, use `browser_run_javascript` to extract all attributes that could be used to build a selector. Use the element's accessible name, role, or a known stable attribute from the snapshot to locate it in the DOM:
+     ```javascript
+     const el = document.querySelector('[data-testid="..."]')
+       || document.querySelector('[name="..."]')
+       || document.querySelector('[role="..."][aria-label="..."]');
+     if (el) {
+       JSON.stringify({
+         tag: el.tagName.toLowerCase(),
+         id: el.id,
+         testId: el.getAttribute('data-testid'),
+         dataCy: el.getAttribute('data-cy'),
+         dataTest: el.getAttribute('data-test'),
+         role: el.getAttribute('role'),
+         name: el.getAttribute('name'),
+         type: el.getAttribute('type'),
+         ariaLabel: el.getAttribute('aria-label'),
+         ariaLabelledBy: el.getAttribute('aria-labelledby'),
+         placeholder: el.getAttribute('placeholder'),
+         href: el.getAttribute('href'),
+         classes: el.className,
+         text: el.textContent?.trim().substring(0, 100)
+       });
+     }
+     ```
+  4. **Choose the best selector** — select the highest-priority attribute per the project's locator strategy from Step 2
+  5. **Record the resolved selector** — store it for updating the ticket design later
+  6. **Execute the step** — after extracting the selector, execute the action (click, type, etc.) to advance the app state for subsequent steps
+
+**4.3 — Handle multi-state elements**
+
+Some elements only appear after certain interactions (dropdowns, modals, tooltips). When a placeholder element is not visible in the current snapshot:
+
+1. Check if a preceding action would reveal it (e.g., clicking a dropdown trigger)
+2. Execute that action (e.g., `browser_click` on the trigger, or `browser_hover` over a menu item), then call `browser_snapshot` again to get updated `ref`s
+3. Use `browser_wait` if dynamic content needs time to appear, then re-snapshot
+4. If the element still cannot be found after revealing interactions, use `browser_run_javascript` to inspect the DOM and confirm the element truly isn't present (e.g., check if the expected container exists but the child element is missing)
+5. If still not found, mark it as unresolved with a reason
+
+**4.4 — Handle page transitions and loading**
+
+After actions that cause page navigation or significant DOM changes:
+
+1. Call `browser_snapshot` to verify the new page has loaded — check for expected content in the accessibility tree
+2. If the page shows a loading spinner or skeleton, use `browser_wait` then re-snapshot
+3. Always take a **new snapshot** after any navigation — previous `ref`s become stale
+
+**4.5 — Retry on interaction failures**
+
+Browser interactions can fail due to loading delays, animations, or elements not yet interactive. When a `browser_click`, `browser_type`, or other interaction fails:
+
+1. Wait briefly (use `browser_wait` for the element to settle)
+2. Take a fresh snapshot — the element's `ref` may have changed due to DOM re-render
+3. Re-identify the element and retry the interaction once
+4. If it fails again, use `browser_run_javascript` to inspect the element's state (visibility, disabled attribute, z-index overlap) and mark the step as problematic in the summary
+
+**4.6 — Detect design gaps**
+
+While walking through steps, watch for situations where the ticket design doesn't match reality:
+- A navigation step is missing (the app shows a different page than expected)
+- A prerequisite action isn't described (e.g., need to dismiss a cookie banner or accept terms first)
+- An element described in the design doesn't exist on the actual page
+- The step order doesn't match the actual user flow
+
+Record these gaps — they'll be reported in Step 7 so the ticket designer can fix them. Do not modify `ticket-design.md` to fix gaps; only replace placeholder selectors.
+
+### Step 5: Build Selector Values
+
+For each placeholder, apply the project's locator priority in strict order — use the first attribute that is present and stable:
+
+| Priority | Condition | Selector format |
+|----------|-----------|-----------------|
+| 1 | `testId` is present | `[data-testid="<value>"]` |
+| 2 | `name` is present on an input/select/textarea | `<tag>[name="<value>"]` (e.g. `input[name="email"]`) |
+| 3 | `role` + `ariaLabel` are both present | `[role="<value>"][aria-label="<value>"]` |
+| 4 | None of the above — use relative XPath | `//tag[contains(@class,"...") and text()="..."]` |
+| — | Element not found | Keep `<-- Update selector for this element -->` unchanged |
+
+**Avoid these anti-patterns** because they produce brittle, flaky selectors that break on routine code changes:
+- **`id`** — often auto-generated by frameworks (e.g., `#radix-12`, `#mui-input-3`) and changes across renders
+- **CSS class names** — typically generated by CSS-in-JS or build tools (e.g., `.styles_button__a1b2c`) and change on every build
+- **Absolute XPath** — encodes the full DOM path (e.g., `/html/body/div[2]/main/form/button`), breaks when any ancestor element changes
+- **Index-based selectors** — depend on element ordering (e.g., `button:nth-child(3)`) which changes when elements are added or reordered
+- **Text-only selectors** — break when copy is updated, translated, or A/B tested
+
+### Step 6: Update Ticket Design
+
+For each placeholder that has a resolved selector, update the `ticket-design.md` file in place:
+
+**Replace:**
+```
+  - Selector: <-- Update selector for this element -->
+```
+
+**With:**
+```
+  - Selector: [resolved-selector]
+```
+
+Do not modify any other lines in the step (`- Element:`, `- Action:`, `- Expected Result:`, `- Note:`). The `- Note: New element/action - needs to be implemented` line must remain — this skill only resolves selectors, not implement the automation code.
+
+Save the updated file at its original location.
+
+### Step 7: Summary
+
+Display the result to the user:
+
+```
+Selectors updated for ticket {TICKET_ID}.
+
+Updated:
+- .tickets/{TICKET_ID}/ticket-design.md
+
+Summary:
+- Selectors resolved: {resolved_count}
+- Selectors still pending: {pending_count}
+```
+
+If any selectors remain unresolved, add:
+
+```
+Unresolved elements:
+- [Test Case ID] Step [N]: [Element name] — [reason: not found in snapshot / element not visible / page state unclear]
+
+Note: These elements could not be identified in the live application.
+You can update them manually or try the FE source code approach.
+```
+
+If any design gaps were detected during navigation (Step 4.6), add:
+
+```
+⚠️ Design gaps detected — ticket-design.md was NOT modified for these:
+- [Test Case ID] Step [N]: [description of the gap]
+  Suggested fix: [what step or action is missing]
+
+Re-run the web-auto-ticket-designer agent to address these gaps before proceeding.
+```
+
+## Important Rules
+
+- **Follow project locator strategy** — always read and follow the Selector Strategy from the project blueprint; only use the default fallback when no blueprint is found
+- **Execute steps in order** — follow the test case step sequence to ensure the application is in the correct state before extracting each selector; skipping or reordering steps corrupts browser state
+- **One test case at a time** — complete all steps of one test case before moving to the next to maintain correct application state
+- **Extract from live DOM only** — selectors must come from actual page snapshots and `browser_run_javascript` calls; never fabricate or guess selector values
+- **Always use fresh snapshots** — before interacting with any element, take a new `browser_snapshot`; previous `ref`s become invalid after DOM changes or navigation
+- **Use `ref` + `element` for all interactions** — Playwright MCP requires the `ref` from the latest snapshot for `browser_click`, `browser_type`, `browser_hover`, and other interaction tools; always include a human-readable `element` description alongside the `ref`
+- **Use `browser_run_javascript` for attribute extraction** — execute JavaScript in the browser context to extract DOM attributes from identified elements; use known stable attributes from the snapshot to locate the element in the DOM
+- **Use JS inspection for debugging** — when an element can't be found or page state is unexpected, use `browser_run_javascript` to check the current URL, document title, or DOM structure before marking as unresolved
+- **Preserve file structure** — only modify `- Selector:` lines; do not alter step numbers, descriptions, actions, expected results, or notes
+- **Report design gaps, never fix them** — if a missing navigation step, prerequisite action, or undescribed interaction is detected, report it in the summary under "Design gaps detected"; do not add, remove, or reorder steps in `ticket-design.md`
+- **Keep analysis internal** — do not output snapshot data or candidate lists to the user
+- **Handle failures gracefully** — if the MCP server is unavailable or the app is not running, inform the user and stop before making any changes
+- **Wait for page stability** — use `browser_wait` and re-snapshot after navigations and actions that trigger loading states
+- **File update failure** — report the error and ask how to proceed

package/kits/shared/skills/web-auto-test-cases/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: web-auto-test-cases
+description: Generate BDD Gherkin test cases from raw ticket content. Receives the ticket ID and raw ticket content, extracts the feature path, creates the ticket directory, generates comprehensive Gherkin scenarios, and saves them as test-cases.md. Always use this skill when asked to generate test cases, create BDD scenarios, or write Gherkin for a ticket — even if the request seems simple or comes from an orchestrator. Triggers on requests like "create test cases for ticket TKT-001", "generate BDD scenarios for ABC-123", "write Gherkin test cases for ticket fe-2026", "generate test cases for this ticket", or "create scenarios from these instructions".
+---
+
+# Web Automation Test Cases
+
+Given a ticket ID and its raw content, extract the feature path, create the ticket directory, systematically analyze every test case, and generate comprehensive BDD Gherkin scenarios saved to `test-cases.md`.
+
+The goal is completeness and accuracy: every test case in the ticket becomes exactly one Gherkin scenario — no more, no less — with its original test case ID preserved as a tag, so the test suite stays fully traceable to the source ticket.
+
+## Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `TICKET_ID` | string | Yes | The ticket identifier (e.g., TKT-001, ABC-123) |
+| `TICKET_CONTENT` | string | Yes | Raw ticket content (instructions, test cases, acceptance criteria) |
+
+If either parameter is missing, ask the user before proceeding.
+
+## Workflow
+
+### Step 1: Extract Feature Path
+
+Parse `TICKET_CONTENT` to find the **Feature** field and extract `PARENT_FEATURE` and `CHILD_FEATURE`.
+
+**Expected format in the ticket content:**
+```
+- Feature: {PARENT_FEATURE} - {CHILD_FEATURE}
+```
+
+**Extraction rules:**
+- Split the Feature value on ` - ` (space-dash-space)
+- First part → `PARENT_FEATURE`, second part → `CHILD_FEATURE`
+- Convert both to lowercase kebab-case (e.g., `Administration` → `administration`, `Users Monitors` → `users-monitors`)
+
+**Examples:**
+
+| Feature field value | PARENT_FEATURE | CHILD_FEATURE |
+|---------------------|----------------|---------------|
+| `administration - users-monitors` | `administration` | `users-monitors` |
+| `Reports - Monthly Sales` | `reports` | `monthly-sales` |
+| `User Management - Role Permissions` | `user-management` | `role-permissions` |
+
+**If the Feature field is missing or cannot be parsed:** Ask the user to provide the parent and child feature names.
+
+### Step 2: Create Directory
+
+Build the output path:
+```
+.tickets/{TICKET_ID}/
+```
+
+Create the directory if it does not exist.
+
+### Step 3: Analyze Ticket Content (internal)
+
+Before generating any Gherkin, do a full analysis of the ticket. This step is entirely internal — don't output the analysis to the user. Its purpose is to ensure every test case is captured and nothing is missed.
+
+**3.1 — Inventory test case IDs**
+
+Find and list every Test Case ID in the ticket exactly as written. The count matters — you'll use this to verify at the end that every ID has a matching scenario.
+
+**3.2 — Parse each test case**
+
+For each test case, extract:
+- Summary
+- Preconditions
+- Test Data
+- Steps
+- Expected Results
+- Post-conditions (Cleanup)
+
+**3.3 — Plan the scenario structure**
+
+Decide:
+- Which preconditions are shared across all scenarios → these go in `Background`
+- Which preconditions are specific to one scenario → these go as `Given` steps in that scenario
+- Which scenarios need `@cleanup` → based on their Post-conditions section
+
+Create a 1:1 mapping: every test case ID → one Gherkin scenario. This is the core of the skill — a missed test case ID means a gap in test coverage that can't be easily detected later.
+
+### Step 4: Generate Gherkin
+
+Produce the complete Gherkin content following the template at [templates/test-cases.template.md](templates/test-cases.template.md).
+
+**Tags and feature structure:**
+
+| Element | Rule | Why |
+|---------|------|-----|
+| Feature tag | `@{TICKET_ID}` | Groups all scenarios for this ticket, making them runnable together |
+| Related Feature tag | Include only if present and not "None" | Avoids polluting the tag namespace with empty values |
+| Feature line | `Feature: {Parent} - {Child Feature}` | Mirrors the ticket's hierarchy |
+| Background | Preconditions shared by all scenarios | Reduces repetition without hiding setup |
+
+**Scenario structure:**
+
+| Element | Rule | Why |
+|---------|------|-----|
+| Scenario tag | Exact Test Case ID (e.g., `@TC057`) | Keeps the suite traceable to ticket IDs |
+| `@cleanup` tag | Only when Post-conditions require it | Makes test teardown explicit and opt-in |
+| Scenario name | Derived from the test case Summary | Should read like a plain-English description of what's being verified |
+
+**Step translation:**
+
+| Source field | Gherkin keyword |
+|--------------|----------------|
+| Steps | `When` / `And` |
+| Expected Results | `Then` / `And` |
+| Unique preconditions | `Given` (within the scenario) |
+
+**Data handling:** Enclose all variable data in double quotes — emails, usernames, messages, URLs, test data values. This keeps steps readable and makes data easy to spot for future parameterization.
+
+**Edge cases:**
+- If a test case has no preconditions of its own, skip `Given` and start with `When`
+- If no preconditions are shared across scenarios, omit `Background` entirely
+- If a scenario name from the Summary is ambiguous, expand it slightly for clarity
+
+### Step 5: Save
+
+Save the generated Gherkin content to:
+
+```
+.tickets/{TICKET_ID}/test-cases.md
+```
+
+If the file cannot be created, report the error and ask how to proceed.
+
+### Step 6: Summary
+
+```
+Test cases created for ticket {TICKET_ID}.
+
+Created:
+- .tickets/{TICKET_ID}/test-cases.md
+
+Scenarios: {count} ({list of test case IDs})
+```