# Gherkin Desk

> Paste one Cucumber/SpecFlow `.feature` file and work it five ways in one sitting. A deterministic
> Gherkin parser runs free in the browser first; the AI lanes are then held to what that parser found.

Live at https://gherkin-desk.skillsafe.ai/ · API tutorial at https://gherkin-desk.skillsafe.ai/api.html

## What it is

A single-work-object app. The work object is one Gherkin feature file — the `.feature` files that
Cucumber (Ruby, JVM, JS), behave, SpecFlow and Reqnroll execute. Everything the app does takes that
same file as its input.

## The free lane (no account, nothing uploaded)

A hand-written Gherkin reader in the browser builds the AST — `Feature`, `Rule`, `Background`,
`Scenario`, `Scenario Outline`/`Scenario Template`, `Examples`, tags, doc strings, data tables,
`# language:` headers, escaped table cells — and then:

- runs 29 deterministic lint rules over it;
- prints the file back in canonical form with every table aligned on its widest cell, without
  inventing a cell a row does not have;
- reduces every step to a **signature** (`I request {int} dollars`), which is what a step-definition
  file actually matches on, and reports how many definitions the file owes;
- generates the undefined-step skeletons in Ruby (Cucumber), JavaScript (Cucumber.js), Python
  (behave) or Java (Cucumber JVM);
- exports the findings as CSV.

None of that needs sign-in, and nothing leaves the browser.

### The lint rules

`GD01` no/unnamed Feature · `GD02` no narrative under Feature · `GD03` scenario asserts nothing (no
Then) · `GD04` scenario has no Given · `GD05` scenario has no When · `GD06` more than one When ·
`GD07` steps out of order (Given after the action, When after a Then) · `GD08` scenario opens with
And/But · `GD09` Scenario Outline with no Examples, or an Examples table with no rows · `GD10`
`<placeholder>` never declared in an Examples header, or used in a plain Scenario · `GD11` Examples
column never read by any step · `GD12` Examples row width does not match its header · `GD13`
duplicate scenario name · `GD14` duplicate Examples row · `GD15` imperative UI step (clicking,
typing, selectors, hard waits) · `GD16` step longer than 18 words · `GD17` Background contains a
When or Then · `GD18` Background longer than four steps · `GD19` more than twelve scenarios in one
file · `GD20` `@wip`/`@skip`/`@ignore` present · `GD21` two steps that reduce to one signature ·
`GD22` environment-coupled literal (URL, IP, port, localhost) · `GD23` empty scenario or Background ·
`GD24` unnamed scenario · `GD25` the file does not parse cleanly · `GD26` no tags anywhere · `GD27`
step joins several things with "and" · `GD28` credential committed in step text · `GD29` non-English
language header.

Severities are literal: `blocker` means the file is wrong or unsafe, `warn` means it runs but the
practice is a named BDD defect, `note` is worth seeing and never worth blocking on.

## The five AI lanes

Each run sends `task` plus the feature text plus the browser's own facts, and the reply must
reconcile against every flag the browser raised.

| `task` | What it produces |
| --- | --- |
| `audit` | A senior BDD review: one verdict per scenario (`solid`/`weak`/`split-it`/`delete`), domain-language inconsistencies, a structure note. |
| `rewrite` | The whole file rewritten declaratively. The result is re-parsed and re-linted in the browser in front of the user. |
| `gaps` | The scenarios the file never covers — edge cases, error states, boundaries, permissions, concurrency, data, recovery paths, non-functional — each as ready-to-paste Gherkin, ranked by risk. |
| `stepdefs` | One step definition per distinct signature in `ruby`, `javascript`, `python` or `java`, with Cucumber Expressions and the ambiguities named. Coverage is checked against the browser's signature index. |
| `testplan` | A manual QA plan: objective, role, priority, preconditions, numbered action/expected pairs, pass criteria, traced back to the scenario. |

Handoffs are buttons, not copy-paste: a rewrite feeds `stepdefs`, an audit feeds `rewrite`, the gaps
feed back into `rewrite`.

## The output contract

Every lane returns one JSON object with the same envelope — `task`, `title`, `verdict`, `summary`,
`assumptions[]`, `open_questions[]`, `findings[]`, `reconciliation[]`, `next_lane`, `body` — and only
`body` differs per lane. `findings[]` entries carry `id`, `severity` (`blocker`/`major`/`minor`),
`scenario`, `line`, `issue`, `why`, `fix`. `reconciliation[]` carries one entry per distinct browser
flag id with `status` of `confirmed`, `cleared` or `not-assessed`; a flag the reply never addressed is
shown to the user as unanswered rather than dropped.

## How it behaves about facts

- The file is always parsed **whole**; only the text sent to the model is clipped, and it is clipped
  on whole-scenario boundaries with the `Feature` header and the `Background` always kept, because a
  scenario truncated mid-step would be reviewed as though it were the file.
- The browser's counts are authoritative. Where the model's reading disagrees, the disagreement is
  displayed.
- A credential found in a step is reported before any advice about style, because a password pasted
  into a `.feature` file is already in version control.
- No lane claims to have executed anything. The app never runs a test suite.

## Sources

Derived from and crediting:

- `@el-feo/cucumber-gherkin` — Gherkin keywords, Cucumber Expressions, step definition and hook
  patterns.
- `@thebushidocollective/bdd-patterns` — Given-When-Then structure, feature files, acceptance
  criteria.
- `@product-on-purpose/deliver-edge-cases` — edge cases, error states, boundary conditions, recovery
  paths.
- `@phuryn/test-scenarios` — test objectives, starting conditions, roles, step-by-step actions and
  expected outcomes.

This app is a derived work. It does not republish any of those skills.

## Metering

Runs cost credits and need an account (`gpt-terra`, publisher markup 1000 bps). The free lane —
parser, 29 rules, formatter, signature analysis, skeletons, CSV export — costs nothing and needs no
sign-in. Every lane also ships a bundled example reply that replays with no run and no charge.