| name | specflow-simulate |
| description | Simulates end-to-end usage of a Specflow story across multiple personas and divergent routes to discover gaps, edge cases, and unhandled branches BEFORE the story is built — then proposes each finding as a concrete story addition (new REQ, negative-path AC, Gherkin branch, or journey step). This is the high-value exploratory step run right after a story is created, distinct from the pre-flight compliance gate. This skill should be used when the user asks to "simulate this story", "simulate usage end to end", "find gaps and edges", "run personas through this", "stress-test this story", or invokes /specflow-simulate on a story file or GitHub issue. Scope is Specflow story exploration — it is generative (surfaces and proposes), not a build or a verification gate. |
Specflow Simulate
Run a story through realistic usage — multiple personas, multiple routes — to find the gaps and edges a single happy-path reading misses. The output is not commentary; it is a set of concrete, proposed additions that make the story sharper before any code is written.
When to run
Trigger on: "simulate this story", "simulate usage end to end", "find gaps / edges", "run personas through this", "stress-test this story", or /specflow-simulate <file-or-issue>.
Position in the Specflow flow — this runs after create, before audit:
create (specflow-writer) → SIMULATE (this skill) → audit/uplift (specflow-audit) → pre-flight gate
It is generative (discover + propose). It is NOT the pre-flight gate (that verifies and blocks). Do not conflate the two.
The method
Full method (persona archetypes, route taxonomy, gap→edit mapping, output format) is in references/simulation-method.md. Summary:
- Read the story (issue via
gh issue view <n> --json title,body,comments, or the file). Extract the intended outcome, the actors, and the surfaces.
- Derive 3–5 distinct personas — not demographics; behavioural archetypes that route through the problem differently (e.g. power user, first-timer, adversarial/edge user, wrong-permissions user, interrupted/returning user). Pick the ones that stress this story.
- Walk each persona through the story end-to-end — the happy path AND at least one divergent route per persona: where do they get confused, blocked, take an unanticipated branch, hit an empty/error/permission state, or make a decision the story didn't plan for?
- Collect gaps — each gap is a concrete moment where the story is silent, ambiguous, or wrong for that persona/route.
- Map every gap to a story edit — a new
REQ-NN, a negative-path AC, a new Gherkin scenario/branch, a new journey step + data-testid, or a flagged open question. A gap with no proposed edit is incomplete.
- Propose, don't silently rewrite — post the findings as ONE labelled block: a GitHub comment (
gh issue comment) or an appended ## Simulation Findings (proposed) section. The user (or the subsequent specflow-audit uplift) folds accepted items into the story body. Only edit the body directly if the user explicitly says to apply.
Parallel personas (optional, for thorough runs)
For a deep simulation, fan out one agent per persona so each route is explored independently and blind to the others — this surfaces more than one sequential reading. The ux-critique skill already runs parallel persona agents against a live screen; reuse that pattern here, scoped to the story text rather than a running UI. Then dedupe and synthesize into the single findings block.
Output shape
Report, and post as the findings block:
- the personas chosen and why each stresses this story,
- per persona: the route taken + the gaps found,
- a consolidated proposed-additions list (REQ / AC / Gherkin / journey-step), each tagged with the persona/route that motivated it,
- open questions that need a human decision (don't invent answers to product questions).
Reference
references/simulation-method.md — persona archetypes, route taxonomy, gap→edit mapping table, and the ## Simulation Findings (proposed) format.
