Race Condition Flakiness Identification Prompt

This prompt is designed for test infrastructure engineers and SDETs who need to diagnose timing-dependent test failures that pass or fail unpredictably across runs. The core job-to-be-done is classifying whether a flaky failure is a true race condition—where two or more operations access shared state without proper synchronization—or a deterministic timing issue such as a fixed but insufficient sleep, a missing await, or a slow resource that always resolves given enough time. The distinction matters because race conditions require synchronization fixes (locks, mutexes, atomic operations, ordered queues), while deterministic timing issues require wait-strategy corrections (explicit awaits, polling with timeouts, event-driven triggers). Using the wrong fix class wastes engineering time and can mask real concurrency bugs.

You should use this prompt when you have collected execution logs from multiple test runs—ideally five or more—that include timestamps with at least millisecond precision, thread or process identifiers, and resource access sequences such as lock acquisitions, database transactions, file writes, or shared memory operations. The prompt expects structured evidence: thread interleaving patterns, synchronization point logs, and timing deltas between dependent operations. Without this data, the model cannot distinguish between a race condition and a slow operation. Do not use this prompt for failures where no timing or concurrency data is available, for simple assertion failures with no interleaving evidence, or for failures in purely sequential single-threaded test suites. The prompt produces a structured classification with confidence scores and fix recommendations, but these recommendations require code-level verification before implementation—the model cannot see your actual synchronization primitives or memory model.

Before running this prompt, ensure your log collection captures the right signals: thread IDs or goroutine names, entry and exit timestamps for critical sections, lock acquisition and release events, and the order of operations on shared resources. If your test framework does not log these by default, instrument the code paths under test with structured logging before collecting evidence. The prompt's classification accuracy depends on the granularity and completeness of this timing data. After receiving the output, validate the classification by reproducing the failure under controlled concurrency stress (e.g., running with -race flags, increasing thread count, or injecting artificial delays at suspected race points). The prompt's fix recommendations are starting points for investigation, not production-ready patches.

This prompt template is designed to be pasted directly into your AI workflow. It expects structured evidence from test execution logs, thread/process traces, and synchronization point data. Replace every square-bracket placeholder with your actual data before execution. The prompt instructs the model to act as a senior concurrency engineer, analyze the provided evidence, and output a structured JSON classification with fix recommendations and confidence scores. The output is designed to be machine-readable for integration into your test triage pipeline.

textCopy
You are a senior concurrency engineer analyzing a timing-dependent test failure. Your task is to classify the failure as a Race Condition or a Deterministic Timing Issue and propose specific code-level fixes.

## INPUT DATA

### Test Failure Context
- Test Name: [TEST_NAME]
- Test Suite: [TEST_SUITE]
- Failure Rate: [FAILURE_RATE] (e.g., "~30% of runs")
- Last Stable Run: [LAST_STABLE_TIMESTAMP]

### Execution Logs (Relevant Snippets)

[THREAD_PROCESS_LOGS]

codeCopy

### Synchronization Points Identified
[Synchronization_POINTS]

### Code Context (Optional)
```[LANGUAGE]
[RELEVANT_CODE_SNIPPETS]

OUTPUT SCHEMA

You must respond with a single JSON object conforming to this structure: { "classification": "race_condition" | "deterministic_timing", "confidence": 0.0-1.0, "evidence_summary": "string", "root_cause_hypothesis": "string", "fix_recommendations": [ { "category": "lock" | "retry" | "async_await" | "refactor" | "environment", "description": "string", "code_snippet": "string or null", "complexity": "low" | "medium" | "high" } ], "requires_code_verification": true }

CONSTRAINTS

• Base your analysis strictly on the provided logs and code context. Do not invent external factors.
• If the evidence is insufficient for a high-confidence classification, set confidence below 0.5 and state what additional data is needed in the evidence_summary.
• For race conditions, focus on unsynchronized access to shared mutable state.
• For deterministic timing issues, focus on fixed sleeps, missing await/join, or assumptions about execution order without explicit synchronization.
• All fix recommendations must be actionable by a developer and require code-level verification.

To adapt this template, replace the placeholders with data extracted from your CI/CD pipeline or test runner. The [THREAD_PROCESS_LOGS] placeholder should contain the raw log lines surrounding the failure, including timestamps and thread IDs. The [SYNCHRONIZATION_POINTS] field can be a list of known locks, semaphores, or async operations in the code under test. If you have access to the source code, include the relevant sections in [RELEVANT_CODE_SNIPPETS] to improve classification accuracy. The output JSON can be parsed by your test triage automation to automatically route the failure to the appropriate team or create a ticket with the fix recommendations pre-filled.

This prompt is designed to operate as a classification and recommendation step inside a broader flaky test triage pipeline. It expects structured input—failure timing patterns, thread or process logs, and identified synchronization points—and returns a structured classification with confidence scores and fix recommendations. The output is not a final verdict; it is a hypothesis generator that must be verified against code before any remediation is applied. Wire this prompt after log extraction and before any automated fix application.

Input assembly is the first integration point. Before calling the model, assemble the [FAILURE_TIMING_DATA], [THREAD_PROCESS_LOGS], and [SYNCHRONIZATION_POINTS] placeholders from your test execution artifacts. Timing data should include timestamps of failures, pass/fail boundaries, and any retry intervals. Thread logs must capture interleaving across concurrent workers, not just sequential dumps. Synchronization points should list known locks, semaphores, barriers, or async await boundaries in the code under test. If your CI system doesn't capture these signals, add instrumentation before relying on this prompt—the model cannot identify race conditions from generic stack traces alone.

Validation and retry logic must surround the model call. Parse the JSON output and validate that classification is one of the expected enum values (race_condition, deterministic_timing, insufficient_evidence), that confidence_score is a float between 0.0 and 1.0, and that fix_recommendations is a non-empty array when classification is race_condition. If validation fails, retry once with the validation error appended to the prompt as additional [CONSTRAINTS]. If the second attempt also fails validation, log the raw output and escalate for manual review rather than silently accepting a malformed classification.

Human review gates are mandatory for high-risk classifications. Any output where confidence_score exceeds 0.7 and classification is race_condition should create a review task for a senior engineer before the recommended fix (lock addition, retry logic, async await restructuring) is implemented. The prompt's fix recommendations are syntactically plausible but may be semantically wrong for your specific concurrency model. The review should verify that the identified synchronization point actually governs the contended resource and that the proposed fix doesn't introduce deadlocks or starvation. For insufficient_evidence classifications, route the test to enhanced logging rather than closing the investigation.

Model choice and tool use affect reliability. Use a model with strong code reasoning capabilities—GPT-4, Claude 3.5 Sonnet, or equivalent. This prompt does not require tool calling or RAG unless you want to ground fix recommendations against your internal concurrency patterns library. If you maintain a knowledge base of known race condition fixes, add a retrieval step that injects relevant examples into the [EXAMPLES] placeholder before the model call. For production pipelines processing hundreds of flaky tests, batch similar failure signatures and deduplicate before calling the model to avoid redundant API costs on identical timing patterns.

Logging and observability are critical for trust. Log every model call with the input hash, output classification, confidence score, and whether the classification was later confirmed or rejected by human review. Track the false positive rate of race_condition classifications over time—if the model consistently flags patterns that engineers dismiss, adjust the confidence threshold or add counterexamples to the prompt. Also monitor the insufficient_evidence rate; a rising trend indicates your log extraction pipeline is not capturing the signals this prompt needs, and you should improve instrumentation before blaming the prompt.