executable-stories

Use when the user asks for a rich explanation of a code change, diff, branch, or PR in a repo that uses executable-stories. Produces an explainer that is part of the living documentation — grounded in run artifacts, published next to the stories, and finished with a comprehension quiz — instead of a throwaway HTML file.

Use when teaching a technical or coding topic (onboarding, katas, LeetCode-style practice, a library, a pattern) and you want each lesson to be runnable and self-proving. Authors lessons as executable story tests so the lesson, the test, and the living documentation are one artifact. Companion to the `teach` skill: teach owns the pedagogy (mission, progression, references) and this skill owns the verification layer.

Bootstrap executable-stories into a repo from zero. Installs Vitest and/or Playwright if missing, wires the StoryReporter, drops a sample story test, and adds a test script. Use when the user wants to "set up executable-stories", "add story testing to this repo", "initialize executable-stories", "bootstrap from scratch", or runs `pnpm dlx executable-stories-init`. Mirrors the `executable-stories-init` CLI; prefer the CLI when available, otherwise follow the manual checklist.

Use when running the executable-stories CLI or formatters API: turning a RawRun into a report (Astro, Confluence, HTML, Markdown, JUnit, Cucumber, story-report-json, etc.), gating a release, comparing runs, reviewing AI-authored changes, or driving agent-loop commands (check/triage/goal).

Use when writing BDD story tests in Jest with executable-stories-jest: top-level given/when/then/and/but imports, story.init(), or doc entries.

Use when writing BDD story tests in Vitest with executable-stories-vitest: the callback-only story.init(task) API, given/when/then/and/but steps, or doc entries.

Use when incrementally adopting executable-stories in an existing Cypress test suite, converting cy.ts specs to story tests, or adding story.init() without a full rewrite. Progressive enhancement of .story.cy.ts files; requires plugin and support-file wiring.

Use when configuring the executable-stories-cypress reporter: wiring the Mocha reporter via --reporter or cypress.config.ts, or using the module API (buildRawRunFromCypressResult, generateReportsFromRawRun) for programmatic report generation.

Use when writing BDD story tests in Cypress with executable-stories-cypress: story.init(), given/when/then steps, doc entries, or the browser-Node bridge via cy.task.

Use when setting up ESLint rules for executable-stories-jest: enforcing story.init() ordering before steps, story-context scoping for step calls, or test-context requirements for doc.story.

Use when setting up ESLint rules for executable-stories-playwright: enforcing story.init() ordering before steps, story-context scoping for step calls, doc.story test-context requirements, or detecting Playwright test modifiers (only/skip/fixme/fail/slow).

Use when setting up ESLint rules for executable-stories-vitest: enforcing the story.init(task) argument requirement, test-context scoping for story.init, or init-before-steps ordering.

Use when writing BDD story tests in Go with executable-stories-go: Init(t, scenario, opts...), Given/When/Then/And/But steps, doc entries, or RunAndReport output in TestMain.

Use when incrementally adopting executable-stories in an existing Jest test suite, converting test blocks to story tests, or adding story.init() and top-level step imports without a full rewrite. Progressive enhancement of .story.test.ts files.

Use when configuring the executable-stories-jest custom reporter: wiring the jest.config reporters array, setupFilesAfterEnv for story flushing, or output format/directory/naming and aggregated vs. colocated modes.

Use when writing BDD story tests in JUnit 5 (Kotlin/Java) with executable-stories-junit5: the static Story.init/given/when/then/and/but API, wrapped steps, or automatic JSON output via TestExecutionListener.

Use when incrementally adopting executable-stories in an existing Playwright test suite, converting spec blocks to story tests, or adding story.init(testInfo) without a full rewrite. Progressive enhancement of .story.spec.ts files.

Use when configuring the executable-stories-playwright custom reporter: wiring the playwright.config.ts reporter array, or output format/directory/naming and aggregated vs. colocated modes.

Use when writing BDD story tests in Playwright with executable-stories-playwright: story.init(testInfo), async steps with fixtures, or doc entries.

Use when writing BDD story tests in Python with executable-stories-pytest: the module-singleton story API (story.init, given/when/then/and_/assert_), wrapped steps, or automatic JSON output via pytest plugin hooks.

Use when writing BDD story tests in Ruby Minitest with executable-stories-ruby: ExecutableStories.init, given/when/then/and/but steps, or doc entries.

Use when writing BDD story tests in Rust with executable-stories-rust: the Story::new() builder, given/when/then/and/but steps, or write_results() JSON output.

Use when transforming low-level automated tests into clearer business-facing executable specifications without losing behavioural coverage. Preserves what the tests prove while rewriting how they communicate.

Use when writing new executable story tests, converting existing tests to stories, or reviewing story test quality. Guides specification shape using OOPSI decomposition before writing Given/When/Then.

Layers an evidence discipline over the per-framework story API so each AI-authored change is communicated with proof — declared change-type, intent/approach, and a test whose pass is credible — for the Evidence Review report. Use when authoring or reviewing changes surfaced through `executable-stories review` or the action's `mode: review`, or when the user mentions evidence review, reviewing AI changes by behaviour and proof, change-type tags, or evidence-graded tests.

Use when refining requirements with examples, rules, and open questions before writing scenarios or story tests. Turns fuzzy conversations into structured specification material.

Use when writing executable specifications that should remain readable and useful long after implementation as a trusted source of truth. Focused on longevity, organisation, and readability for mixed audiences.

Use when discovering behaviour from user goals and driving system design from the outside in using scenarios. Based on Dan North's view that BDD is collaborative discovery, not test scripting.

Use when you have raw examples, acceptance criteria, or conversation notes and need to refine them into concise, business-readable executable specifications. Based on Gojko Adzic's Specification by Example.

Use when reviewing existing scenarios, story tests, or specifications for clarity, coverage, rule separation, and maintainability. Provides a structured critique checklist.

Use when specifying business rules, validations, calculations, eligibility, or policy-heavy behaviour. Focuses on decision tables, boundaries, rule combinations, and precedence.

Use when specifying multi-step workflows, approvals, handoffs, state transitions, or long-running business processes. Covers happy paths, alternate paths, interruptions, and ownership.

Use when incrementally adopting executable-stories in an existing Vitest test suite, converting it/test blocks to story tests, or adding story.init(task) without a full rewrite. Progressive enhancement of .story.test.ts files.

Use when configuring the StoryReporter in vitest.config.ts for executable-stories-vitest: OutputConfig, aggregated vs. colocated output modes, or GitHub Actions summary integration.

Use when writing BDD story tests in xUnit (C#) with ExecutableStories.Xunit: the static Story.Init/Given/When/Then/And/But API, wrapped steps, or Story.RecordAndClear() output.

Posts idempotent Linear evidence receipts from executable-stories review reports using Linear MCP. Use when the user asks to update Linear from an Evidence Review, post a green-tick receipt to linked Linear issues, summarize verified behaviour on tickets, or use Linear MCP with executable-stories reports.