aio-gherkin-refine

aio-gherkin-refine

Transforms vague requests into clear Gherkin scenarios and reviews existing Gherkin for quality. Serves developers, BA/QA/Product, and Claude agents.

Mode Detection

REVIEW mode — when user pastes existing Gherkin, says "review", "improve", "check my scenarios":

1. Load references/review-checklist.md
2. Rate each scenario: ✅ Good / ⚠️ Needs Work / ❌ Rewrite
3. Show before/after for each issue with explanation
4. End with quality score and top 3 improvements

WRITE mode — when request is new, ambiguous, or user says "write", "create", "draft":

1. Load references/mental-models.md — use Example Mapping to extract rules/examples/questions
2. Load references/writing-guide.md — apply declarative style and naming conventions
3. Draft Feature file with happy path + at least one failure scenario
4. Present to user for confirmation before implementing

When in doubt: default to WRITE mode, offer REVIEW as an option.

Example Mapping Quick-Start (WRITE mode)

Before writing any Gherkin, run a mini Example Mapping session:

Story: [what the user wants]
  Rule 1: [business rule derived from story]
    Example: [concrete example that tests this rule]
    Example: [edge case]
  Rule 2: [another rule]
    Example: [...]
  Questions: [anything unclear — ask user before proceeding]

If you have more than 4 examples for a single rule, the rule is too broad — split it.

Output Format

Always use fenced code blocks with gherkin syntax:

Feature: [noun phrase — what capability this describes]

  Background:  # only if ALL scenarios share this context
    Given [shared precondition]

  Scenario: [complete sentence describing the rule being tested]
    Given [initial context — who, what state]
    When [the action that triggers behavior]
    Then [the observable outcome]

  Scenario: [failure or alternative case]
    Given [different context]
    When [same or different action]
    Then [different outcome]

After presenting Gherkin, always ask: "Does this capture what you need? Any scenarios to add or modify?"