# Spec Generate

> Generate Gherkin acceptance scenarios from a context.md, with mandatory interview for ambiguities, concrete data, and test-level tags. Use after impact-map, or when the user provides a user story and rules and asks for scenarios.

- Skill: `mpiton/spec-generate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mpiton/spec-generate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mpiton/spec-generate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mpiton (https://skillmd.com/u/mpiton)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mpiton/spec-generate

---


# /spec-generate

Generate Gherkin scenarios from `specs/<us-slug>/context.md`. The pipeline calls this skill in Phase 2 §3 of the diagram.

## When to use

- After `impact-map` produced `context.md`.
- When the user pastes a structured story + rules and asks for acceptance scenarios.

## Inputs

- `specs/<us-slug>/context.md` (see [`impact-map`](../impact-map/SKILL.md)).

## Workflow

### 1. Interview (mandatory before generation)

Read `context.md` **first, and treat it as answered ground**. `impact-map` (or `from-issue`) already elicited the actor, the action, the goal, and the numbered rules — do NOT re-ask any of that. Re-interviewing fields the user already gave upstream is the main avoidable token cost in the spec phase; thread them forward instead.

Ask only the ambiguities that `context.md` does NOT already resolve — DO NOT guess on those. For each genuinely-new ambiguity, ask one focused question. Examples of things that always require a question if not already explicit in `context.md`:

- Numeric thresholds without units (`"limit of 100"` — 100 what?).
- Implicit time zones, date formats, currency.
- Identity / equality semantics (case sensitivity, trimming).
- Default values for omitted fields.
- Behavior on the boundary itself (`<=` vs `<`).

Stop the interview only when every rule can be expressed with concrete, unambiguous data.

### 2. Generate scenarios

For each business rule `R-NN`, produce one `.feature` file at `specs/<us-slug>/<rule-slug>.feature`.

Each file MUST contain scenarios covering at least:

- **Nominal** path (tag: `@nominal`).
- **Violation** of the rule (tag: `@violation`).
- **Authorization** path if the rule involves access (tag: `@auth`).
- **Technical** / integration edge if applicable (tag: `@technical`).
- **Limits / boundaries** for any numeric rule (tag: `@limit`).

Use **concrete data** (real values, not placeholders). Example: prefer `Given the cart contains 3 items at 19.99 EUR` over `Given some items in the cart`.

Add a `# Rule: R-NN` comment at the top of each feature file so traceability survives renames.

Triangulation: if a rule is complex, produce **multiple examples** (Scenario Outline with `Examples:`) rather than a single example.

### 3. Test-level tag

Tag each scenario by the appropriate test level:

- `@use-case` — pure domain / use case test.
- `@e2e` — end-to-end with the real adapters.
- `@ui` — UI driver (Playwright, RTL, etc.).

If unsure, ask the user before generating.

## Outputs

- `specs/<us-slug>/<rule-slug>.feature` — one per business rule.

## Handoff

Next: [`spec-review`](../spec-review/SKILL.md) on the generated `.feature` files.

## Anti-patterns

- **Don't** generate scenarios for rules that are not in `context.md`. Push back, ask `impact-map` to capture them first.
- **Don't** invent assertions; every assertion must trace to a rule.
- **Don't** mock the system under test in the scenario data. Scenarios describe behavior, not implementation.