race-conditions_skill

Overview

This skill helps you find and fix race conditions where correctness depends on timing between operations. It targets code that “works most of the time” but fails intermittently when multiple actors access or mutate shared state. Use its patterns to replace fragile check-then-act sequences with atomic operations, transactions, locks, or idempotency.

How this skill works

The skill inspects code paths that read state and later write based on that read (TOCTOU), shared mutable variables, and patterns like read-modify-write or lazy initialization. It suggests concrete remedies: atomic database updates, transactions with row locks, optimistic locking with version checks, distributed locks, and idempotency keys. It also provides test patterns to reproduce concurrency failures.

When to use it

• Multiple async operations access shared state
• Database read-then-write workflows
• Concurrent API requests that modify the same resource
• Intermittent, non-deterministic failures in production
• When order of operations matters or “it usually works” excuses appear

Best practices

• Never perform read-then-write without atomicity guarantees
• Prefer database atomic ops or transactions for state changes spanning multiple steps
• Use optimistic locking with version checks and retries where locking is too costly
• Adopt idempotency keys for repeatable external-facing operations
• Use distributed locks for complex multi-service workflows
• Write concurrent tests and load tests to expose timing bugs

Example use cases

• Account withdrawals: replace read-then-update with atomic conditional update or transaction
• Payment processing: claim an idempotency key atomically to prevent duplicates
• Order processing: acquire a distributed lock per order to ensure single-worker processing
• Counters and quotas: use atomic increments (Redis INCR, SQL atomic ops) instead of read/increment/write
• Document updates in high-concurrency apps: use optimistic locking with version field and retry