Shared State Mutation Review Prompt

This prompt is designed for a backend or systems engineer reviewing a code change that introduces or modifies access to shared mutable state. The primary job-to-be-done is to catch unsynchronized writes, read-modify-write races, and missing memory barriers before they merge into a main branch, where they become exponentially more expensive and difficult to debug. The ideal user is a developer or tech lead who understands the concurrency primitives of their language (e.g., sync.Mutex in Go, threading.Lock in Python, or std::mutex in C++) but wants a structured, automated second pair of eyes to ensure no access path was overlooked. The required context is a code diff, the language specification, and any known design intent or architectural constraints for the component under review.

You should use this prompt when the code change touches fields or data structures that are reachable from multiple goroutines, threads, or asynchronous tasks. It is particularly valuable for changes to in-memory caches, connection pools, shared configuration objects, or any state held between requests. The prompt is designed to produce a mutation safety report that maps each shared variable to its synchronization mechanism and flags any gaps. Do not use this prompt for single-threaded, purely functional transformations, or for code that only reads immutable state after initialization. It is also not a replacement for the Go race detector, tsan, or similar dynamic analysis tools; it is a static review aid that complements runtime instrumentation.

Before running this prompt, ensure the diff is isolated to the concurrency-relevant changes. Feeding an entire multi-thousand-line PR will dilute the analysis and may cause the model to miss subtle interleavings. Instead, extract the files and functions that touch shared state. The prompt expects a clear [CODE_DIFF] input and an optional [CONCURRENCY_MODEL] description (e.g., 'goroutine-per-request', 'thread pool', 'asyncio event loop'). The output is a structured report you can attach directly to a PR comment. If the report identifies a high-severity unsynchronized mutation, block the merge and request a fix; do not treat the model's output as a final security sign-off without human verification of the suggested synchronization strategy.

This prompt template is designed to be dropped into a code review pipeline or used manually by a developer before merging a pull request. It instructs the model to act as a concurrency reviewer, focusing exclusively on shared state mutation risks. The template uses square-bracket placeholders so you can inject the specific code diff, language context, and risk tolerance for your review. The output is structured as a mutation safety report, making it easy to parse in automated CI/CD checks or to read as a pre-merge checklist.

textCopy
You are a senior systems engineer specializing in concurrent and parallel programming. Your task is to review the provided code change for shared state mutation safety.

## INPUT
Code Diff:
[CODE_DIFF]

Target Language and Runtime:
[LANGUAGE_AND_RUNTIME]

## REVIEW CONSTRAINTS
- Focus exclusively on shared state mutation risks: unsynchronized writes, read-modify-write races, missing memory barriers, and incorrect use of synchronization primitives.
- Do not comment on style, naming, algorithmic complexity, or non-concurrency logic unless it directly causes a mutation bug.
- For each finding, provide a severity rating (CRITICAL, HIGH, MEDIUM, LOW) based on the likelihood and impact of data corruption or undefined behavior.
- If no shared state mutation issues are found, explicitly state that and explain why the synchronization is sufficient.

## OUTPUT SCHEMA
Return a single JSON object with the following structure:
{
  "summary": "A one-sentence overall assessment of mutation safety.",
  "findings": [
    {
      "severity": "CRITICAL|HIGH|MEDIUM|LOW",
      "location": "File path and line range or function name from the diff.",
      "category": "unsynchronized_write|read_modify_write_race|missing_barrier|incorrect_primitive|other",
      "description": "A clear, technical explanation of the race condition or mutation bug.",
      "reproduction_scenario": "A concise description of the concurrent interleaving that triggers the bug.",
      "fix_suggestion": "A specific, actionable code change or synchronization strategy to resolve the issue."
    }
  ],
  "safe_patterns_identified": ["List any correctly synchronized patterns observed in the diff."]
}

## RISK LEVEL
[RISK_LEVEL]

If RISK_LEVEL is "high", apply stricter scrutiny: flag any shared mutable state without explicit synchronization as CRITICAL, even if it appears safe under low contention.

To adapt this template, replace the placeholders before sending it to the model. [CODE_DIFF] should contain the unified diff of the code change. [LANGUAGE_AND_RUNTIME] should specify the language and memory model (e.g., "Go 1.22 with goroutines", "Java 21 with virtual threads", or "Python 3.12 with asyncio"). [RISK_LEVEL] can be set to "standard" or "high" depending on the blast radius of the component under review. For automated pipelines, parse the output JSON and fail the check if any finding has a severity of CRITICAL or HIGH. For manual review, use the safe_patterns_identified field to build team knowledge of correct concurrency patterns.

The Shared State Mutation Review Prompt is designed to operate as a pre-merge safety gate in a CI/CD pipeline or as an assistive tool within a code review platform. The prompt expects a structured diff, the target language, and a risk tolerance level as inputs. The output is a machine-readable mutation safety report that includes a severity classification, a list of unsynchronized access points, and concrete synchronization recommendations. Because concurrency defects can cause data corruption in production, the implementation harness must treat this prompt's output as a signal for human review, not as an automated merge blocker by itself. The harness should parse the structured output, attach findings to the relevant lines in the pull request, and route high-severity findings to a mandatory reviewer queue.

To wire this into an application, construct a pre-processing step that extracts the code diff from the version control system (e.g., git diff origin/main...HEAD), identifies the primary language from the changed files, and packages it alongside a risk tolerance parameter (e.g., [RISK_LEVEL: high] for financial or safety-critical paths, medium for backend services, low for internal tools). The prompt should be called with a structured output request (e.g., JSON mode or function calling) to enforce the expected schema. The harness must then validate the output against the schema: check that severity is one of the allowed enum values, that findings contain valid line references, and that synchronization_recommendations are non-empty for any finding above low severity. If validation fails, retry once with the validation error appended to the prompt as a correction hint. If the retry also fails, log the raw output and escalate to a human reviewer with a note that automated analysis was inconclusive.

For high-risk repositories (e.g., payment processing, auth systems, safety-critical control loops), the harness should enforce a human approval gate on any finding with severity: critical or severity: high. The approval gate should present the original code, the model's finding, and a required checkbox for the reviewer to confirm or dismiss each finding. Dismissed findings should be logged with the reviewer's identity and rationale for auditability. For model selection, prefer models with strong code reasoning capabilities and long context windows to handle large diffs. If the diff exceeds the model's context window, chunk the diff by file or function boundary and run the prompt on each chunk independently, then merge and deduplicate findings by file path and line range. Avoid running this prompt on generated files, vendored dependencies, or lock files; filter those out in the pre-processing step to reduce noise and token cost.

The harness should also implement basic evals before deployment. Maintain a small golden dataset of known concurrency bugs (e.g., unsynchronized map writes in Go, missing synchronized blocks in Java, unprotected shared state in Python async code) and their expected findings. Run the prompt against this dataset and measure recall (did it catch the known bug?) and precision (did it flag benign code?). A reasonable target is >90% recall on critical bugs and <20% false positive rate on clean code. If the prompt's performance degrades after a model update or prompt change, the eval harness will catch it before it reaches production. Finally, log every invocation with the prompt version, model, diff size, output summary, and review outcome. This trace data is essential for debugging false positives, tuning the risk tolerance parameter, and demonstrating review coverage to compliance auditors.