PR Diff Race Condition Detection Prompt Template

This prompt is built for backend engineers, platform teams, and CI/CD pipelines that need automated, structured detection of race conditions, data races, and unsafe concurrent access patterns in pull request diffs. It ingests a unified diff or a set of changed files with clear before/after context and produces file-and-line-specific findings that can be fed directly into review comments, CI check annotations, or triage queues. The core job-to-be-done is shifting concurrency defect detection left—catching the class of bugs that are notoriously difficult to reproduce, diagnose, and fix after deployment.

Use this prompt when you have a concrete code change to review and you want findings scoped exclusively to concurrency risks: unsynchronized shared state mutations, lock ordering violations, missing memory barriers, goroutine or thread lifecycle bugs, channel operation deadlocks, and transaction boundary gaps. The prompt assumes the input is a well-formed diff with sufficient context lines to reason about synchronization scope. It is not a general-purpose code reviewer, style checker, or security scanner. Do not use it for reviewing documentation changes, configuration-only diffs with no concurrent execution paths, or codebases where the concurrency model is entirely external to the submitted code (e.g., a single-threaded event loop with no shared state).

Before wiring this into an automated pipeline, validate the output against a golden set of known concurrency bugs and benign changes to calibrate your false positive tolerance. The prompt produces structured severity classifications—always require human review for CRITICAL and HIGH findings that involve data corruption risks or production exposure. For lower-severity findings, you can configure auto-commenting on the PR, but maintain a feedback loop where developers can dispute or confirm findings to improve your eval dataset over time. The next section provides the copy-ready prompt template you can adapt with your language, framework, and output schema requirements.

This prompt instructs the model to act as a concurrency review specialist. It is designed to be dropped into a CI/CD pipeline, a code review agent, or a developer's local toolchain. The model receives a unified diff, a language context, and a risk tolerance level, then returns a structured JSON array of findings. Each finding includes the file path, line range, severity, a description of the potential race, and a suggested fix. The prompt enforces a strict output schema to ensure downstream systems can parse and act on the results without additional transformation.

textCopy
You are a senior systems engineer specializing in concurrency and race condition detection. Your task is to analyze the provided code diff for potential race conditions, data races, deadlock risks, and unsafe concurrent access patterns.

## INPUT
- **Diff**: [DIFF]
- **Language**: [LANGUAGE]
- **Risk Tolerance**: [RISK_LEVEL] (Options: "strict", "moderate", "permissive")
- **Context**: [CONTEXT] (Optional: architectural notes, known concurrency models, or related file summaries)

## CONSTRAINTS
- Only report findings with a clear concurrency root cause. Do not flag style issues, general code smells, or non-concurrency bugs.
- For each finding, you must cite the specific file path and line range from the diff.
- If the diff contains no concurrency issues, return an empty findings array.
- Do not hallucinate line numbers or file paths that are not present in the diff.
- For "strict" risk tolerance, flag even theoretical races with low probability. For "permissive", only flag high-confidence, high-impact races.

## OUTPUT SCHEMA
Return ONLY a valid JSON object with the following structure. Do not include any text outside the JSON object.

{
  "findings": [
    {
      "file": "string (relative path from diff)",
      "line_range": "string (e.g., 'L45-L52')",
      "severity": "string (Options: 'critical', 'high', 'medium', 'low')",
      "category": "string (Options: 'data_race', 'deadlock', 'atomicity_violation', 'ordering_violation', 'unsafe_publication', 'thread_confinement_violation', 'goroutine_leak', 'channel_deadlock', 'lock_contention', 'other')",
      "description": "string (concise explanation of the race condition and why it is unsafe)",
      "reproduction_scenario": "string (brief description of the interleaving or condition that triggers the bug)",
      "fix_suggestion": "string (concrete, actionable fix with code pattern or synchronization primitive recommendation)",
      "confidence": "number (0.0 to 1.0, indicating how confident you are that this is a real bug)"
    }
  ],
  "summary": {
    "total_findings": "number",
    "critical_count": "number",
    "high_count": "number",
    "medium_count": "number",
    "low_count": "number",
    "overall_risk_assessment": "string (one-sentence summary of the diff's concurrency risk profile)"
  }
}

## EXAMPLES
[EXAMPLES]

Analyze the diff now. Return only the JSON object.

To adapt this template, replace the square-bracket placeholders with real values before execution. The [DIFF] placeholder should contain the full unified diff text. The [LANGUAGE] field helps the model apply language-specific concurrency rules—for example, Go's goroutine and channel semantics differ from Java's synchronized blocks or Python's asyncio. The [RISK_LEVEL] parameter controls the sensitivity of the analysis: use "strict" for security-critical or financial transaction code, and "permissive" for low-risk utility scripts to reduce false positives. The optional [CONTEXT] field can include architectural notes, such as "this service uses a shared-nothing worker pool" or "all database access goes through a connection pool with serializable isolation," which helps the model avoid flagging patterns that are safe in context. The [EXAMPLES] placeholder should be replaced with one or two few-shot examples of correct input-output pairs to improve output consistency, especially for the category and severity fields.

Before integrating this prompt into a production pipeline, you must add validation and evaluation layers. Validate the output JSON against the schema to catch malformed responses. Run the prompt against a golden dataset of known concurrency bugs and confirmed clean diffs to measure false positive and false negative rates. For high-risk code paths, route findings with severity: 'critical' or confidence below 0.7 to a human reviewer. Log every invocation with the diff hash, model version, and output for auditability. Do not use this prompt as the sole gate for merge decisions on critical infrastructure or security-sensitive code paths without human review.

Integrating the PR Diff Race Condition Detection prompt into a CI/CD pipeline requires treating it as a deterministic analysis step with structured output, not a conversational assistant. The prompt expects a code diff, a target language, and a risk tolerance level as inputs, and it returns a JSON array of findings with file paths, line ranges, severity scores, and fix suggestions. The implementation harness must validate this output schema before any finding reaches a developer or blocks a merge. Because concurrency bugs are high-severity defects that can cause data corruption, the harness should default to conservative behavior: when the model returns low-confidence results, when the output fails schema validation, or when the diff exceeds the model's context window, the system must escalate for human review rather than silently passing the change.

A production-grade harness for this prompt typically includes: (1) a diff preprocessor that chunks large diffs by file or hunk and respects the model's token limit, (2) a model invocation layer with retry logic for transient failures and a timeout appropriate to the diff size, (3) a JSON schema validator that rejects malformed findings and logs schema violations for prompt debugging, (4) a severity filter that routes CRITICAL and HIGH findings to a blocking review queue while allowing LOW findings to pass with annotations, and (5) an audit log that records the prompt version, model version, input diff hash, raw output, and validation result for every run. For teams using GitHub Actions or GitLab CI, the harness can run as a required status check that posts findings as inline review comments mapped to the relevant lines. For teams with existing code review tools like Gerrit or Phabricator, the harness should emit findings in the tool's native review format.

Model choice matters here. Concurrency analysis requires precise reasoning about execution order, memory visibility, and language-specific memory models. Claude 3.5 Sonnet and GPT-4o currently produce the most reliable structured findings for this task, but they still require validation. Open-weight models like Llama 3.1 70B can work for this prompt when run with structured output constraints, but expect higher false positive rates and plan for a human triage step on all findings. Do not use this prompt with models below roughly 30B parameters for production concurrency review—smaller models lack the reasoning depth to distinguish true races from benign concurrent access patterns. Always pin the model version in your harness configuration and re-baseline your eval set when upgrading models. The eval set should include known concurrency bugs from your own codebase history plus curated examples from concurrency bug databases to measure both recall and false positive rate before deployment.