debug-concurrency_skill

Overview

This skill helps investigate concurrency and threading problems like race conditions, deadlocks, and thread-safety violations. It provides a focused checklist and reporting style to surface root causes and hypotheses with confidence ratings. Use it to convert timing-dependent failures into actionable findings and remediation steps.

How this skill works

The skill inspects code paths for shared mutable state, lock ordering, and async/await misuse, and highlights suspicious patterns (check-then-act, missing awaits, nested locks). It maps potential circular waits, verifies guard usage for read-modify-write sequences, and assesses visibility guarantees (volatile/fences, safe publication). Findings are presented with a confidence level (High, Medium, Low, Inconclusive) and concrete evidence or reproduction notes where available.

When to use it

• Intermittent crashes or data corruption suspected to be timing-dependent
• Application hangs or severe throughput drops consistent with deadlocks
• Reports of inconsistent state when accessed by multiple threads
• After introducing new concurrency constructs or migrating to async/await
• During code reviews of performance- or safety-sensitive multithreaded paths

Best practices

• Identify and document all shared mutable state and enforce a single synchronization strategy
• Establish and follow a global lock acquisition order to prevent circular waits
• Prefer atomic operations or lock-free algorithms for small critical updates
• Ensure all async operations are awaited or explicitly handled with cancellation
• Use thread-safe collections or wrap access with consistent locking or immutability
• Add timeouts and observability around lock acquisition to aid diagnosis

Example use cases

• Analyze a server that intermittently returns stale or duplicated data under load to find race conditions
• Trace a production hang to discover a deadlock caused by inconsistent lock ordering between modules
• Audit a codebase after adding background tasks to catch missing awaits and swallowed exceptions
• Validate thread-local usage and safe publication when sharing objects across worker threads
• Assess a library for safe concurrent usage before shipping to downstream consumers