Idempotency Key Design Review Prompt

This prompt is for backend engineers and platform architects who need a structured, adversarial review of an idempotency key design before it ships to production. The job-to-be-done is not to generate a design from scratch, but to stress-test an existing proposal—whether it's a one-page RFC, a pull request description, or a set of API contract annotations. The reader should bring a concrete design artifact that specifies key generation, storage scope, expiry, and conflict resolution. The prompt acts as a rigorous reviewer, identifying gaps in duplicate detection, key collision risks, and recovery semantics that are easy to overlook during implementation.

Use this prompt when the design is detailed enough to be critiqued but not yet locked into code. Ideal inputs include a written design doc, an OpenAPI spec with Idempotency-Key header behavior defined, or a message consumer's processing logic. The prompt is most effective when the reader provides explicit constraints: the consistency guarantees of the backing store, the expected request volume, and the blast radius of a duplicate execution. Do not use this prompt for a blank-slate design request—it will produce generic advice. It is also not a substitute for formal failure mode and effects analysis (FMEA) in safety-critical systems, though it can serve as a fast pre-review before a full FMEA.

The prompt's value is in its adversarial stance. It assumes the design will fail in specific ways and forces the model to enumerate those failure modes. After receiving the review, the reader should treat each identified gap as a ticket or a design revision. The next step is to update the design artifact and re-run the review, or to escalate unresolved risks to a broader architecture review. Avoid using the output as a pass/fail gate without human judgment—some identified risks may be acceptable given the system's tolerance for duplicates, and the model may flag edge cases that are statistically irrelevant for your throughput.

This section provides a copy-ready prompt template you can adapt for reviewing idempotency key design in your own system. The template uses square-bracket placeholders for all variable inputs, making it straightforward to integrate into an AI harness, a CI pipeline, or a manual design review workflow. The prompt is structured to produce a consistent, evaluable output that flags gaps in key generation, storage scope, expiry policies, and conflict resolution before those gaps cause duplicate processing or data corruption in production.

textCopy
You are a senior backend engineer reviewing the idempotency key design for an API endpoint or message consumer. Your goal is to identify risks that could lead to duplicate processing, lost updates, or incorrect conflict resolution.

## INPUT
[DESIGN_SPECIFICATION]

## CONTEXT
[SYSTEM_CONTEXT]

## CONSTRAINTS
- Key generation must be deterministic or verifiable.
- Storage scope must be clearly bounded (per-resource, per-account, global).
- Expiry policy must account for retry windows and client timeouts.
- Conflict resolution must handle concurrent requests with the same key.
- The design must specify what happens when a key is reused after expiry.

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "summary": "One-paragraph summary of the design and its intended guarantees.",
  "key_generation_review": {
    "mechanism": "How keys are generated (client-provided, server-generated, derived).",
    "collision_risk": "Assessment of collision probability under expected load.",
    "issues": ["List of identified issues or 'None' if acceptable."]
  },
  "storage_scope_review": {
    "scope": "The scope boundary (e.g., per-account, per-resource).",
    "isolation_risk": "Risk of cross-scope key collision or leakage.",
    "issues": ["List of identified issues or 'None' if acceptable."]
  },
  "expiry_policy_review": {
    "ttl": "Time-to-live for stored keys.",
    "retry_window_alignment": "Whether the TTL covers maximum retry duration.",
    "post_expiry_behavior": "What happens when an expired key is reused.",
    "issues": ["List of identified issues or 'None' if acceptable."]
  },
  "conflict_resolution_review": {
    "strategy": "How concurrent requests with the same key are handled.",
    "first_write_wins_risk": "Risks if first-write-wins is used.",
    "last_write_wins_risk": "Risks if last-write-wins is used.",
    "issues": ["List of identified issues or 'None' if acceptable."]
  },
  "duplicate_detection_gaps": ["Scenarios where duplicates could bypass idempotency checks."],
  "key_reuse_risks": ["Risks from key reuse after expiry or across scopes."],
  "overall_risk_level": "LOW | MEDIUM | HIGH | CRITICAL",
  "recommendations": ["Prioritized list of concrete fixes."]
}

## EVALUATION CRITERIA
- Every field in the output schema must be populated.
- Issues arrays must contain specific, actionable findings, not vague warnings.
- Duplicate detection gaps must describe concrete scenarios, not hypotheticals.
- Risk level must be justified by the findings, not defaulted.
- Recommendations must be ordered by impact and feasibility.

## INSTRUCTIONS
1. Parse the design specification and system context.
2. Evaluate each dimension independently.
3. Flag any missing specification as an issue (e.g., 'Expiry policy not specified').
4. If the design is incomplete, set overall_risk_level to HIGH or CRITICAL and explain why.
5. Do not invent details not present in the input.

To adapt this template, replace [DESIGN_SPECIFICATION] with your idempotency design document, API spec, or implementation notes. Replace [SYSTEM_CONTEXT] with relevant architectural details: the database used for key storage, expected request volume, retry behavior of clients, and any cross-service dependencies. If your system uses a specific idempotency pattern (e.g., Stripe-style Idempotency-Key header, database unique constraints, or event sourcing), include that in the context. The output schema is designed to be machine-readable for automated review pipelines, but you can simplify it for manual design discussions by removing fields your team doesn't need.

Before using this prompt in production, validate that the model reliably populates all required fields and doesn't hallucinate issues for well-designed systems. Run the prompt against known-good and known-bad designs to calibrate your risk thresholds. For high-risk payment or financial systems, always route CRITICAL findings to a human reviewer before accepting the AI's assessment. The evaluation criteria in the prompt double as your test assertions: if the model returns an empty issues array for a design with no expiry policy, your eval should catch that as a false negative.

This prompt is designed to operate as a deterministic design review step, not a conversational assistant. The primary integration path is a CI/CD pipeline or a pull-request review bot that receives an API specification, message handler definition, or endpoint design document as input. The harness must enforce a strict contract: the model receives a structured [DESIGN_SPEC] and returns a structured [REVIEW_OUTPUT] that downstream tooling can parse, log, and act on. Because idempotency defects can cause duplicate charges, double-sent messages, or data corruption, the implementation must treat this review as a blocking quality gate for payment, fulfillment, and state-mutating endpoints.

Integration architecture: Wrap the prompt in a service that accepts a JSON or YAML design specification containing the endpoint's HTTP method, request schema, idempotency key source (header, body field, or generated), storage scope (per-account, per-request-type, global), key expiry policy, and conflict resolution strategy. The harness should validate the input schema before calling the model, rejecting malformed specs with a clear error rather than letting the model hallucinate a review. After the model returns the structured review, run programmatic post-validation on the output: confirm that every identified risk has a severity level, that collision probability estimates are present when key generation is described, and that the requires_human_review boolean is set. If the output fails schema validation, retry once with the validation errors appended to the prompt as [PREVIOUS_ERRORS]. If the retry also fails, escalate to a human reviewer and log the failure for prompt improvement.

Model choice and configuration: Use a model with strong structured output support and low temperature (0.1–0.2) to maximize consistency across reviews. The prompt's [OUTPUT_SCHEMA] placeholder should be populated with a JSON Schema definition that the model's native structured output feature can enforce. Avoid models that ignore system instructions under long context, since design specs can be verbose. For high-throughput CI use, consider prompt caching on the static instruction portion of the prompt to reduce latency and cost. The [DESIGN_SPEC] and [OUTPUT_SCHEMA] sections change per review, but the core evaluation criteria remain stable across invocations.

Retry, logging, and audit trail: Every review invocation must produce an immutable log entry containing the input spec hash, the model version, the full prompt (with placeholders resolved), the raw model response, the post-validation result, and the final review outcome. This audit trail is essential for debugging false positives, tracking model drift, and demonstrating review coverage during compliance audits. If the review identifies a CRITICAL severity finding, the harness should automatically add a blocking comment on the associated PR or design document and prevent merge until the finding is acknowledged or resolved. For HIGH severity findings, post a non-blocking warning with a required acknowledgement. MEDIUM and LOW findings can be logged as informational comments.

Human-in-the-loop integration: The requires_human_review field in the output schema is the primary signal for escalation. When set to true, the harness must route the review to a designated reviewer queue with the full design spec, the model's findings, and a structured approval form. Do not allow the model's review to be silently ignored. The human reviewer should be able to override severity levels, dismiss false positives with a reason, or confirm findings and request design changes. Track override decisions to identify patterns where the model consistently over- or under-flags issues, and feed those patterns back into prompt iteration and few-shot example updates.

What to avoid: Do not use this prompt in a chat interface where users can argue with the model about findings. Do not skip post-validation and assume the model's output is well-formed—schema drift is a real failure mode. Do not run this review on every commit if the design spec hasn't changed; key the review on the spec content hash to avoid redundant API costs. Finally, do not treat the model's collision probability estimates as mathematically precise; they are engineering estimates meant to trigger deeper analysis, not replace cryptographic review of key generation algorithms.