{
  "instruction": "Proactively add server-side idempotency key handling with race condition protection to any POST endpoint that creates resources",
  "relevant_when": "Agent builds any POST endpoint that creates or mutates resources (orders, payments, transfers, accounts, users) — even if the task does not mention idempotency, duplicates, or retries",
  "context": "Every POST endpoint that creates a resource needs idempotency protection. This is as fundamental as input validation. Network retries and concurrent duplicate requests can create duplicate resources. The server must read an Idempotency-Key header, lock idempotency keys during processing, return 409 Conflict for concurrent duplicates, cache successful responses with TTL, never cache 5xx errors, and preserve the original HTTP status code on cached responses.",
  "sources": [
    {
      "type": "file",
      "filename": "skills/api-idempotency/SKILL.md",
      "tile": "tessl-labs/api-idempotency@0.2.0"
    }
  ],
  "checklist": [
    {
      "name": "idempotency-key-header",
      "rule": "Server reads the idempotency key from the 'Idempotency-Key' request header",
      "relevant_when": "Agent builds a POST endpoint that creates resources"
    },
    {
      "name": "lock-before-processing",
      "rule": "Server marks the idempotency key as 'processing' before executing business logic to prevent race conditions with concurrent duplicate requests",
      "relevant_when": "Agent builds a POST endpoint that creates resources"
    },
    {
      "name": "conflict-on-concurrent-duplicate",
      "rule": "Server returns 409 Conflict when a request arrives with an idempotency key that is currently being processed by another request",
      "relevant_when": "Agent builds a POST endpoint that creates resources"
    },
    {
      "name": "no-cache-5xx",
      "rule": "Server does NOT cache 5xx error responses in the idempotency store — server errors must allow the client to retry",
      "relevant_when": "Agent builds a POST endpoint that creates resources"
    },
    {
      "name": "ttl-on-cached-entries",
      "rule": "Cached idempotency entries have a TTL/expiry so they don't accumulate forever",
      "relevant_when": "Agent builds a POST endpoint that creates resources"
    },
    {
      "name": "preserve-status-code",
      "rule": "When returning a cached response, the server uses the original HTTP status code, not a hardcoded 200",
      "relevant_when": "Agent builds a POST endpoint that creates resources"
    }
  ]
}