Lock-Free Code Correctness Review Prompt

This prompt is for systems engineers and performance-focused teams who need a rigorous, pre-production correctness review of lock-free and wait-free data structure implementations. It is designed to accelerate the discovery of subtle concurrency defects—specifically memory ordering violations, ABA problem vulnerabilities, and linearizability breaks—that are notoriously difficult to reproduce under test and catastrophic in production. The ideal user has already written or is reviewing a complete implementation in a language like C++, Rust, or Java, and can supply the full source code along with the target memory model (e.g., x86-TSO, ARM weak ordering). The prompt acts as a reasoning accelerator, not a replacement for formal verification tools like TLA+ or Spin, dynamic race detectors like ThreadSanitizer, or stress testing under high contention. Use it during pre-merge code review, architecture review, or when hardening a concurrent data structure that cannot afford the latency or liveness risks of lock-based synchronization.

To use this prompt effectively, you must provide the complete, unredacted implementation source code and explicitly state the target memory model. The prompt assumes the reviewer has already isolated the data structure in question and is not asking the model to search a large codebase for concurrency primitives. It works best on self-contained structures like lock-free queues, stacks, hazard pointers, epoch-based reclamation schemes, or custom atomic state machines. Do not use this prompt for general multi-threaded code that uses locks, for I/O-bound asynchronous code, or for high-level architectural patterns. The output is a structured analysis, not a binary pass/fail, so you should expect to find a ranked list of potential issues, each tied to a specific line range, a formal concern (e.g., 'missing acquire barrier on line 47'), and a suggested remediation. Because the domain is high-risk, every finding should be treated as a hypothesis to be validated with a model checker or targeted stress test before the review is closed.

Before running this prompt, ensure you have a baseline understanding of the implementation's linearization points and intended memory ordering guarantees. The prompt will challenge these assumptions, so if you cannot articulate them, the review will be less effective. After receiving the output, map each finding to a concrete test case or formal check. For memory ordering issues, construct a litmus test. For ABA problems, verify that your tag or pointer-width assumptions hold under the target architecture. For linearizability concerns, define the sequential specification and check whether every concurrent execution maps to a valid sequential history. The prompt is a starting point for this verification work, not the final word. If the review surfaces a potential data corruption bug, escalate to a human review with domain expertise in lock-free programming before any production deployment.

This template provides the core instruction set for an AI-assisted lock-free code correctness review. It is designed to be used as a system prompt or a single-turn task prompt. The placeholders in square brackets must be replaced with your specific code, language, memory model, and risk tolerance before use. The prompt instructs the model to act as a systems engineering reviewer, focusing on memory ordering, ABA problems, and linearizability—not general code style.

textCopy
You are a systems engineering reviewer specializing in lock-free and wait-free concurrent data structures. Your task is to perform a rigorous correctness review of the provided code.

## Input Code
[CODE_SNIPPET]

## Language and Memory Model
- Language: [LANGUAGE]
- Target memory model: [MEMORY_MODEL, e.g., C11, C++11, Java, Rust]
- Target architecture(s): [ARCHITECTURE, e.g., x86-64, ARM64]

## Review Constraints
- Focus exclusively on concurrency correctness: memory ordering, ABA problems, linearizability, and progress guarantees.
- Do not comment on naming, style, or general code organization unless it directly impacts concurrency correctness.
- Assume a multi-core environment with a weakly consistent memory model unless specified otherwise.
- [ADDITIONAL_CONSTRAINTS, e.g., "Ignore memory reclamation scheme for now."]

## Required Output Format
Return a JSON object with the following schema:
{
  "findings": [
    {
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "category": "MEMORY_ORDERING | ABA | LINEARIZABILITY | PROGRESS | OTHER",
      "location": "function_name or line range",
      "description": "Concise explanation of the issue.",
      "formal_reference": "Reference to a relevant formal model, paper, or language spec section.",
      "suggested_fix": "Concrete code change or design adjustment.",
      "stress_test_recommendation": "Specific scenario or tool to surface this bug."
    }
  ],
  "linearizability_assessment": "Brief verdict on whether the data structure appears linearizable.",
  "overall_risk": "LOW | MEDIUM | HIGH | CRITICAL",
  "summary": "One-paragraph summary of the review."
}

## Evaluation Criteria
- Every finding must cite a specific code location.
- Severity must be justified by potential impact (data corruption, deadlock, livelock).
- If no issues are found, return an empty findings array and state why.

To adapt this template, start by replacing [CODE_SNIPPET] with the exact function or data structure you are reviewing. Specify the [LANGUAGE] and [MEMORY_MODEL] precisely—a review for C11 atomics on ARM64 will differ significantly from one for Java on x86. Use the [ADDITIONAL_CONSTRAINTS] field to scope the review, for example, to exclude memory reclamation if you are using a known scheme like hazard pointers or epoch-based reclamation. The output schema is designed to be machine-readable for integration into CI pipelines; you can parse the JSON to block a merge if any CRITICAL findings are present. For high-risk code paths, always follow the AI review with a human expert review and runtime validation under a tool like rr or a model checker.

This prompt is designed to operate as a pre-merge correctness gate for lock-free and wait-free data structure implementations. It expects a complete source file or a focused diff containing the lock-free algorithm, plus optional context about the target memory model (e.g., x86-TSO, ARM weak ordering). The typical integration point is a CI job triggered on pull requests that touch files in paths like src/concurrent/, lockfree/, or directories flagged by a CODEOWNERS rule. Because lock-free bugs are notoriously difficult to reproduce and often survive standard unit tests, this prompt should run before human review begins, surfacing formal correctness concerns that a reviewer might miss during a standard code read.

Wire the prompt into your application by constructing a request that includes the full source code of the lock-free implementation, the target architecture's memory model, and a structured output schema. The model should be instructed to produce a JSON object with fields for correctness_verdict, memory_ordering_issues, aba_risk, linearizability_gaps, and stress_test_recommendations. Validation is critical: after receiving the model response, validate that the JSON schema matches, that all line references fall within the submitted code's line range, and that any claimed violation includes a concrete interleaving scenario. If validation fails, retry once with the validation errors appended as feedback. For high-risk code paths (e.g., memory allocators, garbage collector internals, or networking fast paths), route the validated output to a senior systems engineer for human sign-off before the PR can merge. Log every invocation with the commit SHA, model version, and validation result for auditability.

Model choice matters here. This task requires strong reasoning about memory ordering, happens-before relationships, and abstract state machines. Use a model with demonstrated strength in formal reasoning and code analysis, such as Claude 3.5 Sonnet or GPT-4o, rather than a smaller or faster model optimized for latency. Set the temperature low (0.0–0.1) to maximize deterministic, repeatable analysis. If your CI pipeline has a latency budget, consider running this as an asynchronous check that posts results back to the PR as a comment, rather than blocking the merge queue. Avoid using this prompt on partial diffs that lack the full algorithm context—lock-free correctness often depends on invariants spread across multiple functions. When in doubt, include the entire file or module. Finally, pair this prompt with a concurrency stress test runner (e.g., a tool that exercises the code under thread-sanitizer or equivalent dynamic analysis) and cross-reference the model's stress test recommendations with the runner's findings to catch issues neither approach would find alone.