Race Condition Scenario Generation Prompt

This prompt is for test architects and backend engineers who need to move from sequential behavior specifications to verifiable concurrency acceptance criteria. Use it when you have a stable, approved sequential spec for a shared-resource operation—such as a Gherkin scenario describing a user updating a profile, reserving inventory, or transferring funds—and you need to generate Gherkin scenarios covering lost updates, dirty reads, write skew, and ordering violations. The prompt forces the model to identify shared resources, propose interleavings, and declare expected isolation levels before writing any scenario, ensuring the output is grounded in a specific concurrency model rather than generic threading advice.

Do not use this prompt when the sequential spec is incomplete or still under active revision, because the generated concurrency scenarios will inherit and amplify those ambiguities. It is also unsuitable when the system under test has no shared mutable state—if every operation is a pure function with no side effects on a shared store, there are no race conditions to model. Similarly, skip this prompt when the data store guarantees serializable isolation by default and the team has validated that guarantee; in that case, the prompt adds unnecessary specification overhead. This prompt belongs in a test design workflow after sequential acceptance criteria are approved and before concurrency test implementation begins. It is not a replacement for load testing, performance profiling, or deadlock detection—those require different tools and prompts.

Before running the prompt, gather the sequential Gherkin scenario, the data model or entity description for any shared resources, and the target isolation level your system claims to provide (e.g., READ COMMITTED, REPEATABLE READ, SERIALIZABLE). If you cannot articulate which resources are shared or what isolation level is expected, the prompt will produce scenarios that are difficult to validate. After generation, review each scenario for correctness against your actual transaction boundaries and locking strategy. The prompt produces a starting point for concurrency test design, not a final test suite—human review is required to confirm that the proposed interleavings match your system's actual concurrency behavior and that the expected outcomes align with your isolation guarantees.

This template converts a sequential behavior specification into a set of Gherkin scenarios that test for race conditions. It forces the model to identify shared resources, propose interleavings, and produce scenarios with explicit isolation level expectations. Replace every square-bracket placeholder before sending the prompt to the model. The template is designed to be used as part of a test generation pipeline where the output is validated for structural correctness and coverage before being committed to a test repository.

textCopy
You are a concurrency test architect. Given a sequential behavior specification, your job is to generate Gherkin scenarios that expose potential race conditions.

## INPUT
Sequential Behavior Specification:
[SPECIFICATION]

System Architecture Context (shared resources, data stores, services):
[ARCHITECTURE_CONTEXT]

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "shared_resources": [
    {
      "resource": "string (e.g., 'user_balance_row', 'inventory_count')",
      "access_pattern": "string (read, write, read-modify-write)",
      "contention_risk": "high | medium | low"
    }
  ],
  "scenarios": [
    {
      "scenario_id": "string",
      "title": "string",
      "race_category": "lost_update | dirty_read | write_skew | ordering_violation | phantom_read | duplicate_execution",
      "isolation_level_required": "read_committed | repeatable_read | serializable | snapshot",
      "gherkin": "string (full Gherkin block with Feature, Scenario, Given, When, Then, and Examples table if parameterized)",
      "interleaving_description": "string (step-by-step description of the concurrent execution that triggers the race)",
      "expected_failure_mode": "string (what breaks if isolation is insufficient)",
      "detection_method": "string (how to observe the race in test output, e.g., assertion failure, log anomaly, data invariant violation)"
    }
  ],
  "coverage_gaps": ["string (categories of races not covered and why)"]
}

## CONSTRAINTS
- Every scenario must reference at least one shared resource from the shared_resources list.
- For each shared resource, produce at least one scenario per applicable race category.
- Gherkin must use concrete values, not placeholders, unless parameterized in an Examples table.
- Isolation level expectations must be explicit and justified by the interleaving description.
- If the specification lacks enough detail to identify shared resources, output an empty shared_resources array and explain what information is missing in coverage_gaps.
- Do not invent system components not mentioned in ARCHITECTURE_CONTEXT.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK_LEVEL
[RISK_LEVEL]

Adapt this template by adjusting the OUTPUT_SCHEMA to match your test management system's expected format. If your team uses a different race condition taxonomy, replace the race_category enum values. The FEW_SHOT_EXAMPLES placeholder should contain 2-3 worked examples showing the desired mapping from specification to scenarios. For high-risk financial or healthcare systems, set RISK_LEVEL to high to instruct the model to flag scenarios requiring additional human review and to include specific data integrity invariants in the expected_failure_mode field. Always validate the output JSON against the schema before ingestion, and run a coverage check to ensure every shared resource has scenarios for the race categories that apply to its access pattern.

This prompt is designed to be called programmatically as part of a CI-integrated test generation service or a QA engineer's local toolchain. The primary input is a sequential behavior specification (Gherkin feature file or structured acceptance criteria) and a shared-resource inventory (database tables, caches, message queues, file systems). The harness should pre-process the input to extract resource names, state transitions, and isolation level hints before assembling the final prompt. Because the output is Gherkin scenarios that will be committed to a test repository and potentially executed in CI, the harness must enforce schema validation, coverage checks, and a human review step before the generated scenarios reach the test suite.

The implementation should follow a three-stage pipeline: pre-generation enrichment, model invocation with retries, and post-generation validation. In the enrichment stage, parse the input specification to identify shared resources (tables, rows, counters, queues) and state-mutating steps. Build a resource-interleaving matrix that maps which steps touch which resources—this matrix feeds the [SHARED_RESOURCE_INVENTORY] and [INTERLEAVING_MATRIX] placeholders. For model invocation, use a model with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) with response_format set to JSON and the output schema defined as an array of Gherkin scenario objects. Implement a retry loop (max 3 attempts) that catches JSON parse failures, schema validation errors, and missing required fields. On retry, append the validation error to the prompt as [PREVIOUS_VALIDATION_ERRORS]. Log every invocation with the prompt version, input hash, model, latency, token counts, and validation outcome for observability.

Post-generation validation must run before the scenarios are presented for human review. Validate that each generated scenario includes: a Scenario title, explicit Given preconditions that reference concurrency state (e.g., 'Given two concurrent sessions for user A'), When steps that describe interleaved actions, Then outcomes that specify expected isolation behavior, and an @isolation tag with the expected isolation level (@read-committed, @repeatable-read, @serializable). Run a coverage check: every shared resource identified in the input must appear in at least one generated scenario. Flag scenarios that describe lost updates without a corresponding @isolation tag of @serializable or higher. If the validation failure rate exceeds 30% across retries, escalate for manual prompt refinement rather than continuing to retry. After validation passes, route the generated scenarios to a review queue where a test architect or senior QA engineer can approve, edit, or reject each scenario. Only approved scenarios should be merged into the test repository. For high-risk domains (financial systems, healthcare data, safety-critical systems), require two-person review and add a @reviewed-by tag with reviewer identifiers before merge.