Exactly-Once Semantics Implementation Audit Prompt

This prompt is designed for platform engineers and backend architects who need to audit a distributed pipeline for exactly-once processing guarantees. The job-to-be-done is a rigorous, evidence-based review of idempotency mechanisms, transaction boundaries, deduplication stores, and failure recovery paths. Use it when you are designing a new critical path, troubleshooting an unexplained duplicate or missing record in production, or conducting a pre-release resilience review. The ideal user has access to system design documents, code for producers and consumers, and configuration for message brokers and databases.

Do not use this prompt for a superficial checklist or a generic system health review. It is not a replacement for load testing, chaos engineering, or formal verification. The prompt requires concrete technical context—such as the idempotency key strategy, the database isolation level, and the message broker's delivery semantics—to produce a useful audit. Without this context, the output will be speculative and low-value. The audit is also not a substitute for a full failure mode and effects analysis (FMEA), though it can serve as a focused input to one.

Before running this prompt, gather the [PIPELINE_ARCHITECTURE] description, the [IDEMPOTENCY_MECHANISM] details, the [TRANSACTION_BOUNDARIES] specification, and the [DEDUPLICATION_STORE] configuration. The prompt will produce a structured audit with identified gaps, test scenarios for duplicate detection failures and partial commits, and a severity-ranked list of risks. After receiving the output, you should validate any critical findings against the actual code and configuration, and use the generated test scenarios as a starting point for your resilience testing suite.

This prompt template is designed to produce a structured audit of exactly-once processing guarantees across a distributed pipeline. It forces the model to examine idempotency mechanisms, transaction boundaries, deduplication stores, and failure recovery semantics before declaring correctness. Use this template when you need a systematic review of a proposed or existing implementation—not when you need a quick yes/no answer. The template expects detailed technical context about your pipeline architecture, message formats, and storage systems. Without that context, the audit will be shallow and potentially misleading.

textCopy
You are an expert distributed systems auditor specializing in exactly-once semantics. Your task is to produce a rigorous audit of the exactly-once processing guarantees described in the provided system design.

## INPUT
[SYSTEM_DESIGN]

## CONSTRAINTS
- Do not assume correctness. Verify every claim against the described mechanisms.
- Flag any missing mechanism, ambiguous behavior, or unverified assumption.
- Distinguish between at-least-once, at-most-once, and exactly-once guarantees at each processing stage.
- Consider failure modes including: producer crashes, consumer crashes, network partitions, storage failures, and clock skew.
- [ADDITIONAL_CONSTRAINTS]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "audit_summary": {
    "overall_assessment": "EXACTLY_ONCE | AT_LEAST_ONCE | AT_MOST_ONCE | UNCLEAR",
    "confidence": "HIGH | MEDIUM | LOW",
    "critical_gaps_found": <integer>,
    "recommendations_count": <integer>
  },
  "pipeline_stages": [
    {
      "stage_name": "string",
      "guarantee_level": "EXACTLY_ONCE | AT_LEAST_ONCE | AT_MOST_ONCE | UNCLEAR",
      "idempotency_mechanism": "string | null",
      "deduplication_store": "string | null",
      "transaction_boundary": "string | null",
      "failure_recovery_behavior": "string",
      "gaps": ["string"],
      "evidence": "string"
    }
  ],
  "cross_cutting_concerns": [
    {
      "concern": "string",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "affected_stages": ["string"],
      "description": "string",
      "remediation": "string"
    }
  ],
  "test_scenarios": [
    {
      "scenario_name": "string",
      "description": "string",
      "expected_behavior": "string",
      "potential_failure_mode": "string"
    }
  ],
  "recommendations": [
    {
      "priority": "CRITICAL | HIGH | MEDIUM | LOW",
      "recommendation": "string",
      "rationale": "string"
    }
  ]
}

## EVALUATION CRITERIA
- Every pipeline stage must be assessed for idempotency, deduplication, and transaction boundaries.
- Any stage lacking a deduplication store must be flagged as at-least-once unless another mechanism is proven.
- Test scenarios must include: duplicate producer sends, consumer crash mid-processing, storage failure during deduplication write, and partial commit states.
- If the system design is incomplete, state what is missing rather than guessing.

## RISK LEVEL
[RISK_LEVEL]

## ADDITIONAL CONTEXT
[ADDITIONAL_CONTEXT]

To adapt this template, replace the square-bracket placeholders with your actual system details. The [SYSTEM_DESIGN] placeholder should contain a complete description of your pipeline: message producers, brokers, consumers, storage systems, transaction boundaries, and any idempotency or deduplication mechanisms already in place. Use [ADDITIONAL_CONSTRAINTS] to inject domain-specific rules, such as regulatory requirements or latency budgets. The [RISK_LEVEL] field should be set to HIGH, MEDIUM, or LOW to calibrate the depth of scrutiny—high-risk systems demand exhaustive analysis, while lower-risk pipelines may accept a faster review. The [ADDITIONAL_CONTEXT] field is for any supplementary information that doesn't fit neatly into the system design, such as team experience, operational history, or known incident patterns. After copying the template, validate that your input data is complete enough to produce a meaningful audit. An incomplete system description will produce an audit full of assumptions, which is worse than no audit at all.

Before using this prompt in production, build a validation harness that checks the output JSON against the declared schema. Reject any response that omits required fields or contains invalid enum values. For high-risk systems, route the audit output to a human reviewer before accepting any architectural decisions based on it. Store each audit result alongside the system design version it was generated from, so you can track how guarantees evolve as the architecture changes. Finally, treat the generated test scenarios as a starting point for your own chaos engineering experiments—the model can suggest failure modes, but only real testing confirms whether your system actually tolerates them.

This prompt is designed to be run against a structured specification document, a set of architecture decision records (ADRs), or a codebase analysis report. The primary integration point is a design review gateway—a step in your CI/CD or RFC process where a system design is submitted, and this prompt produces an audit before implementation proceeds. The prompt expects a detailed description of the processing pipeline, including the message broker, consumer groups, transaction boundaries, and deduplication store. If your input is a codebase instead of a document, you must first run a code-exploration agent to generate a structured summary of the relevant components, or use a RAG pipeline to retrieve the relevant source files and configuration.

Validation and retries: The output is a structured JSON audit. You must validate the JSON schema on receipt. If the model returns malformed JSON, use a repair prompt that provides the raw output, the expected schema, and the instruction to fix only structural errors. For high-risk pipelines (financial transactions, inventory mutations, medical records), the audit output must be reviewed by a human before any implementation changes are approved. The prompt includes a [RISK_LEVEL] parameter; when set to high, the harness should automatically route the output to a review queue and block the pipeline until sign-off is received. Model choice: Use a model with strong reasoning capabilities (e.g., GPT-4o, Claude 3.5 Sonnet) because this task requires multi-step deduction across transaction boundaries, failure modes, and state-machine analysis. Smaller models often miss subtle partial-commit states or incorrectly assume idempotency coverage.

Logging and observability: Log the full prompt input, model output, validation result, and reviewer decision. This creates an audit trail that proves exactly-once semantics were reviewed before deployment—critical for compliance in regulated environments. Tool use: If the prompt needs to verify claims against a live system (e.g., checking if a deduplication table has a TTL), wire it into a tool that queries the database schema or configuration store. The prompt's [TOOLS] placeholder accepts a list of available tool signatures. Next steps: After the audit is approved, feed the identified gaps into your task tracker as implementation tickets. Re-run the prompt after implementation to verify the gaps were closed. Avoid running this prompt on incomplete design documents—the model will hallucinate plausible but incorrect assumptions about missing components.