Deadlock Potential Analysis Prompt

This prompt is designed for systems engineers and platform teams reviewing code changes that introduce or modify lock acquisition patterns. Its primary job is to detect circular wait conditions, lock ordering violations, and nested lock risks across multiple resources before they reach production. The ideal user is a developer or reviewer who understands the codebase's concurrency model but needs a structured, automated second pair of eyes to trace lock dependencies that are difficult to hold in memory. The required context is a code diff or a set of code paths that explicitly show lock acquisition and release sequences. Without this, the analysis is speculative and unreliable.

Do not use this prompt for general code review, style checks, or performance profiling. It is not a substitute for runtime lock tracing tools like lockstat or perf lock, nor can it reason about lock contention under real load. Its value is in static, pre-merge analysis of lock ordering. The prompt works best when the input is scoped to a single, coherent change—a pull request, a patch file, or a specific module. Providing an entire repository will dilute the analysis and increase the risk of hallucinated lock graphs. The output is a dependency graph and a ranked risk list, not a definitive proof of deadlock. Every high-severity finding must be validated against runtime lock tracing data when available, and a human reviewer must confirm the feasibility of the reported circular wait before blocking a merge.

Before using this prompt, ensure you have a clear, text-based representation of the lock acquisitions in the target code. If the code uses implicit locking through language constructs or frameworks, you must first extract and document the effective lock paths. After receiving the output, treat the ranked risk list as a triage guide: investigate high-severity items first, attempt to reproduce the deadlock scenario in a test harness, and use the generated dependency graph to communicate the risk to the team. Avoid the temptation to accept the model's reasoning without verification, especially for complex lock hierarchies where the model may miss context from outside the provided diff.

This prompt template is designed to be dropped into a code review harness, a CI/CD pipeline, or a developer's local analysis workflow. It expects a code diff, a language specification, and optional runtime lock tracing data. The output is a structured dependency graph and a ranked list of deadlock risks, making it suitable for automated gating decisions or manual review triage.

textCopy
You are a systems concurrency analyst. Your task is to review the provided code change for deadlock potential. Analyze lock acquisition patterns, identify circular wait conditions, detect lock ordering violations, and flag nested lock risks across multiple resources.

## INPUTS
[CODE_DIFF]
[LANGUAGE]
[OPTIONAL_RUNTIME_LOCK_TRACES]

## ANALYSIS STEPS
1. Parse the code diff to identify all lock acquisition and release sites. Note the lock type (mutex, read/write lock, semaphore, etc.) and the resource it protects.
2. For each function or code path modified, construct an ordered list of locks acquired.
3. Compare lock acquisition orders across all paths to detect inconsistencies. Flag any path where lock A is acquired before lock B in one location but after lock B in another.
4. Identify nested lock acquisitions. For each nested pair, check if the inner lock is ever acquired independently elsewhere, creating a potential circular wait.
5. If [OPTIONAL_RUNTIME_LOCK_TRACES] are provided, cross-reference static findings with observed lock wait events to confirm or refute deadlock risks.
6. For each detected risk, assess whether the deadlock is theoretically possible, practically reachable under concurrent execution, or confirmed by runtime data.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "analysis_metadata": {
    "language": "string",
    "total_locks_identified": "integer",
    "total_risk_findings": "integer",
    "runtime_data_used": "boolean"
  },
  "lock_dependency_graph": {
    "nodes": [{"id": "string", "type": "lock_type", "resource": "string"}],
    "edges": [{"from": "string", "to": "string", "code_path": "string"}]
  },
  "findings": [
    {
      "id": "string",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "type": "CIRCULAR_WAIT | LOCK_ORDERING_VIOLATION | NESTED_LOCK_RISK | CONFIRMED_DEADLOCK",
      "description": "string",
      "involved_locks": ["string"],
      "code_locations": [{"file": "string", "line": "integer", "function": "string"}],
      "reproduction_scenario": "string",
      "runtime_confirmation": "CONFIRMED | SUGGESTIVE | NONE | NOT_APPLICABLE",
      "fix_suggestion": "string"
    }
  ],
  "overall_risk_score": "CRITICAL | HIGH | MEDIUM | LOW",
  "requires_human_review": "boolean"
}

## CONSTRAINTS
- Do not flag lock acquisitions that are always serialized by an external guarantee (e.g., single-threaded initialization).
- Distinguish between read locks and write locks when the language supports them. Multiple read locks do not constitute a deadlock risk.
- If the code uses a lock-free data structure, note it but do not apply lock-based analysis.
- If runtime traces are provided and contradict a static finding, prioritize the runtime evidence and explain the discrepancy.
- Mark `requires_human_review` as true if any finding is CRITICAL or HIGH severity, or if the analysis confidence is low due to incomplete information.

To adapt this template, replace the square-bracket placeholders with your actual inputs. The [CODE_DIFF] should be a unified diff or a complete file with changes highlighted. The [LANGUAGE] field should be a standard language identifier (e.g., go, java, python, rust, c++). The [OPTIONAL_RUNTIME_LOCK_TRACES] can be omitted entirely if no runtime data is available; the model will skip cross-referencing. For production use, wrap this prompt in a harness that validates the output JSON against the schema before accepting results. If the model returns malformed JSON, retry with a stricter format instruction or fall back to a repair prompt. Always log the full prompt and response for auditability, especially when the analysis gates a merge decision.

The Deadlock Potential Analysis Prompt is designed to be integrated into a pre-merge code review pipeline, not as a standalone chat tool. The primary integration point is a CI/CD system (e.g., GitHub Actions, GitLab CI) that triggers on pull requests containing changes to files matching lock-acquisition patterns. The application harness should extract the relevant diff, identify the programming language, and inject any available runtime lock-tracing data (e.g., from a testing or staging environment) into the [RUNTIME_TRACE] placeholder. Without this runtime data, the analysis is purely static and carries a higher false-positive rate for complex, dynamic dispatch scenarios.

The harness must enforce a strict validation loop on the model's output. The expected output is a JSON object containing a dependency_graph (nodes and edges representing lock acquisition order) and a risk_list (ranked findings with severity, code locations, and reproduction scenarios). After receiving the model response, the application must validate the JSON schema, confirm that every file path and line number in the output exists in the current diff, and discard any finding that references code outside the change set. If validation fails, the harness should retry the prompt once with the validation errors appended to the [CONSTRAINTS] field. If the retry also fails, the analysis should be flagged for human review rather than silently posting an incomplete or misleading report. For high-risk repositories, implement a mandatory human approval gate: any finding with a severity of critical or high must block the merge and require a senior engineer to acknowledge the risk.

Model choice matters for this workflow. The prompt requires strong reasoning over code structure and temporal ordering, making it a good fit for models with large context windows and advanced code understanding, such as Claude 3.5 Sonnet or GPT-4o. Avoid using smaller, faster models for this task unless you have a robust fine-tuning dataset of deadlock examples, as they tend to hallucinate circular dependencies in linear code. Log every analysis result, including the full prompt, model response, and validation outcome, to an observability platform. This creates an audit trail for false-positive tuning and allows you to compare static analysis findings against production deadlock incidents over time. Do not use this prompt as the sole gate for deployment; it is a detection tool that complements, but does not replace, stress testing and runtime deadlock detection.