amey-thakur/ai-skills/deadlock-analysis
Claude Code and agent skill by amey-thakur/ai-skills
- community
Checking that the SKILL.md file is still in the repository.
Find why threads are stuck forever by dumping their state and building the wait-for graph that reveals the lock cycle. Use when a program hangs with no progress and no crash, or throughput drops to zero while CPU sits idle.
Install
npx vskill@latest install amey-thakur/ai-skills/deadlock-analysisSKILL.md
The same SKILL.md was published earlier as amey-thakur/ai-skills/deadlock-analysis.
Deadlock analysis
A deadlock is a cycle of waiting: thread A holds lock 1 and wants lock 2 while thread B holds lock 2 and wants lock 1, and neither will ever move. The process is not crashed, it is frozen, which fools you into looking for a slow operation instead of a stuck one. The cycle is always visible in a thread dump if you know how to read the waits.
Method
- Confirm it is a deadlock, not slowness. Idle CPU with zero progress
for minutes points at blocking, not computation. A busy CPU spinning forever is a livelock or infinite loop, a different bug. Check that threads are parked in a wait state, not running hot.
- Capture a thread dump at the moment of the hang.
jstack <pid>or
kill -3 on the JVM, py-spy dump --pid for Python, dlv or SIGQUIT for Go (which prints all goroutine stacks), gdb -p <pid> then thread apply all bt for native. Take two dumps a few seconds apart: if the stacks are identical, nothing is moving.
- Read who holds what and who waits for what. A good dump names it
directly: the JVM prints "Found one Java-level deadlock" with the lock ids, "waiting to lock <0x...>" versus "locked <0x...>". For each blocked thread, write down the lock it holds and the lock it wants.
- Draw the wait-for graph and find the cycle. Nodes are threads, an
edge runs from a thread to the thread holding the lock it waits on. A cycle in that graph is the deadlock, and the locks on the cycle are the ones acquired in conflicting order. Two locks is the common case; the graph scales to more.
- Fix with a global lock ordering. Pick a total order for the locks on
the cycle (by address, by name, by a fixed rank) and make every code path acquire them in that order. If ordering is impractical, use a single coarser lock, a tryLock with timeout and backoff, or lock-free structures. Consistent order breaks every cycle by construction.
- Prove it under contention. Run the path that hung under many threads
for an extended loop. A deadlock that reproduced in minutes should now run indefinitely. Static tools help catch regressions: -Xlint, jcstress, or Clang's -Wthread-safety annotations flag out-of-order acquisition.
Signals
- Do two thread dumps taken seconds apart show identical, parked stacks?
- Can you trace a closed cycle through the wait-for graph?
- Does every path that touches those locks now take them in one fixed order?
Boundaries
This covers mutual-exclusion deadlocks between threads in one process. Distributed deadlocks across services, database lock waits, and connection-pool exhaustion wear the same mask but resolve with transaction timeouts, lock ordering at the database, or pool sizing, not with a thread dump.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/debugging/deadlock-analysis/SKILL.md
Popularity
- Repository stars
- 10
- Repository forks
- 2
- 7-day trend score
- 17
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/amey-thakur/ai-skills/deadlock-analysis)