reverse-skills-max: initial public release (restored, redacted, hardened)
This commit is contained in:
baradok609hecl1pq6qi
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"name": "windbg",
|
||||
"version": "1.0.0",
|
||||
"description": "WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.",
|
||||
"author": {
|
||||
"name": "Microsoft",
|
||||
"url": "https://github.com/microsoft/WinDbg-Feedback"
|
||||
},
|
||||
"homepage": "https://github.com/microsoft/WinDbg-Feedback",
|
||||
"repository": "https://github.com/microsoft/win-dev-skills",
|
||||
"keywords": [
|
||||
"windows",
|
||||
"windbg",
|
||||
"debugging",
|
||||
"crash",
|
||||
"hang",
|
||||
"memory",
|
||||
"umdf",
|
||||
"drivers"
|
||||
]
|
||||
}
|
||||
12
vendor-new/win-dev-skills/plugins/windbg/CHANGELOG.md
Normal file
12
vendor-new/win-dev-skills/plugins/windbg/CHANGELOG.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# Changelog
|
||||
|
||||
## 1.0.0 - Initial contribution
|
||||
|
||||
- Included the curated debugging skill inventory in `skills.json`.
|
||||
- Added the shared `windbg-diagnostic-method` skill with deterministic report
|
||||
validation and the contrarian agent required for the complete workflow.
|
||||
- Kept the runtime package limited to the inventory in `skills.json`.
|
||||
- Removed owner and metadata fields from every skill header.
|
||||
- Added public WinDbg-Feedback guidance.
|
||||
- Added explicit diagnosis/fix confidence separation and fix-path coverage
|
||||
calibration for the contrarian review gate.
|
||||
66
vendor-new/win-dev-skills/plugins/windbg/FEEDBACK.md
Normal file
66
vendor-new/win-dev-skills/plugins/windbg/FEEDBACK.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# Public feedback
|
||||
|
||||
Feedback destination:
|
||||
[microsoft/WinDbg-Feedback issues](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
|
||||
Use this procedure for feedback about these debugging skills or WinDbg. For
|
||||
general application-debugging help, consult that repository's
|
||||
[support guidance](https://github.com/microsoft/WinDbg-Feedback/blob/master/SUPPORT.md).
|
||||
|
||||
## Procedure for assistants
|
||||
|
||||
1. Collect the skill ID, public package version, the user's own verdict, and
|
||||
what was confusing, incorrect, or missing. Do not invent the user's verdict
|
||||
or claim a diagnosis is confirmed when it is not.
|
||||
2. Check for an existing relevant issue before drafting a new one, when search
|
||||
is available. Do not add labels or choose assignees without authorization.
|
||||
3. Prepare a minimal sanitized title and body using the template below. Exclude
|
||||
secrets, customer data, usernames, private paths, hostnames, proprietary source,
|
||||
internal links, memory contents, and complete diagnostic transcripts.
|
||||
4. Show the exact draft and state that it will be publicly visible in
|
||||
`microsoft/WinDbg-Feedback`. Obtain explicit approval before posting. Re-review
|
||||
material changes to the approved draft. Declining or cancelling creates no
|
||||
issue.
|
||||
5. Use the host's supported GitHub issue-creation tool when available and
|
||||
authorized. Otherwise provide the approved text and
|
||||
[new-issue page](https://github.com/microsoft/WinDbg-Feedback/issues/new)
|
||||
for manual submission. Tool/authentication failure is an explicit failure,
|
||||
not a successful submission or an excuse to silently use another destination.
|
||||
6. Return a confirmed issue URL only after creation succeeds. Never fabricate a
|
||||
receipt. For manual submission, say that the issue has not been submitted yet.
|
||||
|
||||
Do not automatically attach or upload dumps, CABs, ETLs, TTD recordings, source
|
||||
code, or diagnosis files. Permission to share an artifact privately does not
|
||||
authorize public disclosure. Do not put unreviewed diagnostic text into
|
||||
issue-URL query parameters. Report sensitive vulnerabilities through the approved
|
||||
private security reporting channel, not this public feedback flow.
|
||||
|
||||
## Suggested issue template
|
||||
|
||||
Title: `[Debugging skills][<skill-id>] <short feedback summary>`
|
||||
|
||||
```markdown
|
||||
### Skill and version
|
||||
Plugin: windbg
|
||||
Package version: <public version from plugin.json>
|
||||
Skill: <skill-id>
|
||||
|
||||
### Category and verdict
|
||||
Category: <incorrect guidance / missing coverage / unclear instructions / packaging / positive feedback>
|
||||
My verdict: <helpful / partly helpful / incorrect / unclear>
|
||||
|
||||
### Expected behavior
|
||||
<What the guidance should help me do>
|
||||
|
||||
### Observed behavior
|
||||
<Relevant step and minimal sanitized evidence; label uncertain conclusions>
|
||||
|
||||
### Environment
|
||||
<Relevant WinDbg version, Windows version, architecture; omit identifying information>
|
||||
|
||||
### Suggested improvement
|
||||
<Optional correction, missing explanation, or synthetic repro>
|
||||
```
|
||||
|
||||
Only include information the user approves for public disclosure. There is no
|
||||
bundled uploader, credential store, private share, or notification service.
|
||||
371
vendor-new/win-dev-skills/plugins/windbg/README.md
Normal file
371
vendor-new/win-dev-skills/plugins/windbg/README.md
Normal file
@@ -0,0 +1,371 @@
|
||||
# Debugging Diagnostician
|
||||
|
||||
A WinDbg-centric crash, hang, memory, and driver diagnosis playbook for
|
||||
developers who build software **for Windows**: native applications, services,
|
||||
third-party user-mode drivers (including UMDF), and kernel-mode drivers.
|
||||
|
||||
This public edition combines focused user-mode and kernel-mode debugging skills,
|
||||
a shared `windbg-diagnostic-method` skill with deterministic report validation,
|
||||
and a contrarian reviewer. It does not require private Windows source, symbols,
|
||||
portals, or feedback services. The goal is to shorten the path from a dump,
|
||||
trace, or stack to a supported root cause and candidate fix without forcing a
|
||||
pattern match.
|
||||
|
||||
## Install
|
||||
|
||||
Install from the catalog:
|
||||
|
||||
```powershell
|
||||
copilot plugin marketplace add microsoft/win-dev-skills
|
||||
copilot plugin install windbg@win-dev-skills
|
||||
```
|
||||
|
||||
Claude Code and Codex use their normal marketplace install commands described in
|
||||
the repository README. Skills work independently on skill-capable hosts. The
|
||||
optional `diagnostician` agent is provided for GitHub Copilot only; it is not
|
||||
required to use the skills on other hosts.
|
||||
|
||||
### Claude Code with the WinDbg MCP server
|
||||
|
||||
For Claude Code to use the WinDbg MCP server without its debugger operations
|
||||
being blocked, open **WinDbg > Settings > MCP** and clear both of these options:
|
||||
|
||||
- **Enable Cross Prompt Injection Mitigation**
|
||||
- **Enable Secure Mode for MCP Server**
|
||||
|
||||
If secure mode was already activated, restart WinDbg after clearing it. WinDbg
|
||||
keeps secure mode active until restart.
|
||||
|
||||
> [!WARNING]
|
||||
> These settings are security protections. Disable them only for a trusted
|
||||
> debugging session with dumps, command output, source, and prompts you are
|
||||
> authorized to expose to Claude Code. Re-enable the protections when the
|
||||
> unrestricted MCP operations are no longer required.
|
||||
|
||||
The plugin does not bundle an MCP server; this configuration applies to the
|
||||
separately installed WinDbg MCP integration.
|
||||
|
||||
For a pre-merge local review, use your host's supported local plugin loading
|
||||
mechanism on this directory. Do not assume the catalog commands can fetch an
|
||||
unmerged contribution.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Invoke the optional Copilot agent with a dump, stack, trace, or failure summary:
|
||||
|
||||
```text
|
||||
Use the diagnostician agent to analyze this crash stack, bugcheck, hang
|
||||
symptom, or debugger output: <paste the evidence here>
|
||||
```
|
||||
|
||||
You can also invoke a skill directly on a skill-capable host:
|
||||
|
||||
```text
|
||||
Use windbg-user-heap-corruption-investigation on the dump open in WinDbg.
|
||||
Establish what evidence is available, distinguish competing explanations, and
|
||||
state what remains unproven.
|
||||
```
|
||||
|
||||
The plugin supplies diagnostic guidance, not a debugger connection. Use an
|
||||
existing, approved WinDbg integration if available, or inspect the suggested
|
||||
commands yourself and provide their output. The assistant must never claim to
|
||||
have executed commands or accessed source/dumps that it cannot actually use.
|
||||
|
||||
## Short prompt — root cause a dump in the debugger
|
||||
|
||||
Use this when an authorized debugger integration is connected to a dump and you
|
||||
want the diagnostician to drive the investigation:
|
||||
|
||||
```text
|
||||
Root cause the dump in the debugger. Let the diagnostician orchestrate the
|
||||
debugging session, use the available source tools for my own code, and follow
|
||||
the standard five-phase protocol. Treat pattern matches as hypotheses, test
|
||||
alternatives, and state missing evidence.
|
||||
```
|
||||
|
||||
This prompt does three things:
|
||||
|
||||
1. Names the diagnostician as the investigation orchestrator while preserving
|
||||
user approval for state-changing operations.
|
||||
2. Grounds source lookups in tools and repositories the user is authorized to
|
||||
access, rather than assuming private operating-system source.
|
||||
3. Invokes the full observe-hypothesize-test-evaluate-conclude/pivot protocol.
|
||||
|
||||
## Full investigation prompt
|
||||
|
||||
Use this prompt when you want a durable diagnosis with explicit structure:
|
||||
|
||||
````text
|
||||
Use the diagnostician agent to run the full investigation workflow on the dump,
|
||||
trace, stack, or debugger session in this conversation.
|
||||
|
||||
1. Apply the five-phase diagnostic method. Treat matching skills as hypothesis
|
||||
generators, not proof.
|
||||
2. If filesystem access is available, write the complete diagnosis to
|
||||
./.diagnoses/<short-id>/<yyyyMMdd-HHmmss>.md. Otherwise return the same
|
||||
structure in the response and state that no file was written.
|
||||
3. Include these H2 sections in order:
|
||||
Analysis, Root Cause, Fix, Reasoning Chain, Alternatives Considered,
|
||||
Trigger Verification, Mermaid, Contrarian Verdict, and JSON Output Contract Summary.
|
||||
4. Trigger Verification must be a table separating observed evidence,
|
||||
contradictory evidence, missing evidence, and the validation needed for the
|
||||
proposed fix.
|
||||
5. Mermaid must be a VS Code-renderable sequenceDiagram with at least two
|
||||
participants when a sequence/ownership flow is relevant. If a sequence
|
||||
diagram would misrepresent the failure, explain why and use the closest
|
||||
evidence-preserving Mermaid diagram.
|
||||
6. Do not finalize a root cause while a plausible alternative remains untested.
|
||||
If evidence is insufficient, use diagnosis_status
|
||||
"candidate-pending-verification" and name the next evidence required.
|
||||
````
|
||||
|
||||
The package includes a public contrarian sub-agent and the shared
|
||||
`windbg-diagnostic-method` skill. The full prompt invokes both gates; when a
|
||||
host cannot run a separate sub-agent, the agent must state that limitation
|
||||
rather than substitute inline self-review.
|
||||
|
||||
## How It Works
|
||||
|
||||
Every diagnosis follows a five-phase **hypothesis-test-pivot** cycle:
|
||||
|
||||
1. **OBSERVE** — Parse dump/trace type, architecture, stack, code, registers,
|
||||
resource state, and evidence limitations.
|
||||
2. **HYPOTHESIZE** — Form a specific, testable primary theory and plausible
|
||||
alternatives.
|
||||
3. **TEST** — Identify and collect evidence that would confirm or deny each
|
||||
hypothesis.
|
||||
4. **EVALUATE** — Separate what is supported, contradicted, inferred, or still
|
||||
missing.
|
||||
5. **CONCLUDE or PIVOT** — State the supported cause and verification plan, or
|
||||
revise the hypothesis when evidence does not support it.
|
||||
|
||||
The agent may choose one of three reasoning paths:
|
||||
|
||||
| Path | Indicative confidence | Behavior |
|
||||
|---|---:|---|
|
||||
| **Fast** | ≥80% | A strong known pattern is treated as a hypothesis, required evidence is verified, and alternatives are checked before conclusion. |
|
||||
| **Validate** | 40–79% | The leading pattern and at least one plausible alternative go through the full cycle. |
|
||||
| **Full-reasoning** | <40% or no match | Start from observations, construct alternatives, and preserve explicit uncertainty. |
|
||||
|
||||
Confidence is an explanation aid, not measured probability. A high initial
|
||||
match does not bypass evidence or permit blaming a module solely because it
|
||||
appears on the stack.
|
||||
|
||||
## Invocation Modes
|
||||
|
||||
### Mode 1: Interactive Debugging
|
||||
|
||||
Use the diagnostician agent with a dump, trace, stack, or live debugger context.
|
||||
The agent drives the five-phase investigation and produces a structured
|
||||
diagnosis.
|
||||
State-changing actions—enabling Verifier/Page Heap, changing configuration,
|
||||
capturing traces, or forcing a crash—require explicit user authorization.
|
||||
|
||||
### Mode 2: Triage Enrichment
|
||||
|
||||
Provide failure metadata, stack text, or a partial investigation without a live
|
||||
debugger. The diagnostician identifies likely skill routes, missing evidence,
|
||||
and concrete next commands. It must not imply that proposed commands were
|
||||
executed or that a routing match proves the root cause.
|
||||
|
||||
### Mode 3: Public Feedback
|
||||
|
||||
When the user asks to submit WinDbg or debugging-skill feedback, follow
|
||||
`FEEDBACK.md`. Draft a minimal sanitized public issue for
|
||||
[microsoft/WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues),
|
||||
show the exact title/body and public destination, and obtain explicit approval
|
||||
before posting with a supported GitHub issue tool. Without such a tool, provide
|
||||
the approved text and new-issue page for manual submission.
|
||||
|
||||
This public mode does not collect an eval corpus and never automatically uploads
|
||||
dumps, TTD recordings, ETLs, CABs, private source, or full transcripts.
|
||||
|
||||
## Input
|
||||
|
||||
The agent accepts natural language. A structured handoff can use this shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"case_id": "optional public or local identifier",
|
||||
"bug_type": "crash|hang|leak|bugcheck|unknown",
|
||||
"stack_frames": ["frame1", "frame2"],
|
||||
"error_code": "0xC0000005",
|
||||
"exception_type": "ACCESS_VIOLATION",
|
||||
"target": "application|service|user-mode-driver|kernel-mode-driver",
|
||||
"additional_context": "authorized, sanitized context and evidence limits"
|
||||
}
|
||||
```
|
||||
|
||||
Do not put secrets, customer data, private paths, or memory contents into a
|
||||
public feedback issue. Diagnostic input can remain local to the approved session.
|
||||
|
||||
## Output
|
||||
|
||||
```json
|
||||
{
|
||||
"diagnosis_status": "final|candidate-pending-verification",
|
||||
"routing_path": "fast|validate|full-reasoning",
|
||||
"analysis": {
|
||||
"summary": "what the evidence shows",
|
||||
"evidence": ["direct evidence with command/source"],
|
||||
"reasoning": ["why evidence supports or contradicts each hypothesis"],
|
||||
"uncertainty": ["what remains unproven"]
|
||||
},
|
||||
"reasoning_chain": [
|
||||
"OBSERVE: ...",
|
||||
"HYPOTHESIZE: ...",
|
||||
"TEST: ...",
|
||||
"EVALUATE: ...",
|
||||
"CONCLUDE or PIVOT: ..."
|
||||
],
|
||||
"root_cause": "supported cause, or null while pending verification",
|
||||
"fix": "candidate change and verification plan, or null",
|
||||
"confidence": 0.82,
|
||||
"fix_confidence": 0.68,
|
||||
"fix_code_path_coverage": "read-this-session|read-prior-session|symbol-or-disassembly|pattern-only|not-read",
|
||||
"matched_skill": "a skill name, or null",
|
||||
"alternatives_considered": ["alternative and evidence"],
|
||||
"trigger_verification": "verified|partially-verified|not-verified",
|
||||
"contrarian_review": "ACCEPTED|CHALLENGED with notes",
|
||||
"contrarian_loopback": false
|
||||
}
|
||||
```
|
||||
|
||||
## Knowledge Base
|
||||
|
||||
### Debugging Skills (`skills/`)
|
||||
|
||||
The authoritative skill inventory is `skills.json`.
|
||||
|
||||
#### User-mode: applications, services, and user-mode drivers (including UMDF)
|
||||
|
||||
| Skill | Use it for |
|
||||
|---|---|
|
||||
| `windbg-user-exception-triage` | Establish exception context and classify native process crashes, including user-mode driver host failures. |
|
||||
| `windbg-user-heap-corruption-investigation` | Investigate use-after-free, double-free, and overruns in applications, services, or user-mode driver hosts. |
|
||||
| `windbg-user-wait-chain-analysis` | Follow application, service, user-mode driver, COM/RPC, and process waits to a supported blocker or cycle. |
|
||||
| `windbg-user-ttd-reverse-debugging-triage` | Find earlier writes, frees, and calls in a recorded user-mode process, including a user-mode driver host. |
|
||||
| `windbg-user-virtual-memory-exhaustion` | Separate address-space pressure, fragmentation, commit pressure, and applicable limits. |
|
||||
| `windbg-user-mutex-held-across-co-await` | Investigate thread-affine locks held across coroutine suspension in user-mode components. |
|
||||
|
||||
#### Kernel-mode: external kernel-mode driver developers
|
||||
|
||||
| Skill | Use it for |
|
||||
|---|---|
|
||||
| `windbg-kernel-bugcheck-triage` | Decode bugchecks and recover original exception or trap context. |
|
||||
| `windbg-kernel-verifier-triage` | Interpret Driver Verifier violations and available I/O verification evidence. |
|
||||
| `windbg-kernel-irp-lifecycle-triage` | Investigate outstanding I/O, completion/cancel ownership, and power IRPs. |
|
||||
| `windbg-kernel-lock-deadlock-triage` | Build supported kernel owner/waiter graphs and investigate lock-order inversions. |
|
||||
|
||||
Trap-frame and exception-context recovery are included in
|
||||
`windbg-kernel-bugcheck-triage`, not additional skills. Feedback guidance and
|
||||
the optional agent are support content rather than bug-family skills.
|
||||
|
||||
No specialized C++ thrown-object or XAML stowed-exception decoder is included. `windbg-user-exception-triage` documents the boundary and continues evidence-led reasoning instead of dispatching to absent skills. This is native debugging guidance, not a managed .NET diagnostics package.
|
||||
|
||||
### Eight Hypothesis Templates
|
||||
|
||||
These are starting hypotheses, never automatic diagnoses:
|
||||
|
||||
| Template | Signal | Required discipline |
|
||||
|---|---|---|
|
||||
| Race Condition | Race, TOCTOU, concurrent access | Identify shared state, competing paths, ordering, and a reproducible interleaving. |
|
||||
| Lock Ordering | Deadlock, inversion, ABBA | Establish every owner/waiter edge and the conflicting acquisition order. |
|
||||
| RPC Under Lock | Cross-process call while holding a lock | Prove the held resource and callback/server dependency; a synchronous COM call alone is not a deadlock. |
|
||||
| Timer/Callback Race | Callback during teardown | Prove registration, cancellation/rundown, object lifetime, and which path can still execute. |
|
||||
| Cross-Apartment Dependency | Wrong-thread/apartment failure or STA hang | Establish apartment contracts, marshaling, pumping/reentrancy, and object agility. |
|
||||
| Reentrant Lock Acquisition | Re-entry while state/lock is held | Identify the reentrant edge and whether the primitive or invariant permits it. |
|
||||
| Regression | Failure after a version/build change | Compare evidence and code/config changes; correlation with a build is not causation. |
|
||||
| Platform/Instruction | Architecture, alignment, or illegal instruction | Verify target architecture, decoded bytes, CPU/ABI requirement, and binary identity. |
|
||||
|
||||
### Shared method skill
|
||||
|
||||
| Skill | Purpose |
|
||||
|---|---|
|
||||
| `windbg-diagnostic-method` | Applies the shared evidence, reasoning, confidence, review, reporting, and deterministic validation method. |
|
||||
|
||||
## File Inventory
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `plugin.json` | Portable Agent Plugins manifest for Copilot and Codex. |
|
||||
| `.claude-plugin/plugin.json` | Claude Code plugin manifest with matching name/version. |
|
||||
| `com.github.copilot/agents/diagnostician.agent.md` | Main Copilot diagnostician agent. |
|
||||
| `com.github.copilot/agents/contrarian.agent.md` | Independent adversarial review agent. |
|
||||
| `skills/<skill-name>/SKILL.md` | Bug-family skills and the shared diagnostic method. |
|
||||
| `skills.json` | Exact public skill inventory and user-mode/kernel-mode grouping. |
|
||||
| `FEEDBACK.md` | Public, reviewed WinDbg-Feedback issue procedure and issue template. |
|
||||
| `CHANGELOG.md` | Public package changes. |
|
||||
| `README.md` | Package usage, methodology, scope, and support contract. |
|
||||
|
||||
There is no bundled MCP server, uploader, credential store, notification
|
||||
service, or feedback automation. The shared method is explicitly inventoried
|
||||
and is not a bug-family-specific skill.
|
||||
|
||||
### Authoring and calibration material not bundled
|
||||
|
||||
The runtime package contains only the files listed above. Case data, test
|
||||
artifacts, evaluation datasets, source links, and authoring records are not
|
||||
distributed with the plugin. The published skills retain actionable workflows
|
||||
and public references.
|
||||
|
||||
## Requirements and Limits
|
||||
|
||||
- WinDbg and an appropriate process, user-mode driver host, or kernel dump (or
|
||||
an authorized live debugging session).
|
||||
- Public Windows symbols and matching binaries/PDBs for your own modules.
|
||||
Missing dump pages or symbols limit conclusions and must be reported.
|
||||
- TTD requires an actual authorized user-mode recording; it cannot replay
|
||||
kernel execution or reconstruct history from an ordinary dump.
|
||||
- Application Verifier/Page Heap and Driver Verifier are optional repro tools.
|
||||
Use them on suitable test systems; their overhead or deliberate failures can
|
||||
disrupt workloads. Record settings and restore them after the investigation.
|
||||
- Commands and data-model features vary across WinDbg/extension versions. Check
|
||||
installed help and public documentation rather than inventing unsupported
|
||||
syntax or private structure layouts.
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Diagnosis is read-only by default:** Produce a diagnosis; do not modify code,
|
||||
bug state, machine settings, or uploaded artifacts unless the user explicitly
|
||||
authorizes that action.
|
||||
- **Feedback submission is explicit and public:** Show the exact sanitized
|
||||
issue payload and destination before posting. No submission occurs on decline,
|
||||
cancellation, missing tooling, or authentication failure.
|
||||
- **Reasoning-first:** Investigate and test; do not conclude from keyword or
|
||||
stack-pattern matching alone.
|
||||
- **Conservative:** Unknown or candidate-pending-verification is valid. State
|
||||
missing pages, symbols, histories, or cross-process evidence.
|
||||
- **Evidence provenance:** Cite debugger output, the user's authorized source,
|
||||
a controlled reproduction, or public documentation. Do not require private
|
||||
Windows source or portals.
|
||||
- **Windows-scoped:** Native Windows application/service debugging, user-mode
|
||||
drivers including UMDF, and kernel-mode drivers.
|
||||
|
||||
## Contact, Support, and Feedback
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Issue and feedback tracking** | [microsoft/WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues) |
|
||||
| **Public feedback procedure** | [`FEEDBACK.md`](FEEDBACK.md) |
|
||||
| **General debugging support guidance** | [WinDbg-Feedback SUPPORT.md](https://github.com/microsoft/WinDbg-Feedback/blob/master/SUPPORT.md) |
|
||||
| **Sensitive security reports** | Follow the repository SECURITY policy; do not post vulnerabilities publicly. |
|
||||
|
||||
The package uses the public WinDbg-Feedback repository rather than personal
|
||||
contacts or non-public destinations. WinDbg-Feedback is for feedback, not a
|
||||
guarantee of individual application-debugging support. Publication reviewers
|
||||
should confirm ongoing skill-feedback triage with that repository's maintainers.
|
||||
|
||||
Never automatically upload dumps, TTD traces, ETLs, CABs, private source, or
|
||||
full diagnostic transcripts. Review and approve a minimal sanitized issue
|
||||
before posting.
|
||||
|
||||
## Versioning and Contribution
|
||||
|
||||
The public inventory is `skills.json`. Change the package version in both plugin
|
||||
manifests and all three catalog entries when publishing changed content. Update
|
||||
the plugin CHANGELOG and keep exactly the intended skill inventory.
|
||||
|
||||
Do not mark an update as shipped until its public contribution or release is
|
||||
confirmed. Future changes must be reviewed in this repository and preserve
|
||||
independent improvements made to the published plugin.
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
name: contrarian
|
||||
description: Independently challenges a proposed Diagnostician root cause, trigger evidence, alternatives, confidence, fix strength, and diagram consistency.
|
||||
tools: []
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Contrarian
|
||||
|
||||
You are the **Contrarian** in an adversarial root-cause pipeline for Windows crash, hang, and leak diagnoses. You are invoked by the diagnostician agent AFTER it has completed Phase 5 (Conclude) and produced a candidate root cause + fix + mermaid diagram.
|
||||
|
||||
## Input
|
||||
|
||||
You receive **the diagnostician's complete output**, including:
|
||||
- The reasoning chain (all 5 phases verbatim)
|
||||
- The list of alternative hypotheses considered and the evidence cited to rule each one out
|
||||
- The trigger-verification record (which trigger was suspected, what evidence verifies it, or UNVERIFIED)
|
||||
- The proposed fix, `fix_confidence`, and `fix_code_path_coverage` declaration
|
||||
- The diagnosis confidence value and its calibration rationale
|
||||
- The mermaid sequence diagram
|
||||
|
||||
You do **NOT** see:
|
||||
- The original dump file or live debug session
|
||||
- The ability to run any debugger commands or read any source
|
||||
|
||||
You work ONLY from the diagnostician's output text.
|
||||
|
||||
## Mission
|
||||
|
||||
Argue the **OPPOSITE** of the diagnostician's primary root cause. Find what is **WRONG** with the reasoning, the trigger verification, or the fix. You are not here to be agreeable — you are here to prevent false confidence from reaching the bug fix or the customer.
|
||||
|
||||
|
||||
## Attack Vectors
|
||||
|
||||
Systematically evaluate the diagnostician's output for these failure modes:
|
||||
|
||||
### 1. Symptom-vs-Cause Confusion
|
||||
|
||||
The diagnostician may have anchored on the **observable symptom** rather than the **root invariant violation**. Common patterns:
|
||||
- "The pointer was stack-allocated" — but is that actually possible given the lifetime of the structure on this code path? Did the diagnostician verify it, or assume it because the address looked stack-shaped?
|
||||
- "The structure was freed" — but freed by whom, and was free actually reachable on this code path?
|
||||
- "The lock was not held" — but did the diagnostician verify the locking discipline by reading the producer/consumer code, or only the faulting frame?
|
||||
|
||||
If the root cause restates the crash mode in mechanism terms but does not name the **invariant the code violates**, flag it.
|
||||
|
||||
### 2. Trigger Not Verified by Direct Evidence
|
||||
|
||||
The diagnostician's `trigger_verification` field claims either VERIFIED (with cited evidence) or UNVERIFIED. Audit this:
|
||||
- If VERIFIED: Did the diagnostician actually read the source/disassembly cited, or paraphrase a structure they expect to exist? Look for suspiciously round line numbers, code that "must" have a certain shape, or quotes that read like model knowledge rather than file content.
|
||||
- If the trigger is "the producer's wait has a timeout escape" — was the wait actually inspected, or was it assumed because the symptom requires it?
|
||||
- If the trigger is "callback fires after the producer signals" — was the signal-then-callback ordering proven, or inferred from the crash being in that callback?
|
||||
|
||||
A diagnosis whose entire fix matrix depends on an unverified trigger is a diagnosis without a fix. Call it out.
|
||||
|
||||
### 3. Single-Stack Reasoning / Missing Threads
|
||||
|
||||
Many Windows crashes are cross-thread races. Did the diagnostician examine ONLY the faulting thread's stack, or did they reason about the producer/owner thread as well?
|
||||
- If the bug is a UAF, who freed the memory? Did the diagnostician identify the freeing thread and prove its sequencing?
|
||||
- If the bug is a hang, who holds the lock/signal/handle that the faulting thread is waiting on? Was that thread's state inspected?
|
||||
- If the bug is a corruption, who wrote the bad bytes? Was the writer identified, or assumed?
|
||||
|
||||
A complete diagnosis names BOTH parties to the race. A partial diagnosis names only the victim.
|
||||
|
||||
### 4. Fix Targets Reproducer, Not Invariant
|
||||
|
||||
The proposed fix may eliminate the **specific repro path** without restoring the **broken invariant**. Common patterns:
|
||||
- "Add a null check" — does this fix the use-after-free, or does it just prevent the crash on the dereference while leaving the lifetime bug intact?
|
||||
- "Increase the timeout" — does this fix the synchronization bug, or just hide it?
|
||||
- "Initialize the field to zero" — does this fix the missing initialization, or just prevent the assertion on this code path?
|
||||
- "Hold the lock longer" — does this restore the locking invariant, or just narrow the race window?
|
||||
|
||||
Ask: if a different caller hits the same invariant violation through a different code path, does the proposed fix protect them? If not, the fix is reproducer-targeted, not invariant-restoring.
|
||||
|
||||
### 5. Fix-Confidence Calibration Violation
|
||||
|
||||
The diagnostician's fix confidence must comply with this calibration:
|
||||
- ≥0.9 requires `fix_code_path_coverage = read-this-session`
|
||||
- 0.7–0.89 allows `read-prior-session` or `symbol-or-disassembly`
|
||||
- 0.5–0.69 covers incomplete symbol/disassembly evidence or `pattern-only`
|
||||
- <0.5 uses `not-read` and is candidate-only
|
||||
|
||||
Audit: does the declared `fix_confidence` match the declared coverage? If the diagnostician claims 0.9 but admits the fix was inferred from a related skill rather than read in this session, the calibration is wrong.
|
||||
|
||||
### 6. Mermaid Diagram Lies
|
||||
|
||||
The mermaid diagram should match the reasoning chain. Common drift:
|
||||
- The diagram shows actors that are not named in the reasoning chain
|
||||
- The diagram skips the trigger condition in favor of the symptom
|
||||
- The diagram uses prose that contradicts the verified evidence
|
||||
- The diagram glosses over an unverified step with `Note over` instead of an explicit message
|
||||
|
||||
If the diagram is more confident than the prose, the diagram is wrong.
|
||||
|
||||
## Counter-Hypothesis Requirement
|
||||
|
||||
You **must** produce a counter-hypothesis: an alternative root cause that does NOT rely on the diagnostician's primary mechanism. The counter-hypothesis should:
|
||||
- Be plausible given the symptoms described in the diagnostician's OBSERVE phase
|
||||
- Use a fundamentally different mechanism than the diagnostician's primary hypothesis
|
||||
- Identify what direct evidence (from the dump or source) would distinguish it from the primary hypothesis
|
||||
- Include a probability and confidence estimate
|
||||
|
||||
## Honesty Clause
|
||||
|
||||
If the diagnostician's analysis is genuinely strong — trigger verified, alternatives ruled out with cited evidence, fix targets the invariant, confidence calibrated — say so explicitly. Forced contrarianism without substance is worse than useless. A real ACCEPTED verdict is more valuable than a manufactured CHALLENGE.
|
||||
|
||||
## Isolation Constraints
|
||||
|
||||
- You have **NO tools**. Do not attempt to call any tools.
|
||||
- You work ONLY from the diagnostician's output text.
|
||||
- Do NOT fabricate source code references, function names, or technical details. If the diagnostician didn't cite it, you don't know it.
|
||||
- Your value comes from logical and structural analysis of the diagnosis, not from inventing alternative evidence.
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure your response with these exact sections:
|
||||
|
||||
```
|
||||
## Verdict: ACCEPTED | CHALLENGED
|
||||
|
||||
[One-sentence summary]
|
||||
|
||||
## Counter-Hypothesis (probability: X.XX, confidence: X.XX)
|
||||
|
||||
[An alternative root cause that does NOT use the diagnostician's primary mechanism. Include the distinguishing evidence that would resolve it.]
|
||||
|
||||
## Critique of Diagnostician
|
||||
|
||||
### Symptom-vs-Cause Assessment
|
||||
[Does the root cause name the invariant, or restate the symptom?]
|
||||
|
||||
### Trigger Verification Audit
|
||||
[Was the trigger verified by cited evidence, or assumed? Quote the claim being audited.]
|
||||
|
||||
### Cross-Thread Completeness
|
||||
[Did the diagnosis name both parties to the race / both ends of the lifetime?]
|
||||
|
||||
### Fix-Targets-Invariant Assessment
|
||||
[Does the fix restore the invariant, or close the reproducer?]
|
||||
|
||||
### Confidence Calibration Audit
|
||||
[Does the declared confidence match the declared code-path coverage per the calibration table?]
|
||||
|
||||
### Mermaid Diagram Consistency
|
||||
[Does the diagram match the reasoning chain and verified evidence?]
|
||||
|
||||
## Fabrication Check
|
||||
|
||||
[List each specific technical claim from the diagnostician and grade as VERIFIED (cited evidence in this session), PLAUSIBLE (consistent but uncited), or SUSPECT (no supporting evidence and reads like model knowledge)]
|
||||
|
||||
## Strength Assessment
|
||||
|
||||
[What the diagnostician got RIGHT, and what makes those conclusions reliable. Required even when verdict is CHALLENGED.]
|
||||
```
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
name: diagnostician
|
||||
description: Diagnose native Windows application, service, user-mode driver (including UMDF), and kernel-mode driver failures with public WinDbg workflows.
|
||||
---
|
||||
|
||||
# Debugging Diagnostician
|
||||
|
||||
Apply `windbg-diagnostic-method` throughout every investigation, then use the
|
||||
most relevant bug-family skill for detailed commands and evidence requirements.
|
||||
|
||||
Use the available debugger integration only when authorized. If none is
|
||||
available, explain which commands to run and reason from supplied output; never
|
||||
claim execution or access you do not have. Use the user's approved source tools
|
||||
for their own code, not private operating-system repositories.
|
||||
|
||||
## Investigation contract
|
||||
|
||||
1. Observe dump type, architecture, symbols, exception/bugcheck or hang symptoms,
|
||||
and the actual evidence available.
|
||||
2. Form a primary hypothesis and plausible alternatives. Pattern matches are
|
||||
hypotheses, not conclusions.
|
||||
3. Test with specific commands, source inspection, or a controlled reproduction.
|
||||
Record direct evidence and missing information.
|
||||
4. Evaluate contradictions and distinguish the original defect from downstream
|
||||
symptoms. Do not blame a module solely because the crash appears there.
|
||||
5. Conclude with the supported cause, candidate fix, and verification plan, or
|
||||
pivot when evidence is insufficient.
|
||||
|
||||
## Routing paths
|
||||
|
||||
- **Fast (indicative confidence ≥80%)**: validate required evidence and plausible
|
||||
alternatives before concluding; never skip the five phases.
|
||||
- **Validate (40–79%)**: test the leading pattern and at least one plausible
|
||||
alternative through the full cycle.
|
||||
- **Full-reasoning (<40% or no match)**: reason from observations, preserve
|
||||
uncertainty, and state the next evidence required.
|
||||
|
||||
Confidence is explanatory judgment, not measured probability.
|
||||
|
||||
## Available routes
|
||||
|
||||
| Evidence | Skill |
|
||||
|---|---|
|
||||
| Application, service, or user-mode driver host structured exception | `windbg-user-exception-triage` |
|
||||
| Application, service, or user-mode driver host heap corruption/history | `windbg-user-heap-corruption-investigation` |
|
||||
| Blocked UI, service, user-mode driver host, COM/RPC, or thread/process wait | `windbg-user-wait-chain-analysis` |
|
||||
| A recorded application, service, or user-mode driver host execution with a history question | `windbg-user-ttd-reverse-debugging-triage` |
|
||||
| User-mode allocation failure, VA fragmentation, or commit pressure | `windbg-user-virtual-memory-exhaustion` |
|
||||
| Thread-affine lock surviving coroutine suspension in a user-mode component | `windbg-user-mutex-held-across-co-await` |
|
||||
| Kernel bugcheck, trap frame, or saved exception context | `windbg-kernel-bugcheck-triage` |
|
||||
| Driver Verifier violation | `windbg-kernel-verifier-triage` |
|
||||
| Outstanding/power IRP, cancellation, or completion | `windbg-kernel-irp-lifecycle-triage` |
|
||||
| Kernel lock owner/waiter chain | `windbg-kernel-lock-deadlock-triage` |
|
||||
|
||||
The user-mode skills apply to native applications, services, and user-mode
|
||||
drivers such as UMDF drivers running in a user-mode host process. The
|
||||
kernel-mode skills apply to kernel-mode drivers. `skills.json` is the complete
|
||||
inventory. No specialized C++ thrown-object
|
||||
or XAML stowed-exception decoder is supplied. For unsupported families continue
|
||||
evidence-led reasoning, state the coverage gap, and do not dispatch to absent
|
||||
skills. Kernel trap and context recovery are part of the bugcheck skill.
|
||||
|
||||
## Hypothesis templates
|
||||
|
||||
Use these only to generate testable alternatives:
|
||||
|
||||
| Template | Evidence required |
|
||||
|---|---|
|
||||
| Race condition | Shared state, competing paths, ordering, and a reproducible interleaving |
|
||||
| Lock ordering | Owners/waiters and the conflicting acquisition order |
|
||||
| RPC under lock | Held resource plus callback/server dependency |
|
||||
| Timer/callback race | Registration, cancellation/rundown, lifetime, and still-runnable path |
|
||||
| Cross-apartment dependency | Apartment contracts, marshaling, pumping/reentrancy, and agility |
|
||||
| Reentrant lock acquisition | Reentrant edge and violated lock/state invariant |
|
||||
| Regression | Before/after evidence and the relevant code/configuration change |
|
||||
| Platform/instruction | Architecture, decoded bytes, ABI/CPU requirement, and binary identity |
|
||||
|
||||
## Independent review and completion gate
|
||||
|
||||
Before finalizing a full diagnosis:
|
||||
|
||||
1. Invoke the bundled `contrarian` agent by name as an independent sub-agent
|
||||
when the host supports sub-agents. Give it the complete proposed diagnosis.
|
||||
2. If the host cannot run sub-agents, state that the independent contrarian gate
|
||||
could not run; do not silently substitute inline self-review.
|
||||
3. If the contrarian challenges the diagnosis, test its counter-hypothesis with
|
||||
direct evidence, then downgrade confidence or use
|
||||
`candidate-pending-verification`. Stop after one loopback.
|
||||
4. Write the diagnosis report when filesystem access is available, then run the
|
||||
validator bundled with `windbg-diagnostic-method`. Correct structural
|
||||
failures and re-run the script before finalizing.
|
||||
|
||||
## Output
|
||||
|
||||
Provide a diagnosis with: observations, hypothesis, evidence, alternatives,
|
||||
supported/candidate cause, proposed fix, and verification needs. Distinguish
|
||||
observed facts from inference; report insufficient symbols/dump pages explicitly.
|
||||
Report diagnosis confidence separately from `fix_confidence`, and include
|
||||
`fix_code_path_coverage` using one of: `read-this-session`,
|
||||
`read-prior-session`, `symbol-or-disassembly`, `pattern-only`, or `not-read`.
|
||||
Write a local diagnosis artifact only when requested or required by the user's
|
||||
workflow. Do not automatically turn the analysis into public feedback.
|
||||
|
||||
When the user requests the full durable workflow and filesystem access is
|
||||
available, write `./.diagnoses/<short-id>/<yyyyMMdd-HHmmss>.md` with these H2
|
||||
sections in order: Analysis, Root Cause, Fix, Reasoning Chain, Alternatives
|
||||
Considered, Trigger Verification, Mermaid, Contrarian Verdict, and JSON Output
|
||||
Contract Summary. Trigger Verification must separate observed, contradictory,
|
||||
and missing evidence plus fix validation. Record `contrarian_loopback` as the
|
||||
Boolean `true` or `false`. Run the validator bundled with
|
||||
`windbg-diagnostic-method` against the report. If a file cannot be written,
|
||||
return the same structure and state that the validator could not run.
|
||||
|
||||
## Safety and feedback
|
||||
|
||||
Do not enable Verifier/Page Heap, change system configuration, capture a trace,
|
||||
or upload an artifact without user authorization. Explain repro-tool impact and
|
||||
restoration steps. Never force a crash or alter a production machine merely to
|
||||
collect evidence.
|
||||
|
||||
For requested feedback follow the plugin's `FEEDBACK.md`: draft a minimal
|
||||
sanitized issue for https://github.com/microsoft/WinDbg-Feedback/issues, show
|
||||
the exact public payload, and ask for approval before posting with a supported
|
||||
GitHub issue tool. Without a tool, provide approved text for manual submission.
|
||||
Never attach dumps/traces/transcripts automatically or claim submission without
|
||||
a confirmed issue URL.
|
||||
27
vendor-new/win-dev-skills/plugins/windbg/plugin.json
Normal file
27
vendor-new/win-dev-skills/plugins/windbg/plugin.json
Normal file
@@ -0,0 +1,27 @@
|
||||
{
|
||||
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
||||
"name": "windbg",
|
||||
"version": "1.0.0",
|
||||
"description": "WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.",
|
||||
"author": {
|
||||
"name": "Microsoft",
|
||||
"url": "https://github.com/microsoft/WinDbg-Feedback"
|
||||
},
|
||||
"homepage": "https://github.com/microsoft/WinDbg-Feedback",
|
||||
"repository": "https://github.com/microsoft/win-dev-skills",
|
||||
"keywords": [
|
||||
"windows",
|
||||
"windbg",
|
||||
"debugging",
|
||||
"crash",
|
||||
"hang",
|
||||
"memory",
|
||||
"umdf",
|
||||
"drivers"
|
||||
],
|
||||
"extensions": {
|
||||
"com.github.copilot": {
|
||||
"agents": "./com.github.copilot/agents"
|
||||
}
|
||||
}
|
||||
}
|
||||
19
vendor-new/win-dev-skills/plugins/windbg/skills.json
Normal file
19
vendor-new/win-dev-skills/plugins/windbg/skills.json
Normal file
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"name": "windbg",
|
||||
"version": "1.0.0",
|
||||
"diagnosticSkills": [
|
||||
"windbg-user-exception-triage",
|
||||
"windbg-user-heap-corruption-investigation",
|
||||
"windbg-user-wait-chain-analysis",
|
||||
"windbg-user-ttd-reverse-debugging-triage",
|
||||
"windbg-user-virtual-memory-exhaustion",
|
||||
"windbg-user-mutex-held-across-co-await",
|
||||
"windbg-kernel-bugcheck-triage",
|
||||
"windbg-kernel-verifier-triage",
|
||||
"windbg-kernel-irp-lifecycle-triage",
|
||||
"windbg-kernel-lock-deadlock-triage"
|
||||
],
|
||||
"methodSkills": [
|
||||
"windbg-diagnostic-method"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,179 @@
|
||||
---
|
||||
name: windbg-diagnostic-method
|
||||
description: Use with every WinDbg plugin investigation to apply evidence-first reasoning, confidence calibration, contrarian review, structured reporting, and deterministic validation. Not a bug-family-specific triage skill.
|
||||
user-invocable: false
|
||||
---
|
||||
# WinDbg Diagnostic Method
|
||||
|
||||
Apply this method alongside the bug-family-specific skill selected for an
|
||||
investigation. Pattern matches route the investigation; they do not prove the
|
||||
root cause.
|
||||
|
||||
## Evidence ladder
|
||||
|
||||
Prefer direct evidence in this order:
|
||||
|
||||
1. Faulting instruction/context, bugcheck or exception parameters, and resource
|
||||
owners/waiters from the actual dump or trace.
|
||||
2. Matching symbols and the user's authorized source for the involved build.
|
||||
3. Allocation/free, Verifier, IRP, lock, ETW, WCT, or TTD history captured for
|
||||
the same failure.
|
||||
4. Controlled reproduction and instrumentation.
|
||||
5. Pattern guidance as a hypothesis only.
|
||||
|
||||
Never claim commands, source access, or artifacts that are unavailable in the
|
||||
session.
|
||||
|
||||
## First-pass normalization
|
||||
|
||||
- Confirm process dump versus kernel dump and target architecture/build.
|
||||
- Load public Windows symbols and matching symbols for user/vendor modules.
|
||||
- Record missing pages, symbols, related-process dumps, trace scope, and tool
|
||||
availability.
|
||||
- User-mode exception: `.exr -1`, `.ecxr`, stack, and registers.
|
||||
- Kernel bugcheck: `.bugcheck`, `!analyze -v`, then documented context/trap
|
||||
recovery for that code.
|
||||
- Hang: identify the affected operation, wait type, owner/server, and deepest
|
||||
supported blocker.
|
||||
- Memory: distinguish corruption, address-space pressure, and commit/limit
|
||||
failures before choosing a fix.
|
||||
|
||||
## Five-phase investigation
|
||||
|
||||
1. **OBSERVE**: establish dump/trace type, architecture, symbols, code, stack,
|
||||
registers, thread/resource state, and missing evidence.
|
||||
2. **HYPOTHESIZE**: form a specific primary mechanism and at least two plausible
|
||||
alternatives when the evidence permits.
|
||||
3. **TEST**: identify direct debugger, source, trace, or reproduction evidence
|
||||
that distinguishes the hypotheses. Absence of evidence is not evidence of
|
||||
absence.
|
||||
4. **EVALUATE**: record supporting, contradictory, and missing evidence.
|
||||
5. **CONCLUDE or PIVOT**: name the violated invariant and verification plan, or
|
||||
remain `candidate-pending-verification`.
|
||||
|
||||
## Routing index
|
||||
|
||||
| Evidence | Skill |
|
||||
|---|---|
|
||||
| Native user-mode exception in an app, service, or UMDF/user-mode driver host | `windbg-user-exception-triage` |
|
||||
| User-mode heap corruption or allocation/free history | `windbg-user-heap-corruption-investigation` |
|
||||
| Cross-thread/process, COM/RPC, or service wait | `windbg-user-wait-chain-analysis` |
|
||||
| User-mode TTD history question | `windbg-user-ttd-reverse-debugging-triage` |
|
||||
| User-mode VA fragmentation, allocation failure, or commit pressure | `windbg-user-virtual-memory-exhaustion` |
|
||||
| Thread-affine lock across coroutine suspension | `windbg-user-mutex-held-across-co-await` |
|
||||
| Kernel bugcheck, trap frame, or saved context | `windbg-kernel-bugcheck-triage` |
|
||||
| Driver Verifier violation | `windbg-kernel-verifier-triage` |
|
||||
| Outstanding/power IRP, completion, or cancellation | `windbg-kernel-irp-lifecycle-triage` |
|
||||
| Kernel lock owner/waiter chain | `windbg-kernel-lock-deadlock-triage` |
|
||||
|
||||
These are the complete bug-family routes. Continue evidence-led reasoning for
|
||||
unsupported families; never dispatch to an absent skill.
|
||||
|
||||
## Routing depth
|
||||
|
||||
- **Fast (indicative diagnosis confidence >=0.80)**: validate the apparent
|
||||
pattern, its required evidence, and plausible alternatives.
|
||||
- **Validate (0.40-0.79)**: test the leading pattern and at least one plausible
|
||||
alternative through the full cycle.
|
||||
- **Full reasoning (<0.40 or no match)**: reason from observations and preserve
|
||||
explicit uncertainty.
|
||||
|
||||
Confidence is explanatory judgment, not measured probability.
|
||||
|
||||
## Trigger and fix gates
|
||||
|
||||
- Verify the trigger in the dump, disassembly, source, trace, or controlled
|
||||
reproduction before declaring a final fix.
|
||||
- Name the violated invariant and the parties or path that violate it.
|
||||
- Separate the detector or victim from the original writer, freeing actor, or
|
||||
resource holder.
|
||||
- A fix must restore the violated invariant, not merely suppress the reproducer.
|
||||
- If the trigger is unverified, use `candidate-pending-verification`, set the
|
||||
fix to null or a verification plan, and name the evidence/fix matrix needed.
|
||||
- Do not blame a module solely from a bucket or `MODULE_NAME`.
|
||||
|
||||
## Fix-confidence calibration
|
||||
|
||||
Diagnosis confidence and fix confidence are separate. Every proposed fix must
|
||||
declare `fix_confidence` and one `fix_code_path_coverage` value:
|
||||
|
||||
| Fix confidence | Required coverage |
|
||||
|---|---|
|
||||
| `>=0.90` | `read-this-session`: the actual fix path was read in this investigation. |
|
||||
| `0.70-0.89` | `read-prior-session` or `symbol-or-disassembly`: direct coverage exists, but the complete source path was not read in this investigation. |
|
||||
| `0.50-0.69` | `pattern-only`, or incomplete symbol/disassembly evidence. Treat the fix as a candidate. |
|
||||
| `<0.50` | `not-read`: no direct fix-path coverage. Keep the diagnosis candidate-pending-verification and set the fix to null or a verification plan. |
|
||||
|
||||
Lower confidence is always allowed when evidence quality, path coverage, or
|
||||
alternatives warrant it. Never raise confidence to fit the table.
|
||||
|
||||
## Independent review
|
||||
|
||||
Before finalizing a full diagnosis:
|
||||
|
||||
1. When the host supports the bundled Copilot agents, invoke the `contrarian`
|
||||
agent once with the complete proposed diagnosis.
|
||||
2. When the host cannot run that agent, state that the independent review did
|
||||
not run; do not silently substitute inline self-review.
|
||||
3. If the verdict is `CHALLENGED`, test the counter-hypothesis with direct
|
||||
evidence, then downgrade confidence or remain pending verification.
|
||||
4. Stop after one loopback. A second challenge remains pending verification.
|
||||
|
||||
Record `contrarian_loopback` as the Boolean `true` or `false`.
|
||||
|
||||
## Report contract
|
||||
|
||||
A full report contains these H2 sections in order:
|
||||
|
||||
1. Analysis
|
||||
2. Root Cause
|
||||
3. Fix
|
||||
4. Reasoning Chain
|
||||
5. Alternatives Considered
|
||||
6. Trigger Verification
|
||||
7. Mermaid
|
||||
8. Contrarian Verdict
|
||||
9. JSON Output Contract Summary
|
||||
|
||||
The Trigger Verification section must distinguish observed, contradictory, and
|
||||
missing evidence plus fix validation. Mermaid must reflect verified evidence.
|
||||
The JSON summary must include:
|
||||
|
||||
- `diagnosis_status`
|
||||
- `routing_path`
|
||||
- `root_cause`
|
||||
- `confidence`
|
||||
- `fix_confidence`
|
||||
- `fix_code_path_coverage`
|
||||
- `contrarian_review`
|
||||
- `contrarian_loopback`
|
||||
|
||||
## Deterministic report validation
|
||||
|
||||
After writing the report, run the bundled validator with PowerShell 7:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File <skill-directory>\scripts\validate-diagnosis-output.ps1 `
|
||||
-Path <diagnosis-markdown-path>
|
||||
```
|
||||
|
||||
Use the installed `windbg-diagnostic-method` directory for
|
||||
`<skill-directory>`. The script checks each section body independently,
|
||||
requires at least two alternatives, accepts explicit or implicit Mermaid
|
||||
participants, parses the JSON summary, and exits nonzero on failure.
|
||||
|
||||
Correct failed checks and rerun the script before presenting the report as
|
||||
structurally complete. Structural validation does not replace technical review.
|
||||
|
||||
## Safety and privacy
|
||||
|
||||
Dumps, traces, ETLs, CABs, source, paths, tokens, and memory contents can be
|
||||
sensitive. Obtain authorization before capture, configuration changes, or
|
||||
sharing. Verifier and Page Heap can disrupt workloads and require a recoverable
|
||||
test plan plus restoration steps. Public feedback follows `FEEDBACK.md` and
|
||||
defaults to a minimal reviewed summary with no automatic attachments.
|
||||
|
||||
## Feedback
|
||||
|
||||
For feedback about this method or validator, follow the package `FEEDBACK.md`.
|
||||
Do not attach private diagnosis files automatically.
|
||||
@@ -0,0 +1,169 @@
|
||||
param(
|
||||
[Parameter(Mandatory = $true)]
|
||||
[string]$Path
|
||||
)
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
|
||||
throw "Diagnosis file not found: $Path"
|
||||
}
|
||||
|
||||
$resolvedPath = (Resolve-Path -LiteralPath $Path).Path
|
||||
$content = Get-Content -LiteralPath $resolvedPath -Raw
|
||||
|
||||
function Get-SectionMatch {
|
||||
param([Parameter(Mandatory = $true)][string]$HeadingPattern)
|
||||
|
||||
$pattern = "(?ims)^##\s+(?:$HeadingPattern)\b[^\r\n]*\r?\n(?<body>.*?)(?=^##\s+|\z)"
|
||||
return [regex]::Match($content, $pattern)
|
||||
}
|
||||
|
||||
function Test-MermaidDiagram {
|
||||
$blocks = [regex]::Matches($content, '(?ims)^```mermaid\s*\r?\n(?<body>.*?)^```\s*$')
|
||||
foreach ($block in $blocks) {
|
||||
$body = $block.Groups["body"].Value
|
||||
|
||||
if ($body -match '(?im)^\s*sequenceDiagram\s*$') {
|
||||
$actors = [System.Collections.Generic.HashSet[string]]::new(
|
||||
[System.StringComparer]::OrdinalIgnoreCase
|
||||
)
|
||||
|
||||
foreach ($match in [regex]::Matches(
|
||||
$body,
|
||||
'(?im)^\s*(?:participant|actor)\s+([A-Za-z0-9_.-]+)'
|
||||
)) {
|
||||
[void]$actors.Add($match.Groups[1].Value)
|
||||
}
|
||||
|
||||
foreach ($match in [regex]::Matches(
|
||||
$body,
|
||||
'(?im)^\s*([A-Za-z0-9_.-]+)\s*(?:--?>>|->>|--?>|--x|-x|--\)|-\))\s*([A-Za-z0-9_.-]+)\s*:'
|
||||
)) {
|
||||
[void]$actors.Add($match.Groups[1].Value)
|
||||
[void]$actors.Add($match.Groups[2].Value)
|
||||
}
|
||||
|
||||
if ($actors.Count -ge 2) {
|
||||
return $true
|
||||
}
|
||||
}
|
||||
|
||||
if ($body -match '(?im)^\s*(?:flowchart|graph)\b') {
|
||||
$nodes = [System.Collections.Generic.HashSet[string]]::new(
|
||||
[System.StringComparer]::OrdinalIgnoreCase
|
||||
)
|
||||
|
||||
foreach ($match in [regex]::Matches(
|
||||
$body,
|
||||
'(?im)^\s*([A-Za-z0-9_]+).*?(?:-->|---|-.->|==>)\s*([A-Za-z0-9_]+)'
|
||||
)) {
|
||||
[void]$nodes.Add($match.Groups[1].Value)
|
||||
[void]$nodes.Add($match.Groups[2].Value)
|
||||
}
|
||||
|
||||
if ($nodes.Count -ge 2) {
|
||||
return $true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return $false
|
||||
}
|
||||
|
||||
$analysis = Get-SectionMatch "Analysis"
|
||||
$rootCause = Get-SectionMatch "Root Cause"
|
||||
$fix = Get-SectionMatch "Fix"
|
||||
$reasoning = Get-SectionMatch "Reasoning Chain"
|
||||
$alternatives = Get-SectionMatch "Alternatives(?: Considered)?"
|
||||
$trigger = Get-SectionMatch "Trigger Verification"
|
||||
$contrarian = Get-SectionMatch "Contrarian Verdict"
|
||||
|
||||
$alternativeCount = 0
|
||||
if ($alternatives.Success) {
|
||||
$alternativeCount = [regex]::Matches(
|
||||
$alternatives.Groups["body"].Value,
|
||||
'(?m)^\s*(?:[-*+]\s+|\d+[.)]\s+)'
|
||||
).Count
|
||||
}
|
||||
|
||||
$triggerBody = if ($trigger.Success) { $trigger.Groups["body"].Value } else { "" }
|
||||
$triggerTableRows = [regex]::Matches($triggerBody, '(?m)^\s*\|.*\|\s*$').Count
|
||||
|
||||
$contrarianBody = if ($contrarian.Success) {
|
||||
$contrarian.Groups["body"].Value
|
||||
} else {
|
||||
""
|
||||
}
|
||||
|
||||
$results = [ordered]@{
|
||||
AnalysisHeading = $analysis.Success
|
||||
RootCauseHeading = $rootCause.Success
|
||||
FixHeading = $fix.Success
|
||||
ReasoningChain = (
|
||||
$reasoning.Success -and
|
||||
$reasoning.Groups["body"].Value -match 'OBSERVE|HYPOTHESIZE|TEST|EVALUATE|CONCLUDE'
|
||||
)
|
||||
Alternatives = ($alternatives.Success -and $alternativeCount -ge 2)
|
||||
TriggerVerification = (
|
||||
$trigger.Success -and
|
||||
$triggerTableRows -ge 3 -and
|
||||
$triggerBody -match '(?i)\bVERIFIED\b|\bUNVERIFIED\b|verified by'
|
||||
)
|
||||
MermaidDiagram = Test-MermaidDiagram
|
||||
ContrarianVerdict = (
|
||||
$contrarian.Success -and
|
||||
$contrarianBody -match '\bACCEPTED\b|\bCHALLENGED\b' -and
|
||||
$contrarianBody -match '(?i)contrarian_loopback[^:\r\n]*:\s*(?:true|false)\b'
|
||||
)
|
||||
JsonSummary = $false
|
||||
}
|
||||
|
||||
$requiredJsonProperties = @(
|
||||
"diagnosis_status",
|
||||
"routing_path",
|
||||
"root_cause",
|
||||
"confidence",
|
||||
"fix_confidence",
|
||||
"fix_code_path_coverage",
|
||||
"contrarian_review",
|
||||
"contrarian_loopback"
|
||||
)
|
||||
|
||||
foreach ($block in [regex]::Matches($content, '(?is)```json\s*(?<body>.*?)```')) {
|
||||
try {
|
||||
$json = $block.Groups["body"].Value | ConvertFrom-Json
|
||||
} catch {
|
||||
continue
|
||||
}
|
||||
|
||||
$propertyNames = @($json.PSObject.Properties.Name)
|
||||
$hasRequiredProperties = $true
|
||||
foreach ($property in $requiredJsonProperties) {
|
||||
if ($propertyNames -notcontains $property) {
|
||||
$hasRequiredProperties = $false
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if (
|
||||
$hasRequiredProperties -and
|
||||
$json.contrarian_loopback -is [bool]
|
||||
) {
|
||||
$results.JsonSummary = $true
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
$pass = @($results.Values | Where-Object { $_ -eq $false }).Count -eq 0
|
||||
$output = [pscustomobject]@{
|
||||
Pass = $pass
|
||||
File = $resolvedPath
|
||||
Checks = [pscustomobject]$results
|
||||
}
|
||||
|
||||
$output | ConvertTo-Json -Depth 5
|
||||
if (-not $pass) {
|
||||
exit 1
|
||||
}
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
name: windbg-kernel-bugcheck-triage
|
||||
description: 'Use when a kernel dump reports a Windows bugcheck; decode parameters and recover exception or trap context before investigating your driver. Not for user-mode process crashes or blaming a module from its name alone.'
|
||||
---
|
||||
|
||||
# Kernel Bugcheck 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.
|
||||
|
||||
## Scope
|
||||
|
||||
Use a kernel crash dump or authorized live kernel session. A process dump
|
||||
captured after a reboot does not contain the earlier kernel fault. Confirm
|
||||
the dump type with the debugger, not a filename or the user's visible symptom.
|
||||
This skill includes exception-context and trap-frame recovery.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Establish symbols and bugcheck evidence
|
||||
|
||||
```text
|
||||
.symfix
|
||||
.sympath+ <your-vendor-symbol-directory>
|
||||
.reload
|
||||
!analyze -v
|
||||
.bugcheck
|
||||
k
|
||||
```
|
||||
|
||||
Replace the placeholder with the approved symbol location for your own binaries.
|
||||
Record dump type, target architecture/build, bugcheck code and parameters,
|
||||
faulting instruction, and available memory. Public Windows symbols suffice
|
||||
for many investigations; do not require private Windows source or PDBs.
|
||||
|
||||
### 2. Decode parameters for the specific code
|
||||
|
||||
| Code | Parameter meaning / next step |
|
||||
|---|---|
|
||||
| `0x1E` | P1 exception code; P2 exception address; P3/P4 exception-specific information. These are not generically a CONTEXT pair. |
|
||||
| `0x7E` | P1 exception code; P2 exception address; P3 EXCEPTION_RECORD; P4 CONTEXT. |
|
||||
| `0x3B` | P1 exception code; P2 instruction address; P3 CONTEXT; P4 unused. |
|
||||
| `0x0A` / `0xD1` | Referenced address, IRQL, access information, instruction address. Decode the access field for that code; these parameters are not generally a trap-frame pointer. |
|
||||
| `0x50` | Invalid memory reference; parameter interpretation varies with target version. Consult the code reference. |
|
||||
| `0x9F` | P1 selects the power-failure subtype; use its specific parameter table and `windbg-kernel-irp-lifecycle-triage` where applicable. |
|
||||
| Verifier-class stop | Use `windbg-kernel-verifier-triage` and the exact code/subcode definition. |
|
||||
|
||||
Do not reuse a parameter layout across different bugchecks.
|
||||
|
||||
### 3. Recover the original faulting context
|
||||
|
||||
For `0x7E`:
|
||||
|
||||
```text
|
||||
.exr <P3>
|
||||
.cxr <P4>
|
||||
kb
|
||||
r
|
||||
```
|
||||
|
||||
For `0x3B`:
|
||||
|
||||
```text
|
||||
.cxr <P3>
|
||||
kb
|
||||
r
|
||||
```
|
||||
|
||||
For other exception-style bugchecks, locate a valid saved exception/context
|
||||
using the documented code procedure and available analysis output. Do not
|
||||
guess `.cxr` arguments from arbitrary P1..P4 values.
|
||||
|
||||
When `!analyze -v` or verified stack evidence identifies a `TRAP_FRAME`:
|
||||
|
||||
```text
|
||||
.trap <trap-frame-address>
|
||||
kb
|
||||
r
|
||||
```
|
||||
|
||||
Trap frames can be partial: some registers may be missing or reconstructed
|
||||
incorrectly. Note the debugger's warnings and do not treat unsaved registers as
|
||||
reliable evidence. If a frame is missing, malformed, or absent from the dump,
|
||||
report the limitation rather than scanning arbitrary pointers and claiming a
|
||||
recovered context.
|
||||
|
||||
### 4. Investigate the driver, not just the detector
|
||||
|
||||
```text
|
||||
!thread
|
||||
lmvm <driver-module>
|
||||
.frame /r <frame-number>
|
||||
```
|
||||
|
||||
Inspect the recovered instruction, register/object used, IRQL, ownership,
|
||||
and nearby driver frames. A crash in an operating-system routine may result
|
||||
from prior driver corruption. Conversely, a third-party name in
|
||||
`MODULE_NAME` does not establish that the named driver caused the failure.
|
||||
Verify vendor build identity against the matching binary/PDB.
|
||||
|
||||
For concurrency or blocked requests use `windbg-kernel-lock-deadlock-triage` or
|
||||
`windbg-kernel-irp-lifecycle-triage`. Kernel `~` commands select processors, not the
|
||||
application thread list; use documented thread/process inspection such as
|
||||
`!thread` and `!process 0 7`.
|
||||
|
||||
## Validation
|
||||
|
||||
Record the decoded parameters, recovered context and its limitations, and the
|
||||
evidence connecting the driver's operation to the violated invariant. Test
|
||||
competing lifetime, bounds, IRQL, and synchronization explanations. Recommend
|
||||
an instrumented test/repro only with approval; route Verifier evidence to
|
||||
`windbg-kernel-verifier-triage`. Do not call a guessed module assignment a proven cause.
|
||||
|
||||
## References
|
||||
|
||||
- [Bugcheck reference](https://learn.microsoft.com/windows-hardware/drivers/debugger/bug-check-code-reference2)
|
||||
- [0x3B SYSTEM_SERVICE_EXCEPTION](https://learn.microsoft.com/windows-hardware/drivers/debugger/bug-check-0x3b--system-service-exception)
|
||||
- [0x7E SYSTEM_THREAD_EXCEPTION_NOT_HANDLED](https://learn.microsoft.com/windows-hardware/drivers/debugger/bug-check-0x7e--system-thread-exception-not-handled)
|
||||
- [Context record](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-cxr--display-context-record-)
|
||||
- [Trap frame](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-trap--display-trap-frame-)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and submit only reviewed, sanitized feedback to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-kernel-bugcheck-triage` and the package version from `plugin.json`; no
|
||||
automatic kernel dump, private-symbol, or source upload.
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
name: windbg-kernel-irp-lifecycle-triage
|
||||
description: 'Use when kernel evidence shows stalled I/O, a power IRP, or completion/cancellation misuse; inspect request state and driver ownership. Not for interpreting an empty IRP search in a limited dump as proof of healthy I/O.'
|
||||
---
|
||||
|
||||
# IRP Lifecycle 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.
|
||||
|
||||
## Scope
|
||||
|
||||
Investigate I/O Request Packets in a kernel dump or authorized live kernel
|
||||
session. Examples include `0x9F` power failures and hangs where progress
|
||||
depends on a driver request. Apply the parameter table for the specific
|
||||
bugcheck subtype rather than assuming every `0x9F` identifies the same object.
|
||||
|
||||
For `0x9F` with P1 equal to `3`, P4 is the blocked IRP. Inspect that directly
|
||||
before running a system-wide search.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Decode the known request
|
||||
|
||||
```text
|
||||
!analyze -v
|
||||
!irp <irp-address>
|
||||
```
|
||||
|
||||
When no request address is known and the dump has the required pool data:
|
||||
|
||||
```text
|
||||
!irpfind
|
||||
```
|
||||
|
||||
`!irpfind` can be expensive in a live session and incomplete in a limited dump.
|
||||
Use supported filters where appropriate. No result does not prove there are
|
||||
no outstanding requests.
|
||||
|
||||
### 2. Follow the stack and ownership
|
||||
|
||||
Record the major/minor operation, current stack location, device/driver stack,
|
||||
completion routine, pending flags, cancellation state, and any relevant thread.
|
||||
Use the available device stack and driver source to establish which component
|
||||
is expected to advance or complete the request.
|
||||
|
||||
Do not identify an offending driver solely by the last name printed in the IRP
|
||||
stack. A completion routine, downstream dependency, or framework-owned request
|
||||
may change the responsible path.
|
||||
|
||||
### 3. Correlate dependencies
|
||||
|
||||
| Evidence | Next investigation |
|
||||
|---|---|
|
||||
| I/O verifier violation or available shadow history | `windbg-kernel-verifier-triage` |
|
||||
| Owner/waiter kernel lock chain | `windbg-kernel-lock-deadlock-triage` |
|
||||
| Exception or trap during request handling | `windbg-kernel-bugcheck-triage` |
|
||||
|
||||
Preserve evidence between skills; avoid repeatedly handing the same unchanged
|
||||
IRP back and forth.
|
||||
|
||||
### 4. Test the request protocol
|
||||
|
||||
- **Power request:** inspect the subtype's objects and power/PnP state,
|
||||
current stack location, and completion dependency.
|
||||
- **Cancellation race:** establish which routine owns completion, how
|
||||
cancellation synchronizes with normal completion, and whether the request
|
||||
can be completed twice or retained after cancellation.
|
||||
- **Double completion:** trace competing terminal paths; a single live IRP
|
||||
snapshot may not contain enough history.
|
||||
- **Pending request:** verify API/framework-specific pending and completion
|
||||
rules, remove/shutdown paths, and who promises eventual progress.
|
||||
|
||||
WDM and WDF have different ownership APIs. Do not transplant a raw WDM
|
||||
completion/cancel pattern into a framework-owned request without checking its
|
||||
contract. This skill establishes evidence; it is not a complete I/O protocol
|
||||
reference or a decoder for every power subtype.
|
||||
|
||||
## Validation
|
||||
|
||||
Name the operation, current owner/dependency, and supported protocol violation
|
||||
or stalled path. Test normal completion, concurrent cancellation, removal,
|
||||
power transitions, and shutdown where relevant. If history is missing, propose
|
||||
an approved instrumented test using the verifier skill rather than inventing
|
||||
which driver lost the completion.
|
||||
|
||||
## References
|
||||
|
||||
- [IRP inspection](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-irp)
|
||||
- [IRP search](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-irpfind)
|
||||
- [0x9F power-state failure](https://learn.microsoft.com/windows-hardware/drivers/debugger/bug-check-0x9f--driver-power-state-failure)
|
||||
- [Canceling IRPs](https://learn.microsoft.com/windows-hardware/drivers/kernel/canceling-irps)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and report only reviewed, sanitized feedback to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-kernel-irp-lifecycle-triage` and the package version from `plugin.json`; no
|
||||
automatic kernel dump or request-content upload.
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
name: windbg-kernel-lock-deadlock-triage
|
||||
description: '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.'
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
```text
|
||||
!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:
|
||||
|
||||
```text
|
||||
!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
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
- [ERESOURCE locks extension](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-locks)
|
||||
- [Deadlock extension](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-deadlock)
|
||||
- [Driver Verifier deadlock detection](https://learn.microsoft.com/windows-hardware/drivers/devtest/deadlock-detection)
|
||||
- [Thread inspection](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-thread)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and report reviewed, sanitized feedback to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-kernel-lock-deadlock-triage` and the package version from `plugin.json`; no
|
||||
automatic dump, lock-history transcript, or driver-source upload.
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
name: windbg-kernel-verifier-triage
|
||||
description: 'Use when a kernel dump contains Driver Verifier violations; inspect flags, bugcheck subcodes, and available I/O shadow state. Not for Application Verifier user-mode stops or inferring a violation from enabled flags alone.'
|
||||
---
|
||||
|
||||
# Driver Verifier 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.
|
||||
|
||||
## Scope
|
||||
|
||||
Driver Verifier checks kernel driver contracts. Application Verifier is a
|
||||
different user-mode facility; use `windbg-user-heap-corruption-investigation` for its heap
|
||||
stops. Enabled Driver Verifier flags alone do not prove a contract violation.
|
||||
|
||||
Use this skill when a verifier-class bugcheck or analysis identifies an actual
|
||||
violation. Examples include `0xC4`, `0xC9`, and `0xE6`; inspect the exact code
|
||||
and parameters rather than treating every stop as the same family.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Preserve code, subcode, and active configuration
|
||||
|
||||
```text
|
||||
!analyze -v
|
||||
.bugcheck
|
||||
!verifier
|
||||
k
|
||||
```
|
||||
|
||||
Record the bugcheck, subtype/subcode, offending operation and driver when
|
||||
reported, enabled checks, target build, and evidence availability. Decode each
|
||||
subcode against its documented contract. Existing output may be incomplete in
|
||||
a small dump; do not discard captured evidence merely because live
|
||||
configuration is now different.
|
||||
|
||||
### 2. Decode available I/O history
|
||||
|
||||
When the violation supplies an appropriate IRP address and I/O verification
|
||||
state is available:
|
||||
|
||||
```text
|
||||
!iovirp <irp-address>
|
||||
!irp <irp-address>
|
||||
```
|
||||
|
||||
Shadow state may preserve information lost from the live request. Correlate it
|
||||
with the decoded contract and use `windbg-kernel-irp-lifecycle-triage` for completion,
|
||||
cancellation, pending state, and ownership.
|
||||
|
||||
### 3. Recover context or follow dependencies
|
||||
|
||||
- Saved exception/trap context: `windbg-kernel-bugcheck-triage`.
|
||||
- Lock-order evidence: `windbg-kernel-lock-deadlock-triage`.
|
||||
- Outstanding or power request: `windbg-kernel-irp-lifecycle-triage`.
|
||||
|
||||
Avoid cyclic dispatch. Carry the evidence already collected to the next skill;
|
||||
re-enter only when a distinct evidence requirement exists.
|
||||
|
||||
### 4. Investigate uncovered violations
|
||||
|
||||
For a generic DDI violation, identify the exact precondition (IRQL, lifetime,
|
||||
parameters, or ownership) and the driver call that broke it. For a DMA violation,
|
||||
inspect supported adapter/map/unmap and buffer-lifetime evidence for that
|
||||
subcode. This package does not provide a specialized decoder for every DDI or
|
||||
DMA case; state the gap and continue from documentation and driver source.
|
||||
|
||||
## Controlled repro
|
||||
|
||||
Do not enable Driver Verifier without approval. It can deliberately crash the
|
||||
system and expose boot-critical defects. Use a recoverable test machine, save
|
||||
the current configuration, select relevant vendor drivers/checks, and agree on
|
||||
rollback before restarting. Do not verify every installed driver by default.
|
||||
|
||||
Read-only configuration inspection on a test machine:
|
||||
|
||||
```text
|
||||
verifier /querysettings
|
||||
```
|
||||
|
||||
`verifier /reset` clears settings and normally requires a restart to stop
|
||||
verification; it is a configuration change, not a harmless query. Restore
|
||||
previous intentional settings rather than unconditionally clearing them.
|
||||
|
||||
## Validation
|
||||
|
||||
Name the exact violated contract, link the recorded operation to driver source,
|
||||
and test that the remedy satisfies it under the same checks and workload.
|
||||
Record dump/verification limitations and unverified assumptions. Passing a
|
||||
single repro is not proof that every driver path is safe.
|
||||
|
||||
## References
|
||||
|
||||
- [Driver Verifier](https://learn.microsoft.com/windows-hardware/drivers/devtest/driver-verifier)
|
||||
- [Verifier extension](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-verifier)
|
||||
- [I/O verifier IRP extension](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-iovirp)
|
||||
- [0xC4 verifier violation](https://learn.microsoft.com/windows-hardware/drivers/debugger/bug-check-0xc4--driver-verifier-detected-violation)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and submit reviewed, sanitized feedback to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-kernel-verifier-triage` and the package version from `plugin.json`; do not
|
||||
automatically upload dumps or proprietary driver source.
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
name: windbg-user-exception-triage
|
||||
description: 'Use when a native C/C++ app, service, or user-mode driver host (including UMDF) crashes with a structured exception in a dump or WinDbg session, including native faults inside managed processes. Not for managed .NET exceptions, WinUI/XAML app errors, or kernel bugchecks.'
|
||||
---
|
||||
|
||||
# User-Mode Exception 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.
|
||||
|
||||
## When to use
|
||||
|
||||
Start here for access violations, heap corruption, stack overflow, fail-fast,
|
||||
breakpoints, and other structured exceptions in a native application, service,
|
||||
or user-mode driver host process dump. This includes UMDF driver failures that
|
||||
occur in their user-mode host. Confirm
|
||||
the dump type from WinDbg; the filename extension alone does not distinguish
|
||||
user-mode from kernel-mode dumps.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Establish the exception context
|
||||
|
||||
```text
|
||||
.exr -1
|
||||
.ecxr
|
||||
k
|
||||
!analyze -v
|
||||
```
|
||||
|
||||
Record the exception code, address, parameters, access type, registers, module,
|
||||
and stack. `.ecxr` selects the saved exception context when available. If no
|
||||
exception context was captured, report that limitation rather than treating the
|
||||
currently selected thread as the faulting thread.
|
||||
|
||||
Use matching binaries and PDBs for your modules and public Windows symbols.
|
||||
Investigate mismatches or truncated stacks before naming a failing source line.
|
||||
|
||||
### 2. Classify and choose an available investigation
|
||||
|
||||
| Evidence | Next step |
|
||||
|---|---|
|
||||
| `0xC0000005` with allocation/free or overrun evidence | `windbg-user-heap-corruption-investigation` |
|
||||
| `0xC0000374` heap corruption | `windbg-user-heap-corruption-investigation` |
|
||||
| `0xC0000017`, `0x8007000E`, or an allocation-failure path | `windbg-user-virtual-memory-exhaustion` |
|
||||
| Lock/unlock failure following coroutine suspension | `windbg-user-mutex-held-across-co-await` |
|
||||
| A TTD recording is available and earlier mutation is in question | `windbg-user-ttd-reverse-debugging-triage` |
|
||||
| No crash exception and evidence of blocked work | `windbg-user-wait-chain-analysis` |
|
||||
| A kernel dump reports a bugcheck | `windbg-kernel-bugcheck-triage` |
|
||||
|
||||
Do not classify every address in a heap range as a lifetime bug. Check access
|
||||
type, faulting instruction, object layout, and valid allocation boundaries.
|
||||
|
||||
### 3. Investigate families without a dedicated skill
|
||||
|
||||
- **Access violation without a match:** identify the read/write/execute target,
|
||||
object/register used, and whether bounds, ownership, or synchronization was
|
||||
violated. Distinguish a null pointer from stale or corrupted state.
|
||||
- **`0xC0000409` / fail-fast:** inspect exception parameters and the documented
|
||||
fast-fail subcode, then the failing condition and call path. The historical
|
||||
status name alone does not prove a buffer overrun or rule one out. Not every
|
||||
fast-fail carries an HRESULT.
|
||||
- **`0xC00000FD` / stack overflow:** inspect stack bounds and frame sizes; test
|
||||
recursion, reentrancy, large frames, and inability to commit stack growth.
|
||||
Use the memory-exhaustion skill when commit evidence supports that branch.
|
||||
- **`0xE06D7363` / MSVC C++ exception:** establish whether it was handled,
|
||||
identify the throw/catch path with available symbols, and inspect the
|
||||
exception information supported by the runtime/version. A first-chance throw
|
||||
is not automatically a defect. This package does not decode thrown-object
|
||||
layouts or fully diagnose `noexcept`/termination behavior.
|
||||
- **Stowed/WinRT exceptions:** preserved error information can precede the
|
||||
final failure. Correlate its originating stack and nested errors with the
|
||||
application; this package does not include a XAML extension workflow.
|
||||
- **Illegal instruction or breakpoint:** distinguish CPU/architecture or
|
||||
code-corruption hypotheses from intentional assertions/debug breaks.
|
||||
|
||||
## Validation
|
||||
|
||||
- Exception context and code are established, or their absence is stated.
|
||||
- Faulting instruction and relevant object/register agree with the hypothesis.
|
||||
- Alternatives are tested against evidence, not just stack names.
|
||||
- Missing memory, symbols, and specialized exception coverage are explicit.
|
||||
- The proposed fix addresses a demonstrated invariant and has a repro/test plan.
|
||||
|
||||
## References
|
||||
|
||||
- [Exception context](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-ecxr--display-exception-context-record-)
|
||||
- [Exception record](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-exr--display-exception-record-)
|
||||
- [Controlling exceptions and events](https://learn.microsoft.com/windows-hardware/drivers/debugger/controlling-exceptions-and-events)
|
||||
|
||||
## Feedback
|
||||
|
||||
For this skill, follow the plugin's `FEEDBACK.md` and report a reviewed, sanitized
|
||||
issue to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-user-exception-triage` and the package version from `plugin.json`; do not
|
||||
upload dumps or private source automatically.
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: windbg-user-heap-corruption-investigation
|
||||
description: 'Use when an app, service, or user-mode driver host heap fails or Application Verifier detects corruption; inspect history and bounds. Not for kernel pool corruption or ordinary OOM.'
|
||||
---
|
||||
|
||||
# Heap Corruption Investigation
|
||||
|
||||
**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 and limits
|
||||
|
||||
Look for `STATUS_HEAP_CORRUPTION` (`0xC0000374`), Application Verifier stops,
|
||||
or failures in heap allocate/free/reallocate paths in an application, service,
|
||||
or user-mode driver host such as an UMDF host process. A crash inside the allocator
|
||||
may be the first detection of an earlier bad write, not the faulty operation.
|
||||
Distinguish corruption from allocation failure; for the latter use
|
||||
`windbg-user-virtual-memory-exhaustion`.
|
||||
|
||||
Allocation/free history depends on how the process was instrumented and which
|
||||
pages were captured. A missing history is a limitation, not proof of a leak or
|
||||
use-after-free.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Decode the stop
|
||||
|
||||
```text
|
||||
.exr -1
|
||||
.ecxr
|
||||
!analyze -v
|
||||
k
|
||||
```
|
||||
|
||||
Record the stop reason, corrupted block, corruption address, and the operation
|
||||
that detected the damage. If a verifier stop frame has parameter/local symbols,
|
||||
select it with `.frame /r <frame>` and inspect `dv`; otherwise use the captured
|
||||
stop output and the documented stop definition. Do not assume one fixed
|
||||
parameter layout or a stop code shared by all verifier versions.
|
||||
|
||||
### 2. Recover available block history
|
||||
|
||||
```text
|
||||
!heap -p -a <address>
|
||||
!avrf -hp -a <address>
|
||||
```
|
||||
|
||||
The first command inspects a Page Heap allocation; the second searches available
|
||||
Application Verifier heap-operation history. Use `!heap -?` and `!avrf -?` to
|
||||
confirm support in the installed extension. On an uninstrumented dump these
|
||||
commands may not recover the history needed to identify the writer.
|
||||
|
||||
Capture allocation and free stacks when present. Check the address is inside
|
||||
the user allocation rather than a header or neighboring block.
|
||||
|
||||
### 3. Test competing explanations
|
||||
|
||||
| Hypothesis | Evidence to seek |
|
||||
|---|---|
|
||||
| Use-after-free | Confirmed free before a later access through a retained reference |
|
||||
| Double-free | Two ownership/completion paths freeing the same allocation |
|
||||
| Overrun/underrun | A write outside the allocated user bounds |
|
||||
| Wild write | Corrupted header or payload and a writer with an invalid target |
|
||||
| Allocation/free contract mismatch | Different allocator/deallocator or incorrect owning heap |
|
||||
|
||||
Inspect bytes with `db <address> L<size>` and disassembly around the access.
|
||||
Fill patterns and plausible pointers are clues, not causal proof. Correlate with
|
||||
source, history, or a repro and trace the ownership transition.
|
||||
|
||||
### 4. Obtain stronger evidence if necessary
|
||||
|
||||
With user approval, enable full Page Heap for a named test executable:
|
||||
|
||||
```text
|
||||
gflags /p /enable target.exe /full
|
||||
```
|
||||
|
||||
Restart that process and reproduce under the debugger. Application Verifier
|
||||
heap checks can also be configured for that test executable. Explain memory
|
||||
overhead, timing changes, and potential deliberate stops before doing this.
|
||||
Record the previous settings and restore them when finished; if Page Heap was
|
||||
newly enabled for this test, disable it with:
|
||||
|
||||
```text
|
||||
gflags /p /disable target.exe
|
||||
```
|
||||
|
||||
Do not change an existing application's verification policy without approval.
|
||||
If a user-mode TTD trace is available, use `windbg-user-ttd-reverse-debugging-triage` to
|
||||
find the relevant mutation or free.
|
||||
|
||||
## Fix patterns
|
||||
|
||||
- Enforce the actual lifetime contract with ownership types or explicit
|
||||
acquire/release rules. Shared ownership is appropriate only when the design
|
||||
genuinely has multiple owners.
|
||||
- Synchronize shared state separately: `shared_ptr` ownership does not make a
|
||||
concurrently modified cache or pointed-to object thread-safe.
|
||||
- Size buffers and check arithmetic, lengths, and terminators; use bounds-aware
|
||||
containers where appropriate.
|
||||
- Keep allocation and deallocation compatible across DLL/API boundaries.
|
||||
|
||||
## Validation
|
||||
|
||||
Establish the affected block and supported corruption class, name the path that
|
||||
violated bounds or ownership, and distinguish the detector from the writer.
|
||||
Exercise the fix with the same instrumentation and relevant concurrency/load.
|
||||
Report unresolved writer history rather than presenting a guessed fix as proven.
|
||||
|
||||
## References
|
||||
|
||||
- [Application Verifier stop definitions](https://learn.microsoft.com/windows-hardware/drivers/devtest/application-verifier-stop-codes-and-definitions)
|
||||
- [Heap extension](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-heap)
|
||||
- [Application Verifier extension](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-avrf)
|
||||
- [GFlags and Page Heap](https://learn.microsoft.com/windows-hardware/drivers/debugger/gflags-and-pageheap)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and report reviewed, sanitized feedback to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-user-heap-corruption-investigation` and the package version from
|
||||
`plugin.json`; no automatic dump, source, or transcript upload.
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
name: windbg-user-mutex-held-across-co-await
|
||||
description: 'Use when app, service, or user-mode driver C++ coroutine code holds a thread-affine lock across suspension and later hangs or fails. Not for all coroutine crashes or choosing lock performance.'
|
||||
---
|
||||
|
||||
# Mutex Held Across co_await
|
||||
|
||||
**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
|
||||
|
||||
This pattern can occur in native application, service, or user-mode driver
|
||||
code, including UMDF components that use C++ coroutines. Look for a lock
|
||||
acquired before `co_await` and released after resumption or
|
||||
coroutine destruction. Mutex ownership belongs to the acquiring thread, not
|
||||
the coroutine frame. A resumption on another thread can violate that contract.
|
||||
Even same-thread resumption can create reentrancy or progress problems when
|
||||
the awaited operation needs a lock the coroutine still holds.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Identify the exact lock primitive and acquisition/release scope in source.
|
||||
Audit every suspension point while the RAII guard or ownership is alive.
|
||||
2. Establish the acquire and resume threads using trace/source evidence.
|
||||
Standard mutexes and SRW locks do not provide a universally queryable owner
|
||||
field; do not fabricate an owning TID from undocumented layouts.
|
||||
3. Verify the awaiter's resumption contract. C++/WinRT can preserve apartment
|
||||
context for particular awaitables; `resume_background` intentionally switches.
|
||||
Do not assume every WinRT awaitable always resumes on a worker or always on
|
||||
the originating thread.
|
||||
4. Distinguish wrong-thread release, a dependency cycle, state changed during
|
||||
suspension, lifetime failure, and unrelated memory corruption.
|
||||
5. Move the thread-affine lock into synchronous scopes. Revalidate relevant
|
||||
state after the await rather than treating the pre-await snapshot as current.
|
||||
|
||||
If the symptom is general blocking use `windbg-user-wait-chain-analysis`. For damaged
|
||||
heap objects use `windbg-user-heap-corruption-investigation`. If a recording is available,
|
||||
`windbg-user-ttd-reverse-debugging-triage` can help establish the ownership timeline.
|
||||
|
||||
## Fix pattern
|
||||
|
||||
Conceptual sequence, not a promise about any particular scheduler:
|
||||
|
||||
```text
|
||||
under lock:
|
||||
take a snapshot and its generation
|
||||
release lock
|
||||
await work using that snapshot
|
||||
under lock on the resumed thread:
|
||||
revalidate generation, lifetime, and assumptions
|
||||
apply result or explicitly handle a stale/cancelled operation
|
||||
release lock
|
||||
```
|
||||
|
||||
Use RAII for each synchronous scope. If invariants cannot tolerate unlocking,
|
||||
redesign the operation or use a specifically designed asynchronous coordination
|
||||
primitive with cancellation/lifetime rules. Switching to a recursive mutex or
|
||||
`shared_mutex` does not make a thread-affine lock coroutine-safe.
|
||||
|
||||
Do not recommend a blanket mutex-type replacement. Shared locking is a separate
|
||||
design decision; changing the primitive does not repair suspension ownership.
|
||||
Keep the object and any captured interfaces alive across asynchronous work.
|
||||
|
||||
## Validation
|
||||
|
||||
- No thread-affine lock ownership survives a suspension in the corrected path.
|
||||
- Each awaiter's thread/apartment contract is understood.
|
||||
- State invariants are revalidated after suspension.
|
||||
- Cancellation, concurrent mutation, shutdown, and failed awaited work are tested.
|
||||
- The remedy removes the demonstrated cause, not just an observed exception.
|
||||
|
||||
## References
|
||||
|
||||
- [Holding a lock across coroutine suspension](https://devblogs.microsoft.com/oldnewthing/20210707-00/?p=105417)
|
||||
- [C++/WinRT concurrency and asynchronous operations](https://learn.microsoft.com/windows/uwp/cpp-and-winrt-apis/concurrency)
|
||||
- [Slim reader/writer locks](https://learn.microsoft.com/windows/win32/sync/slim-reader-writer--srw--locks)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and report reviewed, sanitized feedback to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-user-mutex-held-across-co-await` and the package version from `plugin.json`;
|
||||
no automatic source, dump, or transcript upload.
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
name: windbg-user-ttd-reverse-debugging-triage
|
||||
description: 'Use when an app, service, or user-mode driver host TTD recording is available and earlier calls, writes, or lifetimes matter. Not for kernel replay or history from a normal dump.'
|
||||
---
|
||||
|
||||
# TTD Reverse Debugging 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.
|
||||
|
||||
## Requirements and scope
|
||||
|
||||
Time Travel Debugging records a user-mode process for replay, including an
|
||||
authorized application, service, or user-mode driver host process. A dump alone
|
||||
contains no execution timeline. Confirm a valid recording and matching module
|
||||
symbols before attempting timeline queries. It does not record kernel execution
|
||||
or automatically include another process's server-side activity.
|
||||
|
||||
Recording can change timing, require substantial storage, and capture sensitive
|
||||
memory. Obtain authorization before capture. Check the installed recorder's help
|
||||
for supported target, architecture, and options. WinDbg's **Launch executable
|
||||
(advanced)** / **Record with Time Travel Debugging** flow can record a named
|
||||
test application without guessing a recorder command.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Open and index the recording
|
||||
|
||||
Open the recorded `.run` file in WinDbg and load public Windows symbols and
|
||||
matching PDBs for your own binaries.
|
||||
|
||||
```text
|
||||
!tt.index
|
||||
dx @$cursession.TTD
|
||||
```
|
||||
|
||||
Confirm the timeline range. Indexing and data-model availability depend on
|
||||
WinDbg/TTD versions; consult the installed help if the command is unavailable.
|
||||
|
||||
### 2. Ask a bounded history question
|
||||
|
||||
```text
|
||||
dx @$cursession.TTD.Calls("MyModule!MyFunction")
|
||||
dx @$cursession.TTD.Memory(<start-address>, <end-address>, "w")
|
||||
```
|
||||
|
||||
Query the known function or exact memory range, then inspect relevant results
|
||||
and their timeline positions. An empty result can mean unmatched symbols,
|
||||
uninstrumented execution, or an out-of-range query, not proof of absence.
|
||||
|
||||
Use the call query to find allocation/free or module lifetime transitions and
|
||||
the memory query to locate candidate writes. Account for allocator reuse: the
|
||||
same virtual address may represent different objects over the recording.
|
||||
|
||||
### 3. Seek and inspect state
|
||||
|
||||
```text
|
||||
!tt <position>
|
||||
k
|
||||
r
|
||||
g-
|
||||
```
|
||||
|
||||
Seek to an actual position returned by the query. `g-` continues backward;
|
||||
use the installed reverse-step controls to refine the search. Capture the
|
||||
last-good and first-bad states, writer/caller stack, and ownership transition.
|
||||
|
||||
Do not equate the last write with the bug until you establish the object's
|
||||
identity, valid lifetime, intended invariant, and relevant cross-thread order.
|
||||
|
||||
### 4. Continue with a shipped investigation
|
||||
|
||||
| Evidence | Skill |
|
||||
|---|---|
|
||||
| Bad free/write or allocation-boundary violation | `windbg-user-heap-corruption-investigation` |
|
||||
| Growing allocation/reservation usage | `windbg-user-virtual-memory-exhaustion` |
|
||||
| Lock survives coroutine suspension | `windbg-user-mutex-held-across-co-await` |
|
||||
| Blocker or cross-process dependency at the selected moment | `windbg-user-wait-chain-analysis` |
|
||||
|
||||
For other user-mode families continue reasoning from the timeline rather than
|
||||
dispatching to absent skills. For a kernel crash use `windbg-kernel-bugcheck-triage`;
|
||||
TTD is not a kernel-history substitute.
|
||||
|
||||
## Validation
|
||||
|
||||
Record the question, trace identity, timeline positions, relevant object
|
||||
lifetime, and source/stack evidence. Test alternatives and state recording
|
||||
boundaries. A reproducible timeline proves what occurred in that recording;
|
||||
it does not establish that instrumentation preserved all production timing.
|
||||
|
||||
## References
|
||||
|
||||
- [Time Travel Debugging overview](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/time-travel-debugging-overview)
|
||||
- [TTD data-model queries](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/time-travel-debugging-object-model)
|
||||
- [TTD extension commands](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/time-travel-debugging-extension-commands)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and report a reviewed summary to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-user-ttd-reverse-debugging-triage` and the package version from
|
||||
`plugin.json`; never automatically upload a recording or its memory/query
|
||||
contents.
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: windbg-user-virtual-memory-exhaustion
|
||||
description: 'Use when a native app, service, or user-mode driver host allocation fails; distinguish VA exhaustion, fragmentation, and commit pressure. Not for managed .NET heap growth, proving a leak from one snapshot, or corruption.'
|
||||
---
|
||||
|
||||
# Virtual Memory Exhaustion
|
||||
|
||||
**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
|
||||
|
||||
Investigate `E_OUTOFMEMORY` (`0x8007000E`), `STATUS_NO_MEMORY` (`0xC0000017`),
|
||||
`bad_alloc`, or failed heap/virtual allocations in an application, service, or
|
||||
user-mode driver host (including UMDF). Record the actual API, requested
|
||||
size/alignment, architecture, flags, and error. Free physical RAM does not rule
|
||||
out insufficient virtual address space, commit pressure, or applicable limits.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Examine the process VA map
|
||||
|
||||
```text
|
||||
!address -summary
|
||||
!address
|
||||
!heap -s
|
||||
```
|
||||
|
||||
Compare available regions with the attempted allocation's contiguous range and
|
||||
alignment requirements. Distinguish reserved, committed, free, image, mapped,
|
||||
stack, and heap ranges. A large reservation consumes VA without committing its
|
||||
entire range. Heap internals may require more than the user's requested bytes.
|
||||
|
||||
Report unavailable pages/map data rather than inferring completeness from a
|
||||
limited dump.
|
||||
|
||||
### 2. Separate pressure mechanisms
|
||||
|
||||
| Mechanism | Evidence needed |
|
||||
|---|---|
|
||||
| VA exhaustion | Process address range/architecture and little usable free VA |
|
||||
| Fragmentation | Free space exists, but no suitable contiguous/aligned region |
|
||||
| System commit pressure | Commit usage/limit near the failure, not just free RAM |
|
||||
| Process/job memory limit | Actual configured limit and relevant usage/accounting |
|
||||
| Allocation policy/API failure | API-specific constraints, flags, or allocator policy |
|
||||
|
||||
Use contemporaneous system memory counters or an appropriate live/kernel
|
||||
session for system commit data. A process PEB is not a documented
|
||||
`MaximumCommit` source. A process's committed bytes alone do not establish a
|
||||
system-wide or job limit.
|
||||
|
||||
For 32-bit targets inspect `/LARGEADDRESSAWARE` and the host architecture;
|
||||
2 GB versus up to 4 GB depends on those settings. Verify current documented
|
||||
limits for the target Windows version and architecture instead of applying
|
||||
one 64-bit limit to every system.
|
||||
|
||||
### 3. Identify dominant consumers
|
||||
|
||||
```text
|
||||
!address -f:Heap
|
||||
!address -f:Stack
|
||||
!heap -stat -h <heap-address>
|
||||
```
|
||||
|
||||
Use `!address -?` and `!heap -?` for allocator/version-specific support.
|
||||
Classify dominant heaps, stacks, mappings, images, and reserved arenas.
|
||||
Large or numerous allocations are not automatically leaks: map them to cache
|
||||
policy, owners, workload, and expected lifetimes.
|
||||
|
||||
### 4. Establish growth with history
|
||||
|
||||
Collect authorized time-series counters, repeated comparable snapshots, or
|
||||
allocation/free tracing across the workload. Compare warm-up with steady-state
|
||||
behavior and verify whether memory is reclaimed when work finishes.
|
||||
|
||||
One snapshot plus process uptime cannot prove a leak rate. For a suitable
|
||||
user-mode recording use `windbg-user-ttd-reverse-debugging-triage`; for damaged allocations
|
||||
use `windbg-user-heap-corruption-investigation` instead.
|
||||
|
||||
## Fix patterns
|
||||
|
||||
- Bound caches by an appropriate size/cost policy and verify eviction.
|
||||
Define the lifetime of any references returned before eviction.
|
||||
- Match `VirtualAlloc` reservations with the correct `VirtualFree` release
|
||||
contract; distinguish decommit from release.
|
||||
- Use RAII to release resources on all supported exit/error paths.
|
||||
- Reduce large contiguous allocation requirements where the design permits.
|
||||
- Do not blindly increase limits or stack reservations before finding the
|
||||
pressure source, and do not convert a failed allocation into a silent success.
|
||||
|
||||
## Validation
|
||||
|
||||
Name the failing allocation and pressure mechanism, identify the consumer with
|
||||
evidence, and exercise the remedy through warm-up, sustained load, and cleanup.
|
||||
Verify memory remains bounded or the intended allocation succeeds under the
|
||||
required constraints. Document configured system/job limits separately.
|
||||
|
||||
## References
|
||||
|
||||
- [Address extension](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-address)
|
||||
- [Heap extension](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-heap)
|
||||
- [Windows memory limits](https://learn.microsoft.com/windows/win32/memory/memory-limits-for-windows-releases)
|
||||
- [Large-address-aware linker option](https://learn.microsoft.com/cpp/build/reference/largeaddressaware-handle-large-addresses)
|
||||
- [VirtualFree](https://learn.microsoft.com/windows/win32/api/memoryapi/nf-memoryapi-virtualfree)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and submit reviewed, sanitized feedback to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-user-virtual-memory-exhaustion` and the package version from `plugin.json`;
|
||||
no automatic dump or memory-content upload.
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
name: windbg-user-wait-chain-analysis
|
||||
description: 'Use when an app, service, or user-mode driver host is unresponsive on locks, COM/RPC, I/O, or another process; follow the blocker chain. Not for a crash solely from an exception stack.'
|
||||
---
|
||||
|
||||
# Cross-Process Wait Chain Analysis
|
||||
|
||||
**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
|
||||
|
||||
Look for blocked work in an application, service, or user-mode driver host
|
||||
(including UMDF), and threads in wait, COM, RPC, or I/O paths.
|
||||
The process displaying the symptom may not own the underlying defect.
|
||||
Idle worker threads waiting normally are not evidence of a hang.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Identify the affected operation and its thread
|
||||
|
||||
```text
|
||||
.lastevent
|
||||
~*kb
|
||||
!runaway
|
||||
```
|
||||
|
||||
Confirm why the dump was collected. A dump is a snapshot; `.lastevent` does not
|
||||
by itself certify "hang" or "no crash." Identify the UI/serving thread from
|
||||
application evidence instead of assuming thread zero is always the UI thread.
|
||||
If work is spinning rather than blocked, collect appropriate CPU evidence.
|
||||
|
||||
### 2. Identify each wait and its owner
|
||||
|
||||
Inspect frames around `WaitForSingleObject`, `WaitForMultipleObjects`, COM
|
||||
send/receive, and RPC calls. Use matching symbols/source for your own proxy,
|
||||
interface, and server registration to determine what was requested.
|
||||
|
||||
For each edge record:
|
||||
|
||||
```text
|
||||
process / thread -> waited resource or request -> owner / serving thread
|
||||
```
|
||||
|
||||
Do not guess a server PID from undocumented private COM layouts. Use available
|
||||
Wait Chain Traversal, RPC/COM tracing, application correlation IDs, or
|
||||
registration/process information, and explicitly mark unresolved edges.
|
||||
|
||||
### 3. Gather corresponding server evidence
|
||||
|
||||
Obtain authorized dumps or live state of the relevant server processes close
|
||||
enough in time to represent the same operation. Inspect their serving threads.
|
||||
For kernel context use documented commands such as:
|
||||
|
||||
```text
|
||||
!process 0 7
|
||||
!thread <ethread>
|
||||
```
|
||||
|
||||
Available user pages and symbol/context support vary by dump type. If the chain
|
||||
ends in a kernel lock use `windbg-kernel-lock-deadlock-triage`; if blocked I/O is supported
|
||||
by IRP evidence use `windbg-kernel-irp-lifecycle-triage`. Do not promise process heaps or
|
||||
user stacks absent from the dump.
|
||||
|
||||
### 4. Distinguish a cycle from a slow or missing responder
|
||||
|
||||
- **Cycle:** show every required wait/owner edge back to the starting actor.
|
||||
- **Contention:** a runnable owner may eventually release the resource.
|
||||
- **Starvation:** queued work cannot obtain execution capacity.
|
||||
- **Lost completion:** the actor/event expected to unblock the waiter no
|
||||
longer exists or no path signals it.
|
||||
- **Slow server:** the endpoint is doing work, blocked on another dependency,
|
||||
or looping; gather its evidence before blaming the client.
|
||||
|
||||
Multiple snapshots or tracing may be needed to distinguish transient waits
|
||||
from persistent blocking.
|
||||
|
||||
## Fix patterns and COM boundaries
|
||||
|
||||
A synchronous COM call from an STA can pump messages and permit reentrancy.
|
||||
It is not automatically a deadlock. Investigate locks held across calls,
|
||||
callbacks, apartment access, and any non-pumping waits that form an actual
|
||||
dependency cycle.
|
||||
|
||||
Possible remedies include asynchronous APIs, shorter lock scopes, moving
|
||||
destruction/cross-process calls outside critical sections, and bounded
|
||||
wait/cancellation protocols where the API supports them. A timeout on the
|
||||
caller does not cancel server work by itself.
|
||||
|
||||
If work moves to another apartment, marshal apartment-bound interfaces, keep
|
||||
captured state alive, and dispatch UI updates to the correct thread. Merely
|
||||
capturing a COM pointer and `this` in a worker lambda is not a safe fix.
|
||||
|
||||
## Validation
|
||||
|
||||
Identify the affected thread, relevant resources and owners, and demonstrated
|
||||
cycle or deepest supported blocker. Test the proposed remedy under concurrency,
|
||||
reentrancy, shutdown, and timeout/cancellation. Do not stop at "waiting in RPC."
|
||||
If the server dump or an owner edge is missing, state the unresolved hypothesis.
|
||||
|
||||
## References
|
||||
|
||||
- [Wait Chain Traversal](https://learn.microsoft.com/windows/win32/debug/wait-chain-traversal)
|
||||
- [Processes, threads, and COM apartments](https://learn.microsoft.com/windows/win32/com/processes--threads--and-apartments)
|
||||
- [Process inspection](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-process)
|
||||
- [Thread inspection](https://learn.microsoft.com/windows-hardware/drivers/debuggercmds/-thread)
|
||||
|
||||
## Feedback
|
||||
|
||||
Follow `FEEDBACK.md` and submit only reviewed, sanitized feedback to
|
||||
[WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues).
|
||||
Include `windbg-user-wait-chain-analysis` and the package version from `plugin.json`; no
|
||||
automatic capture or public upload of process dumps or full diagnostic
|
||||
transcripts.
|
||||
Reference in New Issue
Block a user