Concurrency Anti-Pattern Detection Prompt

This prompt is designed for backend and systems engineers who need to review multi-threaded code for concurrency defects before they reach production. It analyzes a code diff and produces a severity-ranked list of findings covering race conditions, deadlock risks, thread-safety violations, and improper synchronization patterns. Use this prompt in CI/CD pipelines, pre-merge review gates, or as part of a structured code review checklist. The prompt works best when the diff contains the full context of shared state access, lock acquisition, and thread coordination logic. It is not a replacement for dynamic analysis tools, stress testing, or formal verification.

The ideal input is a focused code diff where concurrency concerns are present—think changes to thread pools, shared caches, lock management, or async coordination. The prompt requires the full diff context, not just isolated lines, because concurrency bugs often span multiple files or involve implicit contracts between components. You should also provide any relevant [CONSTRAINTS], such as the language runtime's memory model guarantees or team-specific synchronization conventions. The output is a structured finding list with severity ratings, file and line references, and fix suggestions, making it directly actionable for developers.

Do not use this prompt for single-threaded code, purely algorithmic changes with no shared state, or diffs where the concurrency model is entirely external (e.g., database-managed transactions with no application-level threading). It will produce false positives on intentional lock-free patterns, well-documented benign data races in performance-critical code, and framework-managed synchronization that the prompt cannot see. Always pair this prompt with a human review step for findings marked as high severity, and consider running it alongside dynamic race detectors like ThreadSanitizer for confirmation. The prompt is a static analysis aid, not a runtime safety guarantee.

This prompt template is designed to be pasted directly into your AI system, whether that's an LLM API call, a CI/CD pipeline integration, or a code review assistant. It expects a code diff as input and produces a structured, severity-ranked list of concurrency anti-pattern findings. Replace each square-bracket placeholder with the actual values for your review context before execution. The template includes placeholders for the code diff, language-specific concurrency primitives, project-specific risk tolerances, and the desired output schema.

textCopy
You are a senior systems engineer specializing in concurrent and parallel programming. Your task is to analyze the provided code diff for concurrency anti-patterns, race conditions, deadlock risks, thread-safety violations, and improper synchronization.

## INPUT
[CODE_DIFF]

## CONTEXT
- Language and runtime: [LANGUAGE_AND_RUNTIME]
- Concurrency model in use: [CONCURRENCY_MODEL, e.g., async/await, threads with locks, actors, channels, STM]
- Shared state boundaries: [SHARED_STATE_DESCRIPTION, e.g., in-memory cache, database connection pool, file system]
- Project risk tolerance: [RISK_LEVEL, e.g., low (data integrity critical), medium, high (best-effort)]

## CONSTRAINTS
- Only report findings that are present in the diff. Do not speculate about code outside the diff unless a diff change creates a new interaction risk with existing code.
- For each finding, cite the specific file path and line range from the diff.
- If no concurrency issues are found, return an empty findings list with a brief justification.
- Do not suggest full rewrites. Suggest minimal, safe fixes.
- Flag any finding that could lead to data corruption or silent failure as CRITICAL severity.

## OUTPUT_SCHEMA
Return a single JSON object with the following structure:
{
  "summary": "string (one-sentence assessment of the diff's concurrency safety)",
  "findings": [
    {
      "id": "string (unique finding identifier, e.g., CONC-001)",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "category": "RACE_CONDITION | DEADLOCK | THREAD_SAFETY | IMPROPER_SYNCHRONIZATION | ATOMICITY_VIOLATION | ORDERING_VIOLATION | RESOURCE_LEAK | OTHER",
      "file": "string (file path from diff)",
      "line_range": "string (e.g., L45-L52)",
      "description": "string (clear explanation of the anti-pattern and why it is a problem in this context)",
      "reproduction_risk": "string (likelihood of hitting this bug in production: HIGH, MEDIUM, LOW)",
      "suggested_fix": "string (concrete, minimal code change suggestion)",
      "requires_human_review": true
    }
  ],
  "no_findings_justification": "string (only present if findings list is empty)"
}

## EXAMPLES
### Example Finding (CRITICAL)
{
  "id": "CONC-001",
  "severity": "CRITICAL",
  "category": "RACE_CONDITION",
  "file": "src/cache/user_session_cache.go",
  "line_range": "L42-L48",
  "description": "The diff introduces a check-then-act pattern on the session map without holding a lock. Between the existence check on L42 and the write on L48, another goroutine could insert a session, leading to a silent overwrite and session corruption.",
  "reproduction_risk": "MEDIUM",
  "suggested_fix": "Acquire the cache mutex before the existence check and release it after the write. Use `cache.mu.Lock()` at L41 and `cache.mu.Unlock()` at L49.",
  "requires_human_review": true
}

### Example Finding (MEDIUM)
{
  "id": "CONC-002",
  "severity": "MEDIUM",
  "category": "IMPROPER_SYNCHRONIZATION",
  "file": "src/worker/task_processor.py",
  "line_range": "L88-L95",
  "description": "The diff adds a shared `self.results` list that is appended to from multiple `asyncio.create_task` calls without any lock or queue. While CPython's GIL protects individual list operations, the order of results is non-deterministic and the size check on L95 may race with pending appends.",
  "reproduction_risk": "HIGH",
  "suggested_fix": "Replace the list with an `asyncio.Queue` and have workers `put` results. The collector should `get` with a timeout or use `task_done` tracking.",
  "requires_human_review": false
}

To adapt this template, start by replacing [CODE_DIFF] with the actual unified diff output from your version control system. The [LANGUAGE_AND_RUNTIME] and [CONCURRENCY_MODEL] fields are critical for accurate detection—a race condition in Go's goroutine model looks different from one in Python's asyncio or Java's thread pools. If your project has a known set of shared state boundaries (e.g., a specific cache instance, a database connection pool), describe them in [SHARED_STATE_DESCRIPTION] to help the model reason about interaction risks. Set [RISK_LEVEL] based on your domain: financial systems and databases should use "low" tolerance to catch more potential issues, while best-effort batch processors can use "high" to reduce noise. After generating findings, always run your eval suite against known concurrency bug patterns to measure false negative rates before trusting this prompt in a merge gate.

Integrating this prompt into an application requires treating it as a deterministic analysis step within a broader review pipeline, not a standalone chatbot. The prompt expects a structured code diff as its primary input and returns a severity-ranked list of findings. The harness must therefore handle pre-processing (diff extraction, file filtering, context window packing), post-processing (output validation, schema enforcement, deduplication), and routing (automated merge gates for low-severity findings, human review queues for critical or high-risk detections). Because concurrency bugs are notoriously difficult to reproduce and can cause data corruption, the implementation must bias toward false positives over false negatives—it is safer to flag a benign pattern for human review than to miss a deadlock risk.

Start by constructing the model request inside a function that accepts a git diff string and a risk threshold configuration. Use a model with strong code reasoning capabilities and a context window large enough to hold the full diff plus the system prompt. Set temperature=0 to maximize output determinism. The prompt returns JSON, so configure the model's response format for strict JSON mode if the provider supports it. After receiving the response, validate the output against a JSON schema that enforces the expected structure: a top-level array of finding objects, each with required fields for severity (enum: CRITICAL, HIGH, MEDIUM, LOW), file_path, line_range, anti_pattern, description, and remediation. Reject malformed responses and retry up to two times with an explicit error message appended to the prompt, such as "Your previous response failed JSON schema validation. Ensure all required fields are present and severity is one of the allowed values." If retries are exhausted, log the failure and escalate the entire diff for human review.

For production CI/CD integration, wrap the detection call in a pipeline stage that runs after linting and before merge eligibility checks. Cache the model response keyed on the diff hash to avoid re-analyzing unchanged code. Route findings by severity: CRITICAL and HIGH findings should block the merge and create a review task with the full finding context; MEDIUM findings should generate a non-blocking comment on the pull request; LOW findings can be logged for trend analysis without interrupting the developer workflow. Implement an eval harness that runs the prompt against a golden dataset of known concurrency bugs—including race conditions, deadlocks, improper synchronization, and thread-safety violations—and measures recall (did it catch the known bug?) and precision (did it flag benign code?). Track false negative rates on critical patterns as a key health metric. Finally, provide a feedback mechanism so reviewers can mark findings as false positives or confirm them, feeding that signal back into prompt refinement and eval dataset expansion.