Idempotency Violation Audit Trail Generation Prompt

This prompt is designed for compliance and platform engineers who need to turn raw operation logs into a structured, evidence-backed audit trail after an idempotency violation is suspected. The ideal user has already collected relevant operation records—including timestamps, payloads, and idempotency keys—from their observability stack or database logs. The job-to-be-done is not real-time detection; it is post-incident root-cause analysis suitable for compliance reporting, postmortem documentation, or regulatory review. Use this prompt when you can answer 'yes' to all of the following: you have a set of operations sharing the same idempotency key, you suspect a duplicate side effect occurred, and you need a human-readable explanation of which operation caused the violation and why.

Do not use this prompt as a replacement for your live observability, alerting, or rate-limiting infrastructure. It does not prevent violations in real time, nor does it make automated retry or deduplication decisions. If you need a prompt that produces an immediate conflict-resolution action—such as 'use-first,' 'retry,' or 'merge'—use the Idempotency Key Conflict Resolution Prompt Template instead. If your goal is to generate idempotency wrapper logic for a non-idempotent API, the Idempotent API Call Wrapper Generation Prompt is a better fit. This audit-trail prompt is also not suitable when you lack complete operation logs; partial data will produce an incomplete or misleading audit trail. The prompt assumes you have already isolated the relevant records by idempotency key and time window.

Before running this prompt, verify that your input includes: the idempotency key under investigation, a list of operations with their timestamps and payloads, and any known side effects (e.g., duplicate database writes, double charges, conflicting state mutations). The prompt works best when you also provide your organization's idempotency policy—such as whether first-write-wins or last-write-wins semantics are expected. If your system uses a mix of idempotency guarantees across services, include that context to avoid false-positive violation flags. After generating the audit trail, always have a human reviewer validate the root-cause conclusion against the raw logs before filing a compliance report or initiating customer-impact communication.

The following prompt template is designed to be copied directly into your AI harness, orchestration layer, or evaluation framework. It accepts raw evidence of an idempotency violation—such as duplicate idempotency keys, conflicting write payloads, and timestamp logs—and produces a structured audit trail with root-cause analysis. Every square-bracket placeholder must be replaced with real data before the prompt is sent to the model. The template is model-agnostic but assumes the model supports structured output instructions.

textCopy
You are an idempotency auditor for a distributed system. Your task is to analyze evidence of a potential idempotency violation and produce a structured audit trail with root-cause analysis.

## INPUT

### Idempotency Key
[IDEMPOTENCY_KEY]

### Request Timeline (ordered by timestamp, oldest first)
[REQUEST_TIMELINE]

### Payloads for Each Request
[REQUEST_PAYLOADS]

### Observed Side Effects (database writes, API calls, state changes)
[SIDE_EFFECTS]

### System State Before First Request
[INITIAL_STATE]

### System State After All Requests
[FINAL_STATE]

### Relevant Configuration (idempotency window, lock TTL, retry policy)
[CONFIGURATION]

## OUTPUT SCHEMA

Return a JSON object with the following structure:

{
  "violation_detected": boolean,
  "violation_type": "duplicate_write" | "conflicting_write" | "stale_key_reuse" | "partial_failure_replay" | "none",
  "root_cause": {
    "category": "client_retry_without_backoff" | "key_expiration_too_short" | "lock_acquisition_failure" | "network_partition" | "clock_skew" | "missing_idempotency_check" | "other",
    "description": "string explaining the root cause in plain language",
    "evidence": ["list of specific evidence items supporting this conclusion"]
  },
  "affected_resources": [
    {
      "resource_type": "string",
      "resource_id": "string",
      "expected_state": "string describing correct state",
      "actual_state": "string describing observed state",
      "impact": "duplicate_creation" | "data_corruption" | "lost_update" | "inconsistent_state" | "none"
    }
  ],
  "timeline_analysis": [
    {
      "timestamp": "ISO8601",
      "event": "string describing what happened",
      "assessment": "expected_behavior" | "anomaly" | "root_cause_indicator"
    }
  ],
  "remediation": {
    "immediate_action": "string describing what to do now",
    "preventive_measures": ["list of changes to prevent recurrence"],
    "data_repair_required": boolean,
    "data_repair_instructions": "string or null"
  },
  "confidence": "high" | "medium" | "low",
  "uncertainty_notes": ["list of factors that reduce confidence, or empty array"]
}

## CONSTRAINTS

1. Only flag a violation if there is clear evidence of duplicate or conflicting side effects.
2. If the requests were idempotent (same payload, same result, no conflicting writes), set violation_detected to false and violation_type to "none".
3. Distinguish between duplicate writes (same payload applied twice) and conflicting writes (different payloads competing for the same resource).
4. When confidence is "low" or "medium", populate uncertainty_notes with specific reasons.
5. Do not fabricate evidence. Only reference data present in the INPUT section.
6. If the evidence is insufficient to determine root cause, set root_cause.category to "other" and explain the gap.
7. For remediation, prefer safe, reversible actions. Do not recommend destructive data fixes without explicit confirmation gates.

## EXAMPLES

[FEW_SHOT_EXAMPLES]

## RISK LEVEL

[RISK_LEVEL]

Adaptation guidance: Replace [FEW_SHOT_EXAMPLES] with 1–3 annotated examples showing correct audit trails for your system's typical violation patterns. Set [RISK_LEVEL] to high if the affected resources involve financial transactions, compliance data, or irreversible side effects—this should trigger additional human-review gates in your harness. If your system uses a non-JSON output format, replace the OUTPUT SCHEMA block with your preferred schema language but preserve the same fields. For models that struggle with complex nested JSON, consider splitting this into two prompts: first a violation-detection prompt, then a root-cause-analysis prompt that receives the detection result as input.

This prompt is designed to be called after an idempotency violation has been detected by your application's guard logic—typically a duplicate idempotency key with a different payload, a conflicting state transition, or a replay of a previously successful request. The harness should gather all relevant context before calling the model: the original request payload, the conflicting request payload, the current system state, any idempotency-key metadata (creation time, TTL, previous response signatures), and relevant logs from the time window surrounding both requests. The model's job is not to decide what to do—that belongs to your conflict-resolution logic—but to produce a structured, human-readable audit trail that explains the root cause, the sequence of events, and the evidence for each conclusion.

Wire the prompt into an asynchronous audit pipeline, not a synchronous request path. When a violation is detected, enqueue an audit-generation job with the collected context. The job calls the LLM with a moderate timeout (30–60 seconds is usually sufficient for this analytical task) and writes the resulting audit record to your compliance store. Validation is mandatory before storage: parse the model's JSON output and check that every required field is present (violation_type, timeline, root_cause, evidence_items, impact_assessment, recommendation). If the output fails schema validation, retry once with the validation errors appended to the prompt as [PREVIOUS_OUTPUT] and [VALIDATION_ERRORS]. If the second attempt also fails, flag the audit record as needs_human_review and store the raw output alongside the validation failure log—never silently drop a failed audit generation.

Model choice matters here. This is a reasoning-heavy task that benefits from models with strong analytical capabilities. GPT-4o, Claude 3.5 Sonnet, or equivalent-tier models are appropriate. Avoid smaller or faster models that may produce plausible-sounding but factually incorrect timelines. Do not use this prompt with models that lack structured output guarantees unless you add a post-processing repair step. The audit trail must be machine-parseable for downstream compliance tooling. Logging and observability are critical: record the model call latency, token usage, validation pass/fail, and retry count for every audit generation. These metrics help you detect prompt drift, model degradation, or schema changes that break the pipeline. If your compliance requirements mandate human sign-off, route all needs_human_review records and a sample of passing records (e.g., 5%) to a review queue. The audit trail itself should include a generation_metadata field with the model version, timestamp, and validation status so reviewers can assess reliability.

False-positive avoidance is the hardest part of this harness. Not every idempotency-key reuse is a violation—retries with identical payloads, clock-skew edge cases, and intentional replay for idempotent operations are all legitimate. Your pre-prompt filtering logic should suppress audit generation when the duplicate request has an identical payload hash and falls within your configured replay window. The prompt's [CONSTRAINTS] section should include your organization's specific idempotency policy (e.g., 'identical payload within 60 seconds is a retry, not a violation'). Test this boundary aggressively: create a golden dataset of known-legitimate retries and known-violations, and verify that the audit pipeline correctly suppresses the former while generating complete records for the latter. Run these regression tests on every prompt or model version change before deploying to production.