agentleFS
MicrosoftKnown publishermicrosoft/win-dev-skills/plugins/windbg/skills/windbg-kernel-lock-deadlock-triage/SKILL.md

windbg-kernel-lock-deadlock-triage

Skill469 starsChanged 36 days agoMITView on GitHub

Use when kernel threads block on driver synchronization or Verifier reports a lock-order violation; build an owner/waiter graph. Not for treating every watchdog stop as a deadlock or listing every lock type with !locks.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Load windbg-diagnostic-method first: if it is not already loaded in this conversation, and apply it throughout for evidence ranking, …

    line 8
  2. Distinctive:

    Use kernel thread stacks, synchronization-object evidence, and Driver Verifier deadlock records.

    line 15
  3. Distinctive:

    If Driver Verifier deadlock detection was enabled and the dump contains its records:

    line 38
  4. Very specific:

    If blocked on an IRP use windbg-kernel-irp-lifecycle-triage.

    line 67
  5. Distinctive:

    Check the required IRQL, permitted waits, lock hierarchy, and object lifetime.

    line 74
  6. Distinctive:

    Use a consistent acquisition hierarchy, reduce lock scope, avoid unbounded waits/cross-component callbacks while holding resources, and …

    line 81
  7. Distinctive:

    Do not replace a lock or add a timeout without preserving invariants and completion/cancellation semantics.

    line 84
  8. Distinctive:

    Test concurrency, callbacks, teardown, and the same applicable Verifier checks.

    line 90
  9. Very specific:

    Follow FEEDBACK.md and report reviewed, sanitized feedback to WinDbg-Feedback.

    line 102

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Kernel Lock and Deadlock Triage

Load windbg-diagnostic-method first if it is not already loaded in this conversation, and apply it throughout for evidence ranking, hypothesis testing, confidence calibration, independent review, and report validation. This skill adds the bug-family-specific commands and evidence requirements.

Detection

Use kernel thread stacks, synchronization-object evidence, and Driver Verifier deadlock records. A watchdog bugcheck can indicate CPU/DPC progress failures, not necessarily a lock cycle. Establish the actual waits before choosing this workflow.

Workflow

1. Gather owners and waiters

!locks
!thread <ethread-address>
!process 0 7

!locks enumerates ERESOURCE information. It is not an inventory of all pushlocks, fast mutexes, and spinlocks. For other primitives use documented primitive-specific inspection when available, matching symbols for your driver, its source, and recorded acquisition evidence. State missing owners explicitly.

2. Inspect recorded lock-order evidence

If Driver Verifier deadlock detection was enabled and the dump contains its records:

!deadlock 1

Inspect the reported resources, acquisition sequence, and threads. Verifier can detect an unsafe ordering before a persistent deadlock actually forms. An empty result without the required verification/history is not proof that the lock order is safe. For Verifier setup/safety use windbg-kernel-verifier-triage.

3. Build and test the graph

thread A holds resource X -> waits for Y owned by B
thread B holds resource Y -> waits for X owned by A

Show evidence for every edge. Check recursive acquisition, callbacks under locks, I/O completion dependencies, and destruction/rundown paths.

Distinguish:

  • A demonstrated cycle or Verifier-reported order inversion.
  • Contention where a runnable owner can progress.
  • Starvation or an owner blocked on a separate request.
  • Spin/IRQL problems, which are not necessarily blocking-lock deadlocks.

If blocked on an IRP use windbg-kernel-irp-lifecycle-triage; if a chain crosses into a user-mode COM/RPC operation use windbg-user-wait-chain-analysis. Carry the proven graph edges into the next skill rather than starting the same investigation again.

4. Localize the driver path

Identify which call path held one resource while acquiring/waiting for another. Check the required IRQL, permitted waits, lock hierarchy, and object lifetime. Private Windows implementation layouts are not prerequisites; if public symbols and captured state cannot recover an edge, request appropriate authorized evidence and keep the conclusion provisional.

Fix patterns

Use a consistent acquisition hierarchy, reduce lock scope, avoid unbounded waits/cross-component callbacks while holding resources, and move potentially blocking destruction outside locks where the ownership design permits. Do not replace a lock or add a timeout without preserving invariants and completion/cancellation semantics.

Validation

Record the graph, supported cycle/inversion, and offending driver path. Test concurrency, callbacks, teardown, and the same applicable Verifier checks. Separate a demonstrated fix from an unproven contention hypothesis.

References

Feedback

Follow FEEDBACK.md and report reviewed, sanitized feedback to WinDbg-Feedback. Include windbg-kernel-lock-deadlock-triage and the package version from plugin.json; no automatic dump, lock-history transcript, or driver-source upload.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.