Workflow State Transition Scenario Prompt

Use this prompt when you have a defined state machine, status workflow, or entity lifecycle and need executable Gherkin scenarios that verify every transition, guard condition, and side effect. This prompt is designed for QA engineers, SDETs, and product teams who must ensure that no invalid state transition is possible and that every valid transition produces the correct side effects. The prompt assumes you can provide a state diagram, transition table, or structured description of states, events, guards, and actions.

The prompt is not suitable for undefined workflows, purely sequential processes without branching, or systems where state is not explicitly modeled. If your workflow lacks clear state definitions, guard conditions, or side-effect descriptions, the model will hallucinate transitions or produce non-verifiable scenarios. Before using this prompt, confirm that you have a source of truth—such as a state diagram, a transition matrix, or a structured specification—that enumerates allowed and disallowed transitions. The prompt works best when you can supply concrete artifacts like a list of states, the events that trigger transitions, the conditions that must be true for a transition to fire, and the actions the system performs as a result.

For high-risk domains such as payments, healthcare, or access control, always pair the generated scenarios with human review and a coverage checklist. The model may miss implicit transitions, concurrency edge cases, or rollback paths that are not explicitly documented in your input. After generating scenarios, validate that every state has defined entry and exit criteria, every guard condition is tested, and every invalid transition is explicitly prohibited. If your state machine includes timer-based transitions, asynchronous callbacks, or compensating actions, supplement this prompt with the Race Condition Scenario Generation Prompt or the Retry and Recovery Scenario Generation Prompt to achieve full coverage.

This prompt template is designed to be pasted directly into your AI harness. It instructs the model to act as a QA architect specializing in stateful system behavior. The model will analyze a provided state machine specification and produce a comprehensive set of Gherkin scenarios. The core value is in systematically covering not just the 'happy path' transitions, but also invalid transitions, guard conditions, and side effects that are often missed in manual test design.

textCopy
You are a QA architect specializing in stateful system behavior. Your task is to generate a comprehensive set of Gherkin scenarios from a state machine specification.

# SPECIFICATION
[STATE_MACHINE_SPECIFICATION]

# OUTPUT SCHEMA
Produce a single JSON object with a "scenarios" array. Each object must have:
- "scenario_name": (string) A clear, descriptive title.
- "feature": (string) The feature or component under test.
- "scenario_type": (string) One of: "happy_path", "invalid_transition", "guard_condition", "side_effect", "rollback".
- "gherkin_text": (string) The complete Gherkin scenario, including tags like @happy-path or @invalid.
- "covered_states": (array of strings) The states involved in this scenario.
- "risk_notes": (string) A brief note on what could be missed if this scenario is not tested.

# CONSTRAINTS
- Ensure every state defined in the specification has at least one scenario covering its entry and exit criteria.
- For every valid transition, generate at least one happy-path scenario.
- For every valid transition, generate at least one invalid-transition scenario that attempts it from a wrong state.
- Explicitly test all guard conditions (e.g., `[is_paid]`, `[has_permission]`).
- Include scenarios for side effects like audit logs, emails, or external API calls.
- If the specification implies a rollback or cancellation path, generate a rollback scenario.
- Use clear, descriptive `Given`, `When`, `Then` steps. Use `Examples` tables for data-driven guard conditions.

# RISK LEVEL
[HIGH_RISK_WORKFLOW]

To adapt this prompt, replace the [STATE_MACHINE_SPECIFICATION] placeholder with your actual state machine definition. This can be a mermaid.js diagram, a structured table of states and transitions, or a detailed textual description. The [HIGH_RISK_WORKFLOW] placeholder should be replaced with a boolean (true or false). When set to true, the model will add an extra layer of caution, explicitly flagging scenarios that require human review before automation, such as those involving financial transactions or irreversible data mutations. After generation, validate the output JSON against the defined schema and review the risk_notes for each scenario to prioritize your testing efforts.

This prompt is designed to be called programmatically from a test management system or CI pipeline, not as a one-off chat interaction. The core integration contract is simple: your system provides a state machine definition as a structured object, and the prompt returns a set of Gherkin scenarios. To make this reliable in production, you must treat the prompt as a deterministic function with well-defined inputs, outputs, and error modes. Store the state machine definition as a versioned JSON or YAML file in your test repository and inject it into the [STATE_MACHINE_DEFINITION] placeholder at generation time. The definition must include states, transitions, guard conditions, side effects, and entry/exit criteria for every state. If your state machine is defined in a visual tool or a different format, preprocess it into the expected schema before calling the prompt.

Validation and retry logic are the most critical parts of the harness. Before committing generated scenarios to your feature files, validate the output against a Gherkin parser such as gherkin-lint or the @cucumber/gherkin library. The parser should confirm that every scenario is syntactically valid and that all referenced states and transitions exist in the input state machine definition. If the model produces scenarios that reference undefined states or transitions, do not silently discard them. Instead, append the validation error to the next request as a [PREVIOUS_VALIDATION_ERRORS] field and ask the model to correct only the failing scenarios. Limit retries to a maximum of three attempts; if validation still fails after three corrections, log the failure, flag the run for human review, and fall back to the last known good scenario set. For high-risk domains such as payments, access control, or healthcare workflows, require human approval on the first generation of any new state machine. Subsequent regenerations for the same machine can be gated on a diff review only, comparing the new scenario set against the previously approved version.

Logging and auditability turn this prompt from a black box into an observable system component. Log every generation run with at minimum: the prompt version (a SHA or semantic version stored alongside the template), the input state machine hash (SHA-256 of the normalized definition), the output scenario count, the validation pass/fail status, the retry count, and the model version used. Store these logs in your test management system or CI artifacts so you can trace any scenario back to its generation context. If you use multiple models for cost or latency reasons, note that smaller models may struggle with complex guard condition logic; route state machines with more than 15 transitions or nested conditionals to a more capable model. Finally, never let generated scenarios bypass your existing code review process. The prompt accelerates scenario authoring, but the output is a candidate artifact that must earn its place in your test suite through the same review gates as human-written specifications.