---
description: Convert a Word or Excel requirements document into Gherkin BDD feature files using the bdd-gherkin skill
argument-hint: "<requirements-file> [output-dir]"
---

Convert the requirements document at **$1** into Gherkin BDD feature files using the `bdd-gherkin` skill, and save them to `${2:-tests/features/}` — the same location and format used by "BDD From URL".

## Workflow

1. **Verify the document exists**.
   - Check that $1 exists and is readable. If not, stop and report the exact problem (missing file, unsupported extension, unreadable content).

2. **Load the BDD skill**.
   - Read `skills/bdd-gherkin/SKILL.md` first and follow its rules for the rest of this task.

3. **Extract the requirements text**.
   - $1 may be a Word document (.docx), an Excel workbook (.xlsx/.xlsm), or a plain-text file (.txt/.md/.csv). Extract its full content to work from:
     - **Plain text (.txt/.md/.csv)** — read the file directly.
     - **Word (.docx)** — a .docx is a ZIP archive. Try, in order:
       1. `pandoc "$1" -t gfm` (keeps tables as markdown) if pandoc is installed
       2. Python with `python-docx` if available
       3. Raw fallback: extract `word/document.xml` from the archive (`unzip -p "$1" word/document.xml`, or PowerShell's `System.IO.Compression.ZipFile` on Windows) and strip the XML tags. Convert `<w:p>` elements to line breaks and `<w:tbl>` table rows to pipe-delimited rows so tabular requirements survive.
     - **Excel (.xlsx/.xlsm)** — also a ZIP archive. Try, in order:
       1. Python with `openpyxl` or `pandas` if available
       2. Raw fallback: extract `xl/workbook.xml`, `xl/sharedStrings.xml`, and `xl/worksheets/sheet*.xml` from the archive and reconstruct the rows — shared strings give the text values, the sheet XML gives the cell positions. Emit each sheet as a separate section, headed by the sheet name.
   - If the extracted text is too long to keep in the conversation, write it to a temporary file **outside** the workspace (e.g. in the OS temp dir) and delete it when done. Never modify or move the original document.
   - If extraction yields garbled or clearly incomplete content, say so and stop instead of inventing requirements.

4. **Analyze the requirements**.
   - Identify the business capability or capabilities, the primary actor(s), the business value, business rules, constraints, and any acceptance criteria.
   - Requirements documents follow recognizable structures — user stories ("As a… I want… So that…"), Jira-style fields (Summary / Observed Behavior / Expected Behavior / Conditions / Replication Steps / Acceptance Criteria), requirement tables with IDs (REQ-001, AC-02, …), or spreadsheets with one requirement per row. Map these to scenarios using the skill's Jira-ticket rules where applicable.
   - For spreadsheets with multiple sheets, treat each sheet as a section of the requirements.

5. **Generate the Gherkin scenarios**.
   - Ground every scenario in what the document actually states — do **not** invent requirements that are not in the document.
   - Cover, as far as the document supports them: happy paths, validation / invalid input, business-rule and state-based cases, boundary / edge cases, and error cases.
   - Where the document is ambiguous, choose the most reasonable interpretation, proceed, and record the assumption in the final summary. This action usually runs unattended from Dino Desktop, so do not block on clarifying questions.

6. **Save the feature files**.
   - Write each capability to `${2:-tests/features/}/<capability-name>.feature` using a clear kebab-case file name (e.g. `loan-approval.feature`, `customer-onboarding.feature`).
   - If the document covers multiple distinct capabilities, split it into multiple feature files in the output directory.
   - When the document numbers its requirements (REQ-014, AC-2, …), add a brief `# REQ-014` comment above each scenario it produced, so coverage stays traceable back to the document.

## Output

- The saved `.feature` file path(s).
- A coverage summary: how many requirements / acceptance criteria were found, how many scenarios were generated per category (happy path, validation, edge cases, errors), and any requirement IDs that could not be covered — with the reason.
- Any assumptions made about ambiguous requirements.