Optimistic Concurrency Control Failure Recovery Prompt

This prompt is for backend engineers and AI reliability engineers who need to recover from version-mismatch errors when multiple agents or processes attempt to write to shared state concurrently. The job-to-be-done is producing a safe merge or retry instruction when an optimistic concurrency control (OCC) failure occurs—typically signaled by a version conflict, ETag mismatch, or conditional-write rejection. The ideal user has access to the failed write payload, the current state of the resource, and conflict metadata such as version numbers, timestamps, and the fields that diverged. Without this context, the prompt cannot reason about what changed and what should be preserved.

Use this prompt when your application layer detects a write conflict and you need the model to decide whether to merge, retry with an updated version, or escalate for human review. It is appropriate for workflows where the cost of a lost update is high—such as updating a customer record, modifying a shared configuration, or writing to a feature flag store—and where a naive last-writer-wins policy would silently discard important changes. The prompt works best when paired with a harness that extracts the conflicting versions, presents them in a structured diff format, and validates that the model's proposed resolution does not introduce regressions or violate invariants.

Do not use this prompt for simple key-value stores where last-writer-wins is acceptable, or for append-only logs where conflicts cannot occur by design. It is also the wrong tool when the conflict resolution logic is deterministic and can be encoded in application code—such as incrementing a counter or merging a set—because the model introduces latency and nondeterminism without benefit. For high-throughput systems, prefer a CRDT-based merge or a deterministic merge function, and reserve this prompt for cases where semantic judgment is required, such as reconciling conflicting edits to a natural-language field or a structured configuration block. If the conflict involves regulated data or safety-critical state, always route the resolution through a human approval step after the model produces its recommendation.

This prompt template is designed to be wired into a backend service's error-handling path. When a database write is rejected because the expected version number does not match the current state, the application should invoke this prompt with the failed payload, the current conflicting state, and relevant metadata. The model's job is not to execute the merge itself, but to produce a structured, auditable recovery instruction that the application can validate and optionally execute.

textCopy
You are a concurrency conflict resolver for a backend system. Your task is to analyze a failed optimistic write and produce a safe recovery instruction.

## CONTEXT
- [CONFLICT_METADATA]
- [BUSINESS_RULES]

## INPUT
- Failed Write Payload: [FAILED_PAYLOAD]
- Expected Version: [EXPECTED_VERSION]
- Current State (Version [CURRENT_VERSION]): [CURRENT_STATE]

## CONSTRAINTS
- [CONSTRAINTS]

## OUTPUT_SCHEMA
Produce a JSON object with the following fields:
- "decision": "retry" | "merge" | "abort" | "escalate"
- "reasoning": A concise explanation of the decision.
- "merge_strategy": If the decision is "merge", describe the field-level resolution rules (e.g., "take latest timestamp for status, sum amounts for balance"). Otherwise, set to null.
- "retry_payload": If the decision is "retry", provide the corrected payload with the updated version. Otherwise, set to null.
- "risk_notes": Any risks of lost updates, double-spending, or invariant violations.

## EXAMPLES
[EXAMPLES]

Analyze the conflict and produce the recovery instruction.

To adapt this template, replace the placeholders with concrete data from your application's error context. [CONFLICT_METADATA] should include the resource ID, the rejected version, and the current version. [BUSINESS_RULES] are critical for safe merges; for example, 'never decrement a balance below zero' or 'status transitions are monotonic.' The [EXAMPLES] placeholder should be populated with 2-3 few-shot demonstrations of correct merge and retry decisions for your specific domain. For high-risk workflows, such as financial ledgers, the [CONSTRAINTS] field must explicitly forbid destructive merges and require human review for any decision other than 'abort' or 'escalate.' After receiving the model's output, validate the JSON schema and check that the retry_payload version matches the current_state version before any automated retry.

This prompt is designed to sit inside a state-mutation pipeline that uses versioned writes. The application layer should intercept a version-mismatch error (e.g., HTTP 409 Conflict, a database conditional-update failure, or an Etag precondition failure) and immediately construct the prompt context from three sources: the failed write payload the caller attempted to persist, the current state of the resource as read after the conflict, and any conflict metadata the data store provides (version vectors, timestamps, or changed-field indicators). Do not call this prompt for every write—only when the harness detects a concrete concurrency conflict. The prompt is not a substitute for a deterministic merge function when one exists; use it when the merge logic is non-trivial, domain-specific, or requires semantic reconciliation that cannot be expressed as a simple last-writer-wins or field-level union.

Wire the prompt into a retry-with-review loop. After the model returns a merge proposal, the harness must validate the output before applying it. Check that the proposed next state includes a correct version reference (e.g., the version field matches the current state's version, not the failed write's stale version). Validate that no fields present in the current state were silently dropped unless the model explicitly marked them as intentionally removed. If the merge proposal fails structural validation, increment a retry counter and re-invoke the prompt with the validation error appended to the conflict metadata. Set a hard retry budget—typically 2–3 attempts—and escalate to a human review queue if the budget is exhausted. Log every attempt, the merge proposal, and the final outcome for auditability. For high-risk domains such as financial ledgers or clinical records, require human approval on all merge proposals before the write is committed, regardless of validation success.

Choose a model with strong instruction-following and structured-output capabilities. The prompt expects a JSON output schema with fields for merge_decision (one of apply_proposed, merge, discard_proposed, or escalate), merged_state, conflict_resolution_notes, and lost_update_risk. Enforce this schema using structured-output APIs (e.g., OpenAI's response_format with a JSON Schema, or equivalent tool-use constraints) rather than relying on post-hoc parsing. For the eval harness, maintain a golden dataset of conflict scenarios with known-safe merge outcomes. Each eval run should check that the model never produces a merge that silently drops a concurrent update (lost-update detection), never fabricates field values not present in either the failed payload or the current state, and correctly escalates when the conflict is semantically unresolvable. Run these evals on every prompt version change and on model upgrades. The next step is to integrate the validated merge output into your write path, ensuring the conditional write uses the version from the merge proposal and that a second conflict triggers escalation rather than an infinite retry loop.