Idempotency

Deep idempotency workflow—identifying retry surfaces, idempotency keys, storage and TTL, exactly-once pitfalls, and testing duplicate delivery. Use when desi...

Security Scan

This is an instruction-only guidance workflow for designing idempotency; its requirements and instructions are coherent with that purpose and it does not request credentials, installs, or elevated persistence.

Purpose & Capability

Name/description match the content: the SKILL.md provides a structured six-stage workflow for idempotency design. The skill requests no binaries, env vars, or installs—proportionate for a documentation/workflow skill.

Instruction Scope

Instructions are limited to design guidance (identify side effects, choose keys, storage/TTL, API/worker patterns, testing). They do not direct the agent to read files, access environment variables, call external endpoints, or perform system operations.

Install Mechanism

No install spec and no code files are present, so nothing is written to disk or fetched at install time—lowest-risk installation model for an instructional skill.

Credentials

The skill declares no required environment variables, credentials, or config paths. There is no request for secrets or unrelated service access.

Persistence & Privilege

always is false and the skill does not request persistent or elevated privileges or modify agent/system configuration. It is user-invocable only.

Assessment

This skill is a safe, instruction-only workflow for designing idempotency and does not itself execute code or access secrets. Consider these points before using: (1) it is guidance only — any code or infra you build from it should be reviewed and security-tested; (2) if your agent will automatically convert these instructions into code or infra changes, review that generated output before running it; (3) for production payment/financial flows, follow the checklist here but also apply stronger audits, longer retention, and independent security reviews.

Idempotency (Deep Workflow)

Most distributed systems deliver work at least once. Idempotency makes duplicate processing safe—critical for payments, inventory, and message consumers.

When to Offer This Workflow

Trigger conditions:

• Retries on HTTP, queues, or background jobs
• Double charges, duplicate records, or “at-least-once” confusion
• Product asks for “exactly-once” semantics

Initial offer:

Use six stages: (1) identify side effects, (2) choose keys, (3) storage & scope, (4) API patterns, (5) worker patterns, (6) testing). Confirm storage (Redis, SQL) and retention window.

---

Stage 1: Identify Side Effects

Goal: Classify operations: reads vs creates vs monetary transfers vs state transitions.

Exit condition: List of mutations that must be idempotent under retries.

---

Stage 2: Choose Keys

Goal: Client-supplied Idempotency-Key header (Stripe-style) vs deterministic hash of normalized payload—trade UX vs collision risk.

---

Stage 3: Storage & Scope

Goal: Store key → outcome or result reference with TTL covering retry window; scope keys per tenant/user when needed.

---

Stage 4: API Patterns

Goal: Same key + same body → same outcome; reject or conflict if same key with different body.

---

Stage 5: Worker Patterns

Goal: Natural unique constraints in DB; dedupe table keyed by event_id or business idempotency key for consumers.

---

Stage 6: Testing

Goal: Chaos or integration tests that deliver duplicate messages; property tests for key behavior.

---

Final Review Checklist

• Mutating paths classified
• Key strategy and scope documented
• Storage, TTL, conflict rules defined
• HTTP and async consumers aligned
• Duplicate delivery tests

Tips for Effective Guidance

• True exactly-once end-to-end is rare—design for at-least-once + idempotent effects.
• Pair with message-queues and rest-best-practices for HTTP idempotency keys.

Handling Deviations

• Financial flows: require stronger audit and longer key retention.