Skip to content

skillCode quality

Concurrency Bug Analysis

Finds races, deadlocks and lost updates by mapping shared state and lock order, then proposes the narrowest lock, queue or atomic operation that fixes them.

npx workspacetemplates add concurrency-bug-analysis --tool claude-code

Writes 1 file to .claude/skills/concurrency-bug-analysis/

.claude/skills/concurrency-bug-analysis/SKILL.md32 lines · 1.9 KBFile
---
name: concurrency-bug-analysis
description: Finds races, deadlocks and lost updates by mapping shared state and lock order, then proposes the narrowest lock, queue or atomic operation that fixes them.
---

# Concurrency bug analysis

Reason first, then reproduce, then fix. A fix without a reproduction is a guess.

## Steps

1. Build the map. List every piece of shared mutable state (globals, singletons, caches, rows, files) and every thread, task, worker or request path that touches it. Mark each access as read or write.
2. Look for the usual shapes:
   - Check-then-act: `if (!exists) create`, `if (stock > 0) stock--`.
   - Read-modify-write without atomicity: `count = count + 1`, or a SQL `SELECT` then `UPDATE`.
   - Lock-order inversion: A takes lock 1 then 2, B takes 2 then 1.
   - Holding a lock across I/O or a callback.
   - Publishing an object before it is fully built; unsynchronized lazy init.
   - Shared iteration while another path mutates the collection.
3. Write the interleaving that breaks it as numbered steps for two actors. If you cannot write the interleaving, the finding is not proven; drop it.
4. Reproduce with a stress test: many parallel callers in a loop, a forced yield or sleep between the check and the act, or the language's race detector (`go test -race`, ThreadSanitizer, or the equivalent).
5. Choose the narrowest fix, in this order: remove the sharing; use an atomic or database operation (`UPDATE ... SET n = n + 1`, compare-and-swap, unique constraint); a queue that serializes writes; a lock held for the shortest code, with one global lock order.
6. Re-run the stress test many times and confirm the failure is gone.

## Rules

- Never add `sleep` or retries as the fix.
- Do not hold locks while calling unknown code.

## Report

The interleaving, the evidence, the fix, the test, and the remaining shared state you could not prove safe.

What it does

Concurrency bugs resist the usual debugging: they vanish under a debugger and show up on a busy Tuesday. This skill reasons about them on paper first, listing what is shared, who writes it and what ordering the code assumes.

The fix it proposes is the smallest one that closes the window, with a test or stress loop that makes the failure reproducible. It avoids the reflex of adding a global lock.

Example

you › Inventory sometimes goes negative under load. Find the race.

agent › Check-then-act in reserve(): src/stock.ts:31 reads stock then writes stock - qty in a separate query, so two requests both pass the check. Reproduced with 50 parallel calls: 9 oversold. Fix: single `UPDATE stock SET qty = qty - $1 WHERE id = $2 AND qty >= $1`, treating 0 rows as out of stock. 200 stress runs, no failures.

Questions

Why not just add a lock around the function?
A broad lock hides the bug but serializes everything and can create deadlocks. An atomic database operation or a short, ordered lock fixes the cause at lower cost.
Does it work for async code in one thread?
Yes. Awaiting between a check and a write lets other tasks interleave, so the same analysis applies.
  • API Deprecation Handling

    SkillCode quality

    Free
  • Code Duplication Removal

    SkillCode quality

    Free
  • Code Smell Detection

    SkillCode quality

    Free
  • Cyclomatic Complexity Reduction

    SkillCode quality

    Free