Race Condition Diagnosis Prompt from Logs

This prompt is designed for backend and reliability engineers who are actively investigating an intermittent concurrency bug that has manifested in production or staging logs. The core job-to-be-done is reconstructing a coherent, interleaved execution timeline from dozens of noisy, distributed log lines across multiple services, threads, or goroutines. The ideal user has already collected raw log evidence showing a race condition—such as corrupted shared state, inconsistent reads, or deadlocks—but cannot visually parse the exact ordering of events that led to the failure. The prompt requires three non-negotiable inputs: the raw log lines with their timestamps and service/thread identifiers, the relevant source code files that manage the shared state in question, and a brief description of the observed symptom (e.g., 'counter underflow' or 'duplicate transaction'). Without all three, the model cannot ground its analysis in evidence.

Use this prompt when you have a high-confidence signal that a race condition exists but need a structured hypothesis to guide a code fix. It is particularly effective for debugging lock contention, channel deadlocks, non-atomic read-modify-write sequences, and missing synchronization in multi-threaded or distributed workflows. The prompt works best with logs that include precise timestamps (millisecond granularity or finer), consistent correlation IDs, and thread or goroutine identifiers. If your logs lack these fields, the reconstruction will be speculative and should be treated as a starting point for adding instrumentation, not a definitive diagnosis. The prompt also assumes the relevant source code is available and can be provided in full; partial or obfuscated code will degrade the sequence diagram accuracy and may produce unsafe locking recommendations.

Do not use this prompt for deterministic bugs, single-threaded failures, or incidents where no relevant source code is available. It is not a substitute for a debugger or a race detector tool like ThreadSanitizer; rather, it complements those tools by synthesizing evidence you already have into a testable hypothesis. Avoid using this prompt when the log volume is so high that it exceeds the model's context window—pre-filter logs to the relevant time window and services before invoking the prompt. Finally, never deploy a locking fix generated by this prompt directly to production without human code review, concurrency testing, and preferably a targeted stress test that attempts to reproduce the original race condition under load. The prompt's output is a diagnostic aid, not a verified patch.

This prompt is designed to be pasted directly into your AI coding agent or LLM interface. It instructs the model to act as a concurrency-focused backend investigator, correlating interleaved log entries from multiple services or threads with the shared-state access patterns found in your repository's source code. The goal is to move beyond symptom description and produce a testable hypothesis: a sequence diagram of the suspected race and a concrete code change proposal.

textCopy
You are a senior backend engineer specializing in distributed concurrency bugs. Your task is to diagnose a suspected race condition using application logs and the corresponding source code.

## INPUTS
- **Incident Description:** [INCIDENT_SUMMARY]
- **Logs (interleaved, with timestamps and service/thread IDs):**

[INTERLEAVED_LOGS]

codeCopy
- **Relevant Source Files:**
- `[FILE_PATH_1]`:
  ```[LANGUAGE_1]
  [SOURCE_CODE_1]
  ```
- `[FILE_PATH_2]`:
  ```[LANGUAGE_2]
  [SOURCE_CODE_2]
  ```
- **Known Shared State:** [SHARED_RESOURCE_DESCRIPTION] (e.g., database row, cache key, in-memory map)

## CONSTRAINTS
- Ground every claim in a specific log timestamp or a specific line of source code.
- If the evidence is insufficient to confirm a single root cause, state the uncertainty and list the top competing hypotheses.
- Do not propose a fix that introduces a new deadlock risk without noting it.

## OUTPUT SCHEMA
Respond with a JSON object containing the following keys:
- `execution_timeline_hypothesis`: An array of ordered steps describing the interleaved execution you believe occurred. Each step must include `timestamp`, `actor` (service/thread), `action`, and `source_evidence` (log line or code reference).
- `sequence_diagram_mermaid`: A string containing a valid Mermaid sequence diagram representing the hypothesis.
- `race_window_analysis`: A string explaining the exact lines of code where the critical section was entered without proper synchronization, and the duration of the vulnerability window.
- `locking_fix_proposal`: An object with keys `strategy` (e.g., 'pessimistic lock', 'compare-and-swap', 'queue'), `code_diff` (a unified diff string), and `trade_offs` (a list of strings noting performance impact or new risks).
- `confidence_score`: A string ('High', 'Medium', 'Low') with a one-sentence justification.
- `further_investigation`: A list of specific log statements or metrics to add to improve future diagnosability.

To adapt this template, replace the square-bracket placeholders with your actual incident data. The [INTERLEAVED_LOGS] placeholder is critical: you must merge logs from all participating services or threads and sort them by timestamp before insertion. The quality of the diagnosis depends heavily on accurate clock synchronization and complete log coverage of the shared resource access. If your logs lack thread or request IDs, add a note in the [INCIDENT_SUMMARY] so the model accounts for ambiguity. For high-severity production incidents, always have a senior engineer review the proposed locking_fix_proposal before merging any code change.

This prompt is designed to operate as a diagnostic step within an incident response pipeline, not as a standalone chat interaction. The implementation harness must ingest distributed log fragments, correlate them with source code from the repository, and produce a structured hypothesis that an on-call engineer can validate before acting. The prompt expects three input channels: a [LOG_FRAGMENTS] block containing timestamped log lines from multiple services or threads, a [SHARED_STATE_ACCESS_PATTERNS] block extracted from source code analysis of mutexes, locks, atomic operations, or database transactions, and a [REPOSITORY_CONTEXT] block with relevant file paths and recent commits. Wire these inputs through a pre-processing layer that deduplicates log lines, normalizes timestamps to a common timezone, and filters noise before assembly into the prompt.

The output schema must be enforced through a validation layer before the hypothesis reaches a human reviewer. Expect a JSON response with interleaving_timeline (an ordered array of events with service, thread, timestamp, and action fields), race_window_candidates (time ranges where conflicting access likely occurred), shared_state_analysis (mapping each contended resource to its locking discipline and violation evidence), and fix_proposal (a structured recommendation with code-level changes and locking strategy). Implement a schema validator that rejects responses missing required fields, containing timestamps outside the input range, or proposing fixes that reference files not present in the repository context. On validation failure, retry once with a more constrained prompt that includes the specific validation error. After two failures, escalate to a human with the partial output and error log.

Model choice matters for this workflow. Use a model with strong reasoning capabilities and a context window large enough to hold interleaved log traces from multiple services—typically 100K+ tokens for production incidents. Claude 3.5 Sonnet or GPT-4o are suitable defaults. Avoid smaller or faster models that may conflate thread identities or miss subtle ordering violations. If the log volume exceeds the context window, implement a pre-processing step that samples representative time slices around error spikes or uses log pattern clustering to reduce redundancy before prompt assembly. Do not truncate arbitrarily; missing log segments can hide the interleaving that reveals the race.

Grounding is the highest-risk failure mode. The prompt must never fabricate file paths, function names, or locking primitives that do not exist in the repository. Implement a post-processing grounding check that verifies every file path and function name in the fix_proposal against the repository's symbol index. Flag any hallucinated references for human review. Additionally, log every prompt invocation with the input hash, output hash, validation result, grounding check result, and reviewer decision. This audit trail is essential for post-incident review and for improving the prompt over time. Store these records in the incident management system, not in ephemeral chat logs.

Human review is mandatory before applying any fix proposal. The prompt output is a diagnostic hypothesis, not a verified root cause. The review interface should display the interleaving timeline as a swimlane diagram, highlight the race window candidates on a shared timeline, and show the proposed code changes as a diff against the current repository state. The reviewer must confirm or reject each race window candidate and approve or modify the fix before it enters the deployment pipeline. Never automate code changes from this prompt without human approval—race condition fixes can introduce deadlocks or performance regressions if applied without understanding the full concurrency model.