From bee99ec1cc2722f5a677a06d6b38da9686ca9249 Mon Sep 17 00:00:00 2001 From: Rade Trimceski Date: Wed, 7 Oct 2026 02:13:07 -0700 Subject: [PATCH 1/5] Add debugging diagnostician plugin Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .agents/plugins/marketplace.json | 14 +- .claude-plugin/marketplace.json | 14 +- .github/CODEOWNERS | 1 + .github/plugin/marketplace.json | 8 +- .github/workflows/pr-validation.yml | 10 +- CHANGELOG.md | 8 +- CONTRIBUTING.md | 6 +- README.md | 12 +- .../.claude-plugin/plugin.json | 21 + plugins/debugging-diagnostician/CHANGELOG.md | 12 + plugins/debugging-diagnostician/FEEDBACK.md | 66 ++++ plugins/debugging-diagnostician/README.md | 366 ++++++++++++++++++ .../agents/diagnostician.agent.md | 121 ++++++ .../agents/fleet/contrarian.agent.md | 153 ++++++++ .../diagnostic-reasoning.instructions.md | 74 ++++ .../root-cause-analysis.instructions.md | 44 +++ plugins/debugging-diagnostician/plugin.json | 28 ++ .../scripts/validate-package.mjs | 44 +++ plugins/debugging-diagnostician/skills.json | 21 + .../heap-corruption-investigation/SKILL.md | 120 ++++++ .../skills/kernel-bugcheck-triage/SKILL.md | 125 ++++++ .../skills/km-irp-lifecycle-triage/SKILL.md | 97 +++++ .../skills/km-lock-deadlock-triage/SKILL.md | 101 +++++ .../skills/km-verifier-triage/SKILL.md | 103 +++++ .../mutex-held-across-co-await/SKILL.md | 82 ++++ .../ttd-reverse-debugging-triage/SKILL.md | 100 +++++ .../skills/um-exception-triage/SKILL.md | 94 +++++ .../skills/validate-diagnosis-output/SKILL.md | 171 ++++++++ .../skills/virtual-memory-exhaustion/SKILL.md | 109 ++++++ .../skills/wait-chain-analysis/SKILL.md | 111 ++++++ 30 files changed, 2222 insertions(+), 14 deletions(-) create mode 100644 plugins/debugging-diagnostician/.claude-plugin/plugin.json create mode 100644 plugins/debugging-diagnostician/CHANGELOG.md create mode 100644 plugins/debugging-diagnostician/FEEDBACK.md create mode 100644 plugins/debugging-diagnostician/README.md create mode 100644 plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md create mode 100644 plugins/debugging-diagnostician/com.github.copilot/agents/fleet/contrarian.agent.md create mode 100644 plugins/debugging-diagnostician/com.github.copilot/instructions/diagnostic-reasoning.instructions.md create mode 100644 plugins/debugging-diagnostician/com.github.copilot/instructions/root-cause-analysis.instructions.md create mode 100644 plugins/debugging-diagnostician/plugin.json create mode 100644 plugins/debugging-diagnostician/scripts/validate-package.mjs create mode 100644 plugins/debugging-diagnostician/skills.json create mode 100644 plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md create mode 100644 plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index d198683e..f4829c5f 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -1,9 +1,21 @@ { "name": "win-dev-skills", "interface": { - "displayName": "Windows app development" + "displayName": "Windows development and debugging" }, "plugins": [ + { + "name": "debugging-diagnostician", + "source": { + "source": "local", + "path": "./plugins/debugging-diagnostician" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + }, { "name": "winui", "source": { diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 9ec4ccc5..1bf44165 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -4,9 +4,21 @@ "name": "Microsoft", "url": "https://github.com/microsoft/win-dev-skills" }, - "description": "Agents and skills for Windows app development.", + "description": "Agents and skills for Windows development and debugging.", "version": "0.7.1", "plugins": [ + { + "name": "debugging-diagnostician", + "description": "Ten WinDbg debugging skills plus report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", + "version": "1.0.0", + "source": "./plugins/debugging-diagnostician", + "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" + }, { "name": "winui", "description": "Agents and skills for WinUI 3 app development. Create new WinUI 3 desktop apps, convert from other frameworks to WinUI 3, or add features to existing WinUI 3 applications.", diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a5fa4075..84bb8ade 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -17,3 +17,4 @@ # # winui and winappcli are maintained in microsoft/winappCli and reviewed # there; their catalog entries are covered above. +/plugins/debugging-diagnostician/ @nmetulev @azchohfi @niels9001 @rtrimceski-MS diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 5d6c8fff..8091fa96 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -5,10 +5,16 @@ "url": "https://github.com/microsoft/win-dev-skills" }, "metadata": { - "description": "Agents and skills for Windows app development.", + "description": "Agents and skills for Windows development and debugging.", "version": "0.7.1" }, "plugins": [ + { + "name": "debugging-diagnostician", + "description": "Ten WinDbg debugging skills plus report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", + "version": "1.0.0", + "source": "./plugins/debugging-diagnostician" + }, { "name": "winui", "description": "Agents and skills for WinUI 3 app development. Create new WinUI 3 desktop apps, convert from other frameworks to WinUI 3, or add features to existing WinUI 3 applications.", diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml index 846e84c3..826a23a4 100644 --- a/.github/workflows/pr-validation.yml +++ b/.github/workflows/pr-validation.yml @@ -45,10 +45,14 @@ jobs: # Same linter and version github/awesome-copilot runs on external plugins. # Only plugins stored in this repo are linted; remote plugins are linted # in their own repositories. + - name: Install local plugin lint dependencies + run: npm ci --prefix scripts/vally --no-audit --no-fund + + - name: Check debugging diagnostician package + run: node plugins/debugging-diagnostician/scripts/validate-package.mjs + - name: Lint local plugin skills - run: | - npm ci --prefix scripts/vally --no-audit --no-fund - node scripts/vally/lint-skills.mjs + run: node scripts/vally/lint-skills.mjs # Fixture-based self-test: a plugin stored in this repo is checked and linted. - name: Test catalog tooling diff --git a/CHANGELOG.md b/CHANGELOG.md index 2244eeba..60c76302 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,9 @@ to `## [X.Y.Z] — YYYY-MM-DD` (see RELEASING.md). ### Added +- **`debugging-diagnostician` plugin**: ten selected WinDbg debugging skills, + auxiliary output validation, contrarian/reasoning workflow, and public + WinDbg-Feedback guidance. - **`winappcli` plugin** (WinApp CLI 0.7.1: MSIX packaging, signing, package identity, appxmanifest, Windows SDK setup, Store distribution) for Copilot, Claude Code, and Codex, pinned to microsoft/winappCli `v0.7.1`. Install with @@ -29,8 +32,9 @@ to `## [X.Y.Z] — YYYY-MM-DD` (see RELEASING.md). [microsoft/winappCli](https://github.com/microsoft/winappCli)**, pinned to commit `5a064a42`. Its content is unchanged (still 0.7.1: same name, agent, and eight skills). File WinUI issues and PRs in microsoft/winappCli. -- This repo now hosts and lists agent plugins for Windows app development - ("Agents and skills for Windows app development"). Copilot and Claude Code +- This repo now hosts and lists agent plugins for Windows development and + debugging ("Agents and skills for Windows development and debugging"). + Copilot and Claude Code install commands are unchanged. - **The Codex catalog is renamed from `microsoft-winui` to `win-dev-skills`**, so Codex commands now match the other hosts (`@win-dev-skills`). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 61827f10..1e71e051 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to `win-dev-skills` -This repo hosts agent plugins for Windows app development under +This repo hosts agent plugins for Windows development and debugging under `plugins//`, and also lists plugins maintained in other repos, pinned to a release. You can contribute: @@ -13,8 +13,8 @@ release. You can contribute: ## Bar for inclusion -- **Windows app development.** Building, designing, testing, packaging, or - shipping Windows apps. +- **Windows development and debugging.** Building, designing, testing, + packaging, shipping, or diagnosing Windows apps, services, and drivers. - **Small and curated.** A focused plugin with a few skills that each do one job well, not a dump of prompts. - **Clear descriptions.** Each skill `description` is 300 characters or fewer diff --git a/README.md b/README.md index 487a2184..f58d1420 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,14 @@ -# Agents and skills for Windows app development +# Agents and skills for Windows development and debugging -Agent plugins for building Windows apps with GitHub Copilot, Claude Code, OpenAI Codex, and more. Add this repo as a marketplace once, then install the plugins you need. +Agent plugins for building and debugging Windows software with GitHub Copilot, +Claude Code, OpenAI Codex, and more. Add this repo as a marketplace once, then +install the plugins you need. | Plugin | What it's for | Maintained in | Hosts | |---|---|---|---| | **`winappcli`** | Packaging, signing, and distributing Windows apps with [WinApp CLI](https://github.com/microsoft/winappCli): MSIX, certificates, package identity, appxmanifest, Windows SDK setup, and the Microsoft Store. Works with Electron, .NET, C++, Rust, Flutter, and Tauri. | [microsoft/winappCli](https://github.com/microsoft/winappCli/tree/main/plugins/winapp) | Copilot, Claude Code, Codex, OpenClaw, OpenCode | | **`winui`** | Native Windows apps with **WinUI 3** and the **Windows App SDK**: scaffold, design, build, run, test, package, and ship. | [microsoft/winappCli](https://github.com/microsoft/winappCli/tree/main/plugins/winui) | Copilot, Claude Code, Codex, OpenClaw, OpenCode | +| **`debugging-diagnostician`** | Ten WinDbg debugging skills plus report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers. [Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). | [This repo](plugins/debugging-diagnostician/README.md) | Copilot, Claude Code, Codex, OpenCode | On Codex, OpenClaw, and OpenCode, skills load; agents aren't available. @@ -121,7 +124,10 @@ codex plugin marketplace upgrade win-dev-skills Tags up to `v0.7.1` of this repo contain the `winui` plugin itself, so `https://github.com/microsoft/win-dev-skills.git#v0.7.1` still installs that version. ## Contributing -New plugins and skills for Windows app development are welcome, either as a plugin in this repo under `plugins//` or as a pinned entry for a plugin maintained in another repo. See [`CONTRIBUTING.md`](CONTRIBUTING.md). For catalog or install problems, [open an issue here](https://github.com/microsoft/win-dev-skills/issues). +New plugins and skills for Windows development and debugging are welcome, either +as a plugin in this repo under `plugins//` or as a pinned entry for a +plugin maintained in another repo. See [`CONTRIBUTING.md`](CONTRIBUTING.md). +For catalog or install problems, [open an issue here](https://github.com/microsoft/win-dev-skills/issues). Most contributions require you to agree to a Contributor License Agreement (CLA); see [opensource.microsoft.com/cla](https://opensource.microsoft.com/cla) for details. This project has adopted the [Microsoft Open Source Code of Conduct](CODE_OF_CONDUCT.md). For support channels see [SUPPORT.md](SUPPORT.md), and for responsible disclosure of security issues see [SECURITY.md](SECURITY.md). diff --git a/plugins/debugging-diagnostician/.claude-plugin/plugin.json b/plugins/debugging-diagnostician/.claude-plugin/plugin.json new file mode 100644 index 00000000..03c6d249 --- /dev/null +++ b/plugins/debugging-diagnostician/.claude-plugin/plugin.json @@ -0,0 +1,21 @@ +{ + "name": "debugging-diagnostician", + "version": "1.0.0", + "description": "Ten WinDbg debugging skills plus 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" + ] +} diff --git a/plugins/debugging-diagnostician/CHANGELOG.md b/plugins/debugging-diagnostician/CHANGELOG.md new file mode 100644 index 00000000..35e5d798 --- /dev/null +++ b/plugins/debugging-diagnostician/CHANGELOG.md @@ -0,0 +1,12 @@ +# Changelog + +## 1.0.0 - Initial contribution + +- Included exactly ten selected debugging skills. +- Added the auxiliary `validate-diagnosis-output` skill, contrarian agent, + and two reasoning instruction files 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. diff --git a/plugins/debugging-diagnostician/FEEDBACK.md b/plugins/debugging-diagnostician/FEEDBACK.md new file mode 100644 index 00000000..94ba3cd8 --- /dev/null +++ b/plugins/debugging-diagnostician/FEEDBACK.md @@ -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][] ` + +```markdown +### Skill and version +Plugin: debugging-diagnostician +Package version: +Skill: + +### Category and verdict +Category: +My verdict: + +### Expected behavior + + +### Observed behavior + + +### Environment + + +### Suggested improvement + +``` + +Only include information the user approves for public disclosure. There is no +bundled uploader, credential store, private share, or notification service. diff --git a/plugins/debugging-diagnostician/README.md b/plugins/debugging-diagnostician/README.md new file mode 100644 index 00000000..bb7fec9f --- /dev/null +++ b/plugins/debugging-diagnostician/README.md @@ -0,0 +1,366 @@ +# 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 a reasoning-first hypothesis-test-pivot method with exactly **ten debugging skills**, plus the auxiliary `validate-diagnosis-output` skill, contrarian reviewer, and reasoning instructions required for the complete workflow. 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. + +Package version: **1.0.0**. + +## Install + +Install from the catalog: + +```powershell +copilot plugin marketplace add microsoft/win-dev-skills +copilot plugin install debugging-diagnostician@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: +``` + +You can also invoke a skill directly on a skill-capable host: + +```text +Use 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//.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 auxiliary `validate-diagnosis-output` 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": "one of the ten skills, 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 inventory is `skills.json`: ten debugging skills and one auxiliary output validator. + +#### User-mode: applications, services, and user-mode drivers (including UMDF) + +| Skill | Use it for | +|---|---| +| `um-exception-triage` | Establish exception context and classify native process crashes, including user-mode driver host failures. | +| `heap-corruption-investigation` | Investigate use-after-free, double-free, and overruns in applications, services, or user-mode driver hosts. | +| `wait-chain-analysis` | Follow application, service, user-mode driver, COM/RPC, and process waits to a supported blocker or cycle. | +| `ttd-reverse-debugging-triage` | Find earlier writes, frees, and calls in a recorded user-mode process, including a user-mode driver host. | +| `virtual-memory-exhaustion` | Separate address-space pressure, fragmentation, commit pressure, and applicable limits. | +| `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 | +|---|---| +| `kernel-bugcheck-triage` | Decode bugchecks and recover original exception or trap context. | +| `km-verifier-triage` | Interpret Driver Verifier violations and available I/O verification evidence. | +| `km-irp-lifecycle-triage` | Investigate outstanding I/O, completion/cancel ownership, and power IRPs. | +| `km-lock-deadlock-triage` | Build supported kernel owner/waiter graphs and investigate lock-order inversions. | + +Trap-frame and exception-context recovery are included in +`kernel-bugcheck-triage`, not additional skills. Feedback guidance and the +optional agent are support content, not an eleventh diagnostic skill. + +No specialized C++ thrown-object or XAML stowed-exception decoder is included. `um-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. | + +### Auxiliary skill + +| Skill | Purpose | +|---|---| +| `validate-diagnosis-output` | Deterministically checks the complete report structure after the contrarian review. | + +## 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/fleet/contrarian.agent.md` | Independent adversarial review agent. | +| `com.github.copilot/instructions/*.instructions.md` | Five-phase reasoning, routing, evidence, output, and privacy contracts. | +| `skills//SKILL.md` | Ten debugging skills plus the auxiliary output validator. | +| `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 auxiliary validator is explicitly +inventoried and is not a debugging 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. diff --git a/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md b/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md new file mode 100644 index 00000000..a0b58efa --- /dev/null +++ b/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md @@ -0,0 +1,121 @@ +--- +name: diagnostician +description: Diagnose native Windows application, service, user-mode driver (including UMDF), and kernel-mode driver failures using ten public WinDbg skills. +--- + +# Debugging Diagnostician + +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 | `um-exception-triage` | +| Application, service, or user-mode driver host heap corruption/history | `heap-corruption-investigation` | +| Blocked UI, service, user-mode driver host, COM/RPC, or thread/process wait | `wait-chain-analysis` | +| A recorded application, service, or user-mode driver host execution with a history question | `ttd-reverse-debugging-triage` | +| User-mode allocation failure, VA fragmentation, or commit pressure | `virtual-memory-exhaustion` | +| Thread-affine lock surviving coroutine suspension in a user-mode component | `mutex-held-across-co-await` | +| Kernel bugcheck, trap frame, or saved exception context | `kernel-bugcheck-triage` | +| Driver Verifier violation | `km-verifier-triage` | +| Outstanding/power IRP, cancellation, or completion | `km-irp-lifecycle-triage` | +| Kernel lock owner/waiter chain | `km-lock-deadlock-triage` | + +The six user-mode skills apply to native applications, services, and user-mode +drivers such as UMDF drivers running in a user-mode host process. The four +kernel-mode skills apply to kernel-mode drivers. These ten skills are 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 `fleet/contrarian.agent.md` 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 and apply + `validate-diagnosis-output`. Correct structural failures 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//.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`. +Run `validate-diagnosis-output` 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. diff --git a/plugins/debugging-diagnostician/com.github.copilot/agents/fleet/contrarian.agent.md b/plugins/debugging-diagnostician/com.github.copilot/agents/fleet/contrarian.agent.md new file mode 100644 index 00000000..4b890c85 --- /dev/null +++ b/plugins/debugging-diagnostician/com.github.copilot/agents/fleet/contrarian.agent.md @@ -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 (Diagnostician Fleet) + +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 the Fix-Confidence Calibration table in `diagnostic-reasoning.instructions.md`: +- ≥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.] +``` diff --git a/plugins/debugging-diagnostician/com.github.copilot/instructions/diagnostic-reasoning.instructions.md b/plugins/debugging-diagnostician/com.github.copilot/instructions/diagnostic-reasoning.instructions.md new file mode 100644 index 00000000..5ac20fff --- /dev/null +++ b/plugins/debugging-diagnostician/com.github.copilot/instructions/diagnostic-reasoning.instructions.md @@ -0,0 +1,74 @@ +# Diagnostic Reasoning Instructions + +## Five phases + +1. **OBSERVE**: establish dump/trace type, architecture, symbols, code, stack, + registers, thread/resource state, and missing evidence. +2. **HYPOTHESIZE**: form a primary mechanism and at least two plausible + alternatives when the evidence permits. +3. **TEST**: identify direct debugger/source/repro 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 | +|---|---| +| User-mode exception in an app, service, or UMDF/user-mode driver host | `um-exception-triage` | +| User-mode heap corruption or allocation/free history | `heap-corruption-investigation` | +| Cross-thread/process, COM/RPC, or service wait | `wait-chain-analysis` | +| User-mode TTD history question | `ttd-reverse-debugging-triage` | +| User-mode VA fragmentation, allocation failure, or commit pressure | `virtual-memory-exhaustion` | +| Thread-affine lock across coroutine suspension | `mutex-held-across-co-await` | +| Kernel bugcheck, trap frame, or saved context | `kernel-bugcheck-triage` | +| Driver Verifier violation | `km-verifier-triage` | +| Outstanding/power IRP, completion, or cancellation | `km-irp-lifecycle-triage` | +| Kernel lock owner/waiter chain | `km-lock-deadlock-triage` | +| Structural report validation | `validate-diagnosis-output` | + +These are the complete skills. Continue general evidence-led reasoning for +unsupported families; never dispatch to an absent skill. + +## Routing paths + +- **Fast (indicative confidence ≥0.8)**: validate the pattern and alternatives. +- **Validate (0.4–0.79)**: test the leading pattern plus alternatives. +- **Full reasoning (<0.4/no match)**: reason from observations and preserve + uncertainty. + +Confidence is judgment, not measured probability. + +## 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. + +## Trigger and fix gates + +- Verify the trigger condition in dump, disassembly, source, or controlled repro + before declaring a final fix. +- A fix must restore the violated invariant, not merely suppress the reproducer. +- Fix confidence of 0.90 or higher requires reading the actual code path in + this session. +- If the trigger is unverified, use candidate-pending-verification, null fix, + and name the evidence/fix matrix required. + +## Output contract + +A full report contains: Analysis, Root Cause, Fix, Reasoning Chain, +Alternatives Considered, Trigger Verification table, Mermaid, Contrarian +Verdict, and JSON Output Contract Summary. Mermaid must reflect verified +evidence and use valid VS Code syntax. Run the independent contrarian once, then +the structural validator. A second challenge ends as pending verification. diff --git a/plugins/debugging-diagnostician/com.github.copilot/instructions/root-cause-analysis.instructions.md b/plugins/debugging-diagnostician/com.github.copilot/instructions/root-cause-analysis.instructions.md new file mode 100644 index 00000000..478078a7 --- /dev/null +++ b/plugins/debugging-diagnostician/com.github.copilot/instructions/root-cause-analysis.instructions.md @@ -0,0 +1,44 @@ +# Root-Cause Analysis Instructions + +## Evidence ladder + +Prefer direct evidence in this order: + +1. Faulting instruction/context, bugcheck/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. + +## 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. + +## Quality bar + +- Name the violated invariant and the parties/path that violate it. +- Separate detector/victim from original writer/freeing/holding actor. +- Test alternatives with direct evidence. +- Do not blame a module solely from a bucket or `MODULE_NAME`. +- Never claim commands, source access, or artifacts unavailable to the session. +- State whether the conclusion is final or pending verification and why. + +## 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/Page Heap can disrupt workloads and must use a recoverable +test plan and restoration steps. Public feedback follows `FEEDBACK.md` and +defaults to a minimal reviewed summary with no automatic attachments. diff --git a/plugins/debugging-diagnostician/plugin.json b/plugins/debugging-diagnostician/plugin.json new file mode 100644 index 00000000..31bda672 --- /dev/null +++ b/plugins/debugging-diagnostician/plugin.json @@ -0,0 +1,28 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "debugging-diagnostician", + "version": "1.0.0", + "description": "Ten WinDbg debugging skills plus 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", + "instructions": "./com.github.copilot/instructions" + } + } +} diff --git a/plugins/debugging-diagnostician/scripts/validate-package.mjs b/plugins/debugging-diagnostician/scripts/validate-package.mjs new file mode 100644 index 00000000..81d819a7 --- /dev/null +++ b/plugins/debugging-diagnostician/scripts/validate-package.mjs @@ -0,0 +1,44 @@ +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import {createRequire} from "node:module"; +import {fileURLToPath} from "node:url"; +const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),".."); +const targetRoot=process.env.WIN_DEV_SKILLS_ROOT?path.resolve(process.env.WIN_DEV_SKILLS_ROOT):path.resolve(root,"..",".."); +const require=createRequire(path.join(targetRoot,"scripts","vally","package.json")); +const {parseDocument}=require("yaml"); +const inventory=JSON.parse(fs.readFileSync(path.join(root,"skills.json"),"utf8")); +assert.equal(inventory.diagnosticSkillCount,10); +assert.equal(inventory.auxiliarySkillCount,1); +assert.deepEqual(inventory.auxiliarySkills,["validate-diagnosis-output"]); +const allowed=[...inventory.diagnosticSkills,...inventory.auxiliarySkills].sort(); +const dirs=fs.readdirSync(path.join(root,"skills"),{withFileTypes:true}).filter(e=>e.isDirectory()).map(e=>e.name).sort(); +assert.deepEqual(dirs,allowed); +const allowedUrlHosts=new Set(["agent-plugins.org","devblogs.microsoft.com","github.com","learn.microsoft.com"]); +function assertPublicText(text,label){ + for(const match of text.matchAll(/https?:\/\/[^\s<>"'`]+/g)){ + const value=match[0].replace(/[),.;:]+$/,""); + const host=new URL(value).hostname.toLowerCase(); + assert.ok(allowedUrlHosts.has(host),label+" references unapproved URL host "+host); + } + assert.doesNotMatch(text,/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i,label+" contains an email address"); +} +for(const id of dirs){ + const text=fs.readFileSync(path.join(root,"skills",id,"SKILL.md"),"utf8"); + const m=/^---\r?\n([\s\S]*?)\r?\n---/.exec(text);assert.ok(m,id); + const doc=parseDocument(m[1],{uniqueKeys:true});assert.equal(doc.errors.length,0,id); + const h=doc.toJS();assert.equal(h.name,id);assert.ok(!("owner" in h));assert.ok(!("metadata" in h)); + assertPublicText(text,id); +} +assert.ok(!fs.existsSync(path.join(root,".mcp.json"))); +assert.ok(!fs.existsSync(path.join(root,"mcp"))); +for(const rel of ["README.md","FEEDBACK.md","com.github.copilot/agents/diagnostician.agent.md","com.github.copilot/agents/fleet/contrarian.agent.md","com.github.copilot/instructions/diagnostic-reasoning.instructions.md","com.github.copilot/instructions/root-cause-analysis.instructions.md"]){ + const text=fs.readFileSync(path.join(root,rel),"utf8"); + assertPublicText(text,rel); +} +for(const rel of ["README.md","com.github.copilot/agents/diagnostician.agent.md","com.github.copilot/agents/fleet/contrarian.agent.md","com.github.copilot/instructions/diagnostic-reasoning.instructions.md","skills/validate-diagnosis-output/SKILL.md"]){ + const text=fs.readFileSync(path.join(root,rel),"utf8"); + assert.match(text,/fix_confidence/,rel+" omits fix_confidence"); + assert.match(text,/fix_code_path_coverage/,rel+" omits fix_code_path_coverage"); +} +console.log("Validated ten debugging skills, one auxiliary validator, complete agent workflow, and public-only links."); diff --git a/plugins/debugging-diagnostician/skills.json b/plugins/debugging-diagnostician/skills.json new file mode 100644 index 00000000..44e2050f --- /dev/null +++ b/plugins/debugging-diagnostician/skills.json @@ -0,0 +1,21 @@ +{ + "name": "debugging-diagnostician", + "version": "1.0.0", + "diagnosticSkillCount": 10, + "auxiliarySkillCount": 1, + "diagnosticSkills": [ + "um-exception-triage", + "heap-corruption-investigation", + "wait-chain-analysis", + "ttd-reverse-debugging-triage", + "virtual-memory-exhaustion", + "mutex-held-across-co-await", + "kernel-bugcheck-triage", + "km-verifier-triage", + "km-irp-lifecycle-triage", + "km-lock-deadlock-triage" + ], + "auxiliarySkills": [ + "validate-diagnosis-output" + ] +} diff --git a/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md b/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md new file mode 100644 index 00000000..c71d294f --- /dev/null +++ b/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md @@ -0,0 +1,120 @@ +--- +name: 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.' +version: 1.0.0 +--- + +# Heap Corruption Investigation + +## 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 +`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 ` 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
+!avrf -hp -a
+``` + +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
L` 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 `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 `heap-corruption-investigation` and package version `1.0.0`; no automatic +dump, source, or transcript upload. diff --git a/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md b/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md new file mode 100644 index 00000000..5afdfcc4 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md @@ -0,0 +1,125 @@ +--- +name: 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.' +version: 1.0.0 +--- + +# Kernel Bugcheck Triage + +## 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+ +.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 `km-irp-lifecycle-triage` where applicable. | +| Verifier-class stop | Use `km-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 +.cxr +kb +r +``` + +For `0x3B`: + +```text +.cxr +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 +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 +.frame /r +``` + +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 `km-lock-deadlock-triage` or +`km-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 +`km-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 `kernel-bugcheck-triage` and package version `1.0.0`; no automatic kernel +dump, private-symbol, or source upload. diff --git a/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md b/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md new file mode 100644 index 00000000..fdd00d72 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md @@ -0,0 +1,97 @@ +--- +name: km-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.' +version: 1.0.0 +--- + +# IRP Lifecycle Triage + +## 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 +``` + +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 | `km-verifier-triage` | +| Owner/waiter kernel lock chain | `km-lock-deadlock-triage` | +| Exception or trap during request handling | `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 `km-irp-lifecycle-triage` and package version `1.0.0`; no automatic kernel +dump or request-content upload. diff --git a/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md b/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md new file mode 100644 index 00000000..792a3ba3 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md @@ -0,0 +1,101 @@ +--- +name: km-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.' +version: 1.0.0 +--- + +# Kernel Lock and Deadlock Triage + +## 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 +!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 `km-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 `km-irp-lifecycle-triage`; if a chain crosses into a +user-mode COM/RPC operation use `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 `km-lock-deadlock-triage` and package version `1.0.0`; no automatic dump, +lock-history transcript, or driver-source upload. diff --git a/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md b/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md new file mode 100644 index 00000000..1370c2c0 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md @@ -0,0 +1,103 @@ +--- +name: km-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.' +version: 1.0.0 +--- + +# Driver Verifier Triage + +## Scope + +Driver Verifier checks kernel driver contracts. Application Verifier is a +different user-mode facility; use `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 +``` + +Shadow state may preserve information lost from the live request. Correlate it +with the decoded contract and use `km-irp-lifecycle-triage` for completion, +cancellation, pending state, and ownership. + +### 3. Recover context or follow dependencies + +- Saved exception/trap context: `kernel-bugcheck-triage`. +- Lock-order evidence: `km-lock-deadlock-triage`. +- Outstanding or power request: `km-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 `km-verifier-triage` and package version `1.0.0`; do not automatically +upload dumps or proprietary driver source. diff --git a/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md b/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md new file mode 100644 index 00000000..ccec0a47 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md @@ -0,0 +1,82 @@ +--- +name: 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.' +version: 1.0.0 +--- + +# Mutex Held Across co_await + +## 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 `wait-chain-analysis`. For damaged +heap objects use `heap-corruption-investigation`. If a recording is available, +`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 `mutex-held-across-co-await` and package version `1.0.0`; no automatic +source, dump, or transcript upload. diff --git a/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md b/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md new file mode 100644 index 00000000..987bbb02 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md @@ -0,0 +1,100 @@ +--- +name: 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.' +version: 1.0.0 +--- + +# TTD Reverse Debugging Triage + +## 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(, , "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 +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 | `heap-corruption-investigation` | +| Growing allocation/reservation usage | `virtual-memory-exhaustion` | +| Lock survives coroutine suspension | `mutex-held-across-co-await` | +| Blocker or cross-process dependency at the selected moment | `wait-chain-analysis` | + +For other user-mode families continue reasoning from the timeline rather than +dispatching to absent skills. For a kernel crash use `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 `ttd-reverse-debugging-triage` and package version `1.0.0`; never +automatically upload a recording or its memory/query contents. diff --git a/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md b/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md new file mode 100644 index 00000000..0c19b0fa --- /dev/null +++ b/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md @@ -0,0 +1,94 @@ +--- +name: um-exception-triage +description: 'Use when an app, service, or user-mode driver host (including UMDF) crashes with a structured exception; establish context and classify it. Not for kernel bugchecks or a complete C++/XAML decoder.' +version: 1.0.0 +--- + +# User-Mode Exception Triage + +## 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 | `heap-corruption-investigation` | +| `0xC0000374` heap corruption | `heap-corruption-investigation` | +| `0xC0000017`, `0x8007000E`, or an allocation-failure path | `virtual-memory-exhaustion` | +| Lock/unlock failure following coroutine suspension | `mutex-held-across-co-await` | +| A TTD recording is available and earlier mutation is in question | `ttd-reverse-debugging-triage` | +| No crash exception and evidence of blocked work | `wait-chain-analysis` | +| A kernel dump reports a bugcheck | `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 `um-exception-triage` and package version `1.0.0`; do not upload dumps or +private source automatically. diff --git a/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md b/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md new file mode 100644 index 00000000..44012a22 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md @@ -0,0 +1,171 @@ +--- +name: validate-diagnosis-output +description: Use after a Diagnostician report is written to verify required sections, trigger evidence, Mermaid, contrarian verdict, and JSON summary. Not for judging whether the diagnosis is technically correct. +version: 1.0.0 +user-invocable: false +--- +# Validate Diagnosis Output + +Deterministic, no-LLM structural validator that the **Debugging Diagnostician +agent** runs against the markdown report it just wrote, before calling +`final completion`. It enforces the agent's stated Output Contract in +`diagnostician.agent.md` so direct-invocation deliverables can't silently ship +without the required artifacts. + +## When to Use + +- Called by the Diagnostician agent **after** writing the diagnosis markdown + to `/.diagnoses//.md`. +- Called **before** rendering the Pre-Completion Checklist and `final completion`. +- May be invoked by a user explicitly to re-validate an existing diagnosis md + ("re-run validate-diagnosis-output against "). + +## What It Checks + +The validator is a structural / regex scan — no semantic judgment. Each check is +binary pass/fail. The full list: + +| # | Check | Pass when | +|---|---|---| +| 1 | **Analysis** section | The markdown contains a heading matching `^##\s+Analysis\b` | +| 2 | **Root Cause** section | Heading matches `^##\s+Root Cause\b` | +| 3 | **Fix** section | Heading matches `^##\s+Fix\b` *(may be a routing recommendation when status is `candidate-pending-verification`)* | +| 4 | **Reasoning Chain** | Heading matches `^##\s+Reasoning Chain\b` AND contains at least one of `OBSERVE`, `HYPOTHESIZE`, `TEST`, `EVALUATE`, `CONCLUDE` | +| 5 | **Alternatives Considered** | Heading matches `^##\s+Alternatives\b` AND the section body contains ≥2 list items (bulleted or numbered) | +| 6 | **Trigger Verification** | Heading matches `^##\s+Trigger Verification\b` AND a markdown table follows with at least one row whose cells include either `VERIFIED`, `UNVERIFIED`, or `verified by` | +| 7 | **Mermaid sequence diagram** | Body contains a fenced block opened by ` ```mermaid` AND closed by ` ``` `, AND the block's content contains either `sequenceDiagram` or `flowchart` AND ≥2 `participant ` or node declarations | +| 8 | **Contrarian Verdict** | Heading matches `^##\s+Contrarian Verdict\b` AND the body contains `ACCEPTED` or `CHALLENGED` AND a `contrarian_loopback: (true|false)` or `**contrarian_loopback**` reference | +| 9 | **JSON Output Contract Summary** | A fenced ` ```json` block exists containing the keys `diagnosis_status`, `routing_path`, `root_cause`, `confidence`, `fix_confidence`, `fix_code_path_coverage`, `contrarian_review`, and `contrarian_loopback` | + +A single check failing means the diagnosis is **incomplete**; the agent must +loop back and fix it before completing. + +## Anti-Patterns the Validator Catches + +These are the exact failure modes observed in real CLI sessions that motivated +this skill: + +- ❌ Producing a long chat-only diagnosis with no markdown file written to + `.diagnoses/` (Output Contract violation). +- ❌ Skipping the mermaid block ("the analysis is mostly textual, the diagram + felt redundant"). The agent.md says it is mandatory; the validator refuses + to pass without it. +- ❌ Putting devil's-advocate prose inline and calling it "contrarian review" + without actually invoking the contrarian sub-agent via the task tool. + Validator only checks structure (verdict line exists), but the agent + constraint that the contrarian be a real sub-agent run still applies. +- ❌ Dropping the `contrarian_loopback` line when the contrarian returned + `CHALLENGED`. This is a workflow violation per `diagnostician.agent.md`. +- ❌ "Diagnosis status: final" with `Trigger Verification: UNVERIFIED` — + inconsistent state. Validator surfaces both rows; agent must reconcile. + +## Reference Implementation (PowerShell, embedded) + +The skill is implementation-light by design — the agent itself runs the check +inline. This snippet is the canonical reference; agents may reproduce its +logic in whatever way matches their runtime. + +```powershell +param([Parameter(Mandatory=$true)][string]$Path) +if (-not (Test-Path $Path)) { throw "diagnosis file not found: $Path" } +$content = Get-Content -Raw -Path $Path +$lines = Get-Content -Path $Path + +function HasHeading($pattern) { ($lines | Select-String -Pattern $pattern).Count -gt 0 } +function MermaidBlock { + $start = [regex]::Match($content, '(?m)^```mermaid\s*$') + if (-not $start.Success) { return $null } + $rest = $content.Substring($start.Index + $start.Length) + $end = [regex]::Match($rest, '(?m)^```\s*$') + if (-not $end.Success) { return $null } + return $rest.Substring(0, $end.Index) +} + +$results = [ordered]@{} +$results.AnalysisHeading = HasHeading '^##\s+Analysis\b' +$results.RootCauseHeading = HasHeading '^##\s+Root Cause\b' +$results.FixHeading = HasHeading '^##\s+Fix\b' +$results.ReasoningChainHeading = HasHeading '^##\s+Reasoning Chain\b' -and ($content -match 'OBSERVE|HYPOTHESIZE|TEST|EVALUATE|CONCLUDE') +$results.AlternativesHeading = HasHeading '^##\s+Alternatives\b' +$results.TriggerVerification = HasHeading '^##\s+Trigger Verification\b' -and ($content -match 'VERIFIED|UNVERIFIED|verified by') + +$mermaid = MermaidBlock +$results.MermaidDiagram = $null -ne $mermaid -and ( + ($mermaid -match 'sequenceDiagram' -or $mermaid -match 'flowchart') -and + ([regex]::Matches($mermaid, '(?m)^\s*(participant\s|[A-Za-z0-9_]+\s*-->)').Count -ge 2) +) + +$results.ContrarianVerdict = HasHeading '^##\s+Contrarian Verdict\b' -and + ($content -match 'ACCEPTED|CHALLENGED') -and + ($content -match 'contrarian_loopback') + +$jsonBlocks = [regex]::Matches($content, '(?s)```json\s*(.*?)```') +$results.JsonSummary = $false +foreach ($m in $jsonBlocks) { + $body = $m.Groups[1].Value + if ($body -match '"diagnosis_status"' -and + $body -match '"routing_path"' -and + $body -match '"root_cause"' -and + $body -match '"confidence"' -and + $body -match '"fix_confidence"' -and + $body -match '"fix_code_path_coverage"' -and + $body -match '"contrarian_review"' -and + $body -match '"contrarian_loopback"') { + $results.JsonSummary = $true; break + } +} + +$pass = -not ($results.Values | Where-Object { $_ -eq $false }) +[pscustomobject]@{ Pass = $pass; File = $Path; Checks = $results } +``` + +## Output Format + +The validator returns a small object (or its markdown equivalent): + +```json +{ + "pass": false, + "file": "C:\\p\\repo\\.diagnoses\\sample-crash-12345\\20260512-145200.md", + "checks": { + "AnalysisHeading": true, + "RootCauseHeading": true, + "FixHeading": true, + "ReasoningChainHeading": true, + "AlternativesHeading": true, + "TriggerVerification": true, + "MermaidDiagram": false, + "ContrarianVerdict": true, + "JsonSummary": true + } +} +``` + +The agent maps each check to a row of the Pre-Completion Checklist: + +| Check (JSON key) | Checklist row | +|---|---| +| `AnalysisHeading` | Analysis section | +| `RootCauseHeading` | Root Cause section | +| `FixHeading` | Fix section | +| `ReasoningChainHeading` | Reasoning Chain | +| `AlternativesHeading` | Alternatives Considered (≥2) | +| `TriggerVerification` | Trigger Verification table | +| `MermaidDiagram` | Mermaid sequence diagram | +| `ContrarianVerdict` | Contrarian Verdict | +| `JsonSummary` | JSON Output Contract Summary | + +## Completion Criteria + +A diagnosis is "structurally complete" when all 9 checks pass. The agent MUST +NOT call `final completion` while any check is failing; instead it must produce +the missing content, re-run the validator, and re-render the checklist. + +This skill does NOT replace the semantic constraints in `diagnostician.agent.md` +(e.g. "the contrarian sub-agent must be a real task-tool invocation, not +inline prose"). It enforces the **structural** floor; semantic correctness +remains the agent's responsibility. + +## Feedback + +For feedback about this validator, follow the package `FEEDBACK.md`. Do not attach private diagnosis files automatically. diff --git a/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md b/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md new file mode 100644 index 00000000..7606a4f2 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md @@ -0,0 +1,109 @@ +--- +name: virtual-memory-exhaustion +description: 'Use when an app, service, or user-mode driver host allocation fails; distinguish VA exhaustion, fragmentation, and commit pressure. Not for proving a leak from one snapshot or corruption.' +version: 1.0.0 +--- + +# Virtual Memory Exhaustion + +## 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 +``` + +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 `ttd-reverse-debugging-triage`; for damaged allocations +use `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 `virtual-memory-exhaustion` and package version `1.0.0`; no automatic +dump or memory-content upload. diff --git a/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md b/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md new file mode 100644 index 00000000..9eb5ef0e --- /dev/null +++ b/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md @@ -0,0 +1,111 @@ +--- +name: 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.' +version: 1.0.0 +--- + +# Cross-Process Wait Chain Analysis + +## 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 +``` + +Available user pages and symbol/context support vary by dump type. If the chain +ends in a kernel lock use `km-lock-deadlock-triage`; if blocked I/O is supported +by IRP evidence use `km-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 `wait-chain-analysis` and package version `1.0.0`; no automatic capture +or public upload of process dumps or full diagnostic transcripts. From 23448155cf73fb9144a5fc9cb866f241feb78c0c Mon Sep 17 00:00:00 2001 From: Rade Trimceski Date: Wed, 7 Oct 2026 10:59:22 -0700 Subject: [PATCH 2/5] Address clear diagnostician review feedback Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .claude-plugin/marketplace.json | 2 +- .github/plugin/marketplace.json | 2 +- .github/workflows/pr-validation.yml | 5 +- CHANGELOG.md | 9 +- README.md | 2 +- .../.claude-plugin/plugin.json | 2 +- plugins/debugging-diagnostician/CHANGELOG.md | 2 +- plugins/debugging-diagnostician/README.md | 18 +- .../agents/{fleet => }/contrarian.agent.md | 4 +- .../agents/diagnostician.agent.md | 24 +- plugins/debugging-diagnostician/plugin.json | 2 +- .../scripts/validate-package.mjs | 44 ---- plugins/debugging-diagnostician/skills.json | 2 - .../heap-corruption-investigation/SKILL.md | 5 +- .../skills/kernel-bugcheck-triage/SKILL.md | 5 +- .../skills/km-irp-lifecycle-triage/SKILL.md | 5 +- .../skills/km-lock-deadlock-triage/SKILL.md | 5 +- .../skills/km-verifier-triage/SKILL.md | 5 +- .../mutex-held-across-co-await/SKILL.md | 5 +- .../ttd-reverse-debugging-triage/SKILL.md | 6 +- .../skills/um-exception-triage/SKILL.md | 7 +- .../skills/validate-diagnosis-output/SKILL.md | 206 +++++------------- .../scripts/validate-diagnosis-output.ps1 | 169 ++++++++++++++ .../skills/virtual-memory-exhaustion/SKILL.md | 7 +- .../skills/wait-chain-analysis/SKILL.md | 6 +- ...test-debugging-diagnostician-validator.mjs | 134 ++++++++++++ scripts/validate-debugging-diagnostician.mjs | 130 +++++++++++ 27 files changed, 549 insertions(+), 264 deletions(-) rename plugins/debugging-diagnostician/com.github.copilot/agents/{fleet => }/contrarian.agent.md (98%) delete mode 100644 plugins/debugging-diagnostician/scripts/validate-package.mjs create mode 100644 plugins/debugging-diagnostician/skills/validate-diagnosis-output/scripts/validate-diagnosis-output.ps1 create mode 100644 scripts/tests/test-debugging-diagnostician-validator.mjs create mode 100644 scripts/validate-debugging-diagnostician.mjs diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1bf44165..1fd5f709 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ "plugins": [ { "name": "debugging-diagnostician", - "description": "Ten WinDbg debugging skills plus report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", + "description": "WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", "version": "1.0.0", "source": "./plugins/debugging-diagnostician", "author": { diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 8091fa96..a660dbd4 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -11,7 +11,7 @@ "plugins": [ { "name": "debugging-diagnostician", - "description": "Ten WinDbg debugging skills plus report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", + "description": "WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", "version": "1.0.0", "source": "./plugins/debugging-diagnostician" }, diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml index 826a23a4..18d366d2 100644 --- a/.github/workflows/pr-validation.yml +++ b/.github/workflows/pr-validation.yml @@ -49,7 +49,10 @@ jobs: run: npm ci --prefix scripts/vally --no-audit --no-fund - name: Check debugging diagnostician package - run: node plugins/debugging-diagnostician/scripts/validate-package.mjs + run: node scripts/validate-debugging-diagnostician.mjs + + - name: Test debugging diagnostician validator + run: node scripts/tests/test-debugging-diagnostician-validator.mjs - name: Lint local plugin skills run: node scripts/vally/lint-skills.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index e725c76d..545606bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,9 +14,9 @@ to `## [X.Y.Z] — YYYY-MM-DD` (see RELEASING.md). ### Added -- **`debugging-diagnostician` plugin**: ten selected WinDbg debugging skills, - auxiliary output validation, contrarian/reasoning workflow, and public - WinDbg-Feedback guidance. +- **`debugging-diagnostician` plugin**: focused WinDbg diagnosis workflows, + auxiliary output validation, contrarian review, and public WinDbg-Feedback + guidance. - **`winappcli` plugin** (WinApp CLI 0.7.1: MSIX packaging, signing, package identity, appxmanifest, Windows SDK setup, Store distribution) for Copilot, Claude Code, and Codex, pinned to microsoft/winappCli `v0.7.1`. Install with @@ -37,8 +37,7 @@ to `## [X.Y.Z] — YYYY-MM-DD` (see RELEASING.md). and eight skills). File WinUI issues and PRs in microsoft/winappCli. - This repo now hosts and lists agent plugins for Windows development and debugging ("Agents and skills for Windows development and debugging"). - Copilot and Claude Code - install commands are unchanged. + Copilot and Claude Code install commands are unchanged. - **The Codex catalog is renamed from `microsoft-winui` to `win-dev-skills`**, so Codex commands now match the other hosts (`@win-dev-skills`). diff --git a/README.md b/README.md index cdb647a2..43663785 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Agent plugins for Windows development and debugging—from apps and services to |---|---|---|---| | **`winappcli`** | Packaging, signing, and distributing Windows apps with [WinApp CLI](https://github.com/microsoft/winappCli): MSIX, certificates, package identity, appxmanifest, Windows SDK setup, and the Microsoft Store. Works with Electron, .NET, C++, Rust, Flutter, and Tauri. | [microsoft/winappCli](https://github.com/microsoft/winappCli/tree/main/plugins/winapp) | Copilot, Claude Code, Codex, OpenClaw, OpenCode | | **`winui`** | Native Windows apps with **WinUI 3** and the **Windows App SDK**: scaffold, design, build, run, test, package, and ship. | [microsoft/winappCli](https://github.com/microsoft/winappCli/tree/main/plugins/winui) | Copilot, Claude Code, Codex, OpenClaw, OpenCode | -| **`debugging-diagnostician`** | Ten WinDbg debugging skills plus report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers. [Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). | [This repo](plugins/debugging-diagnostician/README.md) | Copilot, Claude Code, Codex, OpenCode | +| **`debugging-diagnostician`** | WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers. [Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). | [This repo](plugins/debugging-diagnostician/README.md) | Copilot, Claude Code, Codex, OpenCode | On Codex, OpenClaw, and OpenCode, skills load; agents aren't available. diff --git a/plugins/debugging-diagnostician/.claude-plugin/plugin.json b/plugins/debugging-diagnostician/.claude-plugin/plugin.json index 03c6d249..c6a3bd51 100644 --- a/plugins/debugging-diagnostician/.claude-plugin/plugin.json +++ b/plugins/debugging-diagnostician/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "debugging-diagnostician", "version": "1.0.0", - "description": "Ten WinDbg debugging skills plus report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", + "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" diff --git a/plugins/debugging-diagnostician/CHANGELOG.md b/plugins/debugging-diagnostician/CHANGELOG.md index 35e5d798..62feef33 100644 --- a/plugins/debugging-diagnostician/CHANGELOG.md +++ b/plugins/debugging-diagnostician/CHANGELOG.md @@ -2,7 +2,7 @@ ## 1.0.0 - Initial contribution -- Included exactly ten selected debugging skills. +- Included the curated debugging skill inventory in `skills.json`. - Added the auxiliary `validate-diagnosis-output` skill, contrarian agent, and two reasoning instruction files required for the complete workflow. - Kept the runtime package limited to the inventory in `skills.json`. diff --git a/plugins/debugging-diagnostician/README.md b/plugins/debugging-diagnostician/README.md index bb7fec9f..a7757d60 100644 --- a/plugins/debugging-diagnostician/README.md +++ b/plugins/debugging-diagnostician/README.md @@ -4,9 +4,13 @@ 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 a reasoning-first hypothesis-test-pivot method with exactly **ten debugging skills**, plus the auxiliary `validate-diagnosis-output` skill, contrarian reviewer, and reasoning instructions required for the complete workflow. 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. - -Package version: **1.0.0**. +This public edition combines a reasoning-first hypothesis-test-pivot method +with focused user-mode and kernel-mode debugging skills, the auxiliary +`validate-diagnosis-output` skill, a contrarian reviewer, and reasoning +instructions for the complete workflow. 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 @@ -217,7 +221,7 @@ public feedback issue. Diagnostic input can remain local to the approved session "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": "one of the ten skills, or null", + "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", @@ -229,7 +233,7 @@ public feedback issue. Diagnostic input can remain local to the approved session ### Debugging Skills (`skills/`) -The authoritative inventory is `skills.json`: ten debugging skills and one auxiliary output validator. +The authoritative skill inventory is `skills.json`. #### User-mode: applications, services, and user-mode drivers (including UMDF) @@ -285,9 +289,9 @@ These are starting hypotheses, never automatic diagnoses: | `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/fleet/contrarian.agent.md` | Independent adversarial review agent. | +| `com.github.copilot/agents/contrarian.agent.md` | Independent adversarial review agent. | | `com.github.copilot/instructions/*.instructions.md` | Five-phase reasoning, routing, evidence, output, and privacy contracts. | -| `skills//SKILL.md` | Ten debugging skills plus the auxiliary output validator. | +| `skills//SKILL.md` | Debugging skills plus the auxiliary output validator. | | `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. | diff --git a/plugins/debugging-diagnostician/com.github.copilot/agents/fleet/contrarian.agent.md b/plugins/debugging-diagnostician/com.github.copilot/agents/contrarian.agent.md similarity index 98% rename from plugins/debugging-diagnostician/com.github.copilot/agents/fleet/contrarian.agent.md rename to plugins/debugging-diagnostician/com.github.copilot/agents/contrarian.agent.md index 4b890c85..b91906e1 100644 --- a/plugins/debugging-diagnostician/com.github.copilot/agents/fleet/contrarian.agent.md +++ b/plugins/debugging-diagnostician/com.github.copilot/agents/contrarian.agent.md @@ -5,7 +5,7 @@ tools: [] user-invocable: false --- -# Contrarian (Diagnostician Fleet) +# 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. @@ -73,7 +73,7 @@ Ask: if a different caller hits the same invariant violation through a different ### 5. Fix-Confidence Calibration Violation -The diagnostician's fix confidence must comply with the Fix-Confidence Calibration table in `diagnostic-reasoning.instructions.md`: +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` diff --git a/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md b/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md index a0b58efa..97e875ba 100644 --- a/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md +++ b/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md @@ -1,6 +1,6 @@ --- name: diagnostician -description: Diagnose native Windows application, service, user-mode driver (including UMDF), and kernel-mode driver failures using ten public WinDbg skills. +description: Diagnose native Windows application, service, user-mode driver (including UMDF), and kernel-mode driver failures with public WinDbg workflows. --- # Debugging Diagnostician @@ -49,10 +49,10 @@ Confidence is explanatory judgment, not measured probability. | Outstanding/power IRP, cancellation, or completion | `km-irp-lifecycle-triage` | | Kernel lock owner/waiter chain | `km-lock-deadlock-triage` | -The six user-mode skills apply to native applications, services, and user-mode -drivers such as UMDF drivers running in a user-mode host process. The four -kernel-mode skills apply to kernel-mode drivers. These ten skills are the -complete inventory. No specialized C++ thrown-object +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. @@ -76,15 +76,16 @@ Use these only to generate testable alternatives: Before finalizing a full diagnosis: -1. Invoke the bundled `fleet/contrarian.agent.md` as an independent sub-agent +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 and apply - `validate-diagnosis-output`. Correct structural failures before finalizing. +4. Write the diagnosis report when filesystem access is available, then apply + `validate-diagnosis-output` by running its bundled PowerShell script. Correct + structural failures and re-run the script before finalizing. ## Output @@ -102,9 +103,10 @@ available, write `./.diagnoses//.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`. -Run `validate-diagnosis-output` against the report. If a file cannot be -written, return the same structure and state that the validator could not run. +and missing evidence plus fix validation. Record `contrarian_loopback` as the +Boolean `true` or `false`. Run `validate-diagnosis-output` against the report. +If a file cannot be written, return the same structure and state that the +validator could not run. ## Safety and feedback diff --git a/plugins/debugging-diagnostician/plugin.json b/plugins/debugging-diagnostician/plugin.json index 31bda672..f611a084 100644 --- a/plugins/debugging-diagnostician/plugin.json +++ b/plugins/debugging-diagnostician/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "debugging-diagnostician", "version": "1.0.0", - "description": "Ten WinDbg debugging skills plus report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", + "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" diff --git a/plugins/debugging-diagnostician/scripts/validate-package.mjs b/plugins/debugging-diagnostician/scripts/validate-package.mjs deleted file mode 100644 index 81d819a7..00000000 --- a/plugins/debugging-diagnostician/scripts/validate-package.mjs +++ /dev/null @@ -1,44 +0,0 @@ -import assert from "node:assert/strict"; -import fs from "node:fs"; -import path from "node:path"; -import {createRequire} from "node:module"; -import {fileURLToPath} from "node:url"; -const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),".."); -const targetRoot=process.env.WIN_DEV_SKILLS_ROOT?path.resolve(process.env.WIN_DEV_SKILLS_ROOT):path.resolve(root,"..",".."); -const require=createRequire(path.join(targetRoot,"scripts","vally","package.json")); -const {parseDocument}=require("yaml"); -const inventory=JSON.parse(fs.readFileSync(path.join(root,"skills.json"),"utf8")); -assert.equal(inventory.diagnosticSkillCount,10); -assert.equal(inventory.auxiliarySkillCount,1); -assert.deepEqual(inventory.auxiliarySkills,["validate-diagnosis-output"]); -const allowed=[...inventory.diagnosticSkills,...inventory.auxiliarySkills].sort(); -const dirs=fs.readdirSync(path.join(root,"skills"),{withFileTypes:true}).filter(e=>e.isDirectory()).map(e=>e.name).sort(); -assert.deepEqual(dirs,allowed); -const allowedUrlHosts=new Set(["agent-plugins.org","devblogs.microsoft.com","github.com","learn.microsoft.com"]); -function assertPublicText(text,label){ - for(const match of text.matchAll(/https?:\/\/[^\s<>"'`]+/g)){ - const value=match[0].replace(/[),.;:]+$/,""); - const host=new URL(value).hostname.toLowerCase(); - assert.ok(allowedUrlHosts.has(host),label+" references unapproved URL host "+host); - } - assert.doesNotMatch(text,/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i,label+" contains an email address"); -} -for(const id of dirs){ - const text=fs.readFileSync(path.join(root,"skills",id,"SKILL.md"),"utf8"); - const m=/^---\r?\n([\s\S]*?)\r?\n---/.exec(text);assert.ok(m,id); - const doc=parseDocument(m[1],{uniqueKeys:true});assert.equal(doc.errors.length,0,id); - const h=doc.toJS();assert.equal(h.name,id);assert.ok(!("owner" in h));assert.ok(!("metadata" in h)); - assertPublicText(text,id); -} -assert.ok(!fs.existsSync(path.join(root,".mcp.json"))); -assert.ok(!fs.existsSync(path.join(root,"mcp"))); -for(const rel of ["README.md","FEEDBACK.md","com.github.copilot/agents/diagnostician.agent.md","com.github.copilot/agents/fleet/contrarian.agent.md","com.github.copilot/instructions/diagnostic-reasoning.instructions.md","com.github.copilot/instructions/root-cause-analysis.instructions.md"]){ - const text=fs.readFileSync(path.join(root,rel),"utf8"); - assertPublicText(text,rel); -} -for(const rel of ["README.md","com.github.copilot/agents/diagnostician.agent.md","com.github.copilot/agents/fleet/contrarian.agent.md","com.github.copilot/instructions/diagnostic-reasoning.instructions.md","skills/validate-diagnosis-output/SKILL.md"]){ - const text=fs.readFileSync(path.join(root,rel),"utf8"); - assert.match(text,/fix_confidence/,rel+" omits fix_confidence"); - assert.match(text,/fix_code_path_coverage/,rel+" omits fix_code_path_coverage"); -} -console.log("Validated ten debugging skills, one auxiliary validator, complete agent workflow, and public-only links."); diff --git a/plugins/debugging-diagnostician/skills.json b/plugins/debugging-diagnostician/skills.json index 44e2050f..bf6285bd 100644 --- a/plugins/debugging-diagnostician/skills.json +++ b/plugins/debugging-diagnostician/skills.json @@ -1,8 +1,6 @@ { "name": "debugging-diagnostician", "version": "1.0.0", - "diagnosticSkillCount": 10, - "auxiliarySkillCount": 1, "diagnosticSkills": [ "um-exception-triage", "heap-corruption-investigation", diff --git a/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md b/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md index c71d294f..1756089a 100644 --- a/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md +++ b/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md @@ -1,7 +1,6 @@ --- name: 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.' -version: 1.0.0 --- # Heap Corruption Investigation @@ -116,5 +115,5 @@ Report unresolved writer history rather than presenting a guessed fix as proven. Follow `FEEDBACK.md` and report reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `heap-corruption-investigation` and package version `1.0.0`; no automatic -dump, source, or transcript upload. +Include `heap-corruption-investigation` and the package version from +`plugin.json`; no automatic dump, source, or transcript upload. diff --git a/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md b/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md index 5afdfcc4..dc6d7ae8 100644 --- a/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md +++ b/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md @@ -1,7 +1,6 @@ --- name: 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.' -version: 1.0.0 --- # Kernel Bugcheck Triage @@ -121,5 +120,5 @@ an instrumented test/repro only with approval; route Verifier evidence to Follow `FEEDBACK.md` and submit only reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `kernel-bugcheck-triage` and package version `1.0.0`; no automatic kernel -dump, private-symbol, or source upload. +Include `kernel-bugcheck-triage` and the package version from `plugin.json`; no +automatic kernel dump, private-symbol, or source upload. diff --git a/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md b/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md index fdd00d72..fa5a7783 100644 --- a/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md +++ b/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md @@ -1,7 +1,6 @@ --- name: km-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.' -version: 1.0.0 --- # IRP Lifecycle Triage @@ -93,5 +92,5 @@ which driver lost the completion. Follow `FEEDBACK.md` and report only reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `km-irp-lifecycle-triage` and package version `1.0.0`; no automatic kernel -dump or request-content upload. +Include `km-irp-lifecycle-triage` and the package version from `plugin.json`; no +automatic kernel dump or request-content upload. diff --git a/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md b/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md index 792a3ba3..f2e2469d 100644 --- a/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md +++ b/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md @@ -1,7 +1,6 @@ --- name: km-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.' -version: 1.0.0 --- # Kernel Lock and Deadlock Triage @@ -97,5 +96,5 @@ Separate a demonstrated fix from an unproven contention hypothesis. Follow `FEEDBACK.md` and report reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `km-lock-deadlock-triage` and package version `1.0.0`; no automatic dump, -lock-history transcript, or driver-source upload. +Include `km-lock-deadlock-triage` and the package version from `plugin.json`; no +automatic dump, lock-history transcript, or driver-source upload. diff --git a/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md b/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md index 1370c2c0..f758cdb8 100644 --- a/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md +++ b/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md @@ -1,7 +1,6 @@ --- name: km-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.' -version: 1.0.0 --- # Driver Verifier Triage @@ -99,5 +98,5 @@ single repro is not proof that every driver path is safe. Follow `FEEDBACK.md` and submit reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `km-verifier-triage` and package version `1.0.0`; do not automatically -upload dumps or proprietary driver source. +Include `km-verifier-triage` and the package version from `plugin.json`; do not +automatically upload dumps or proprietary driver source. diff --git a/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md b/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md index ccec0a47..7423831a 100644 --- a/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md +++ b/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md @@ -1,7 +1,6 @@ --- name: 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.' -version: 1.0.0 --- # Mutex Held Across co_await @@ -78,5 +77,5 @@ Keep the object and any captured interfaces alive across asynchronous work. Follow `FEEDBACK.md` and report reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `mutex-held-across-co-await` and package version `1.0.0`; no automatic -source, dump, or transcript upload. +Include `mutex-held-across-co-await` and the package version from `plugin.json`; +no automatic source, dump, or transcript upload. diff --git a/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md b/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md index 987bbb02..24d1b54b 100644 --- a/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md +++ b/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md @@ -1,7 +1,6 @@ --- name: 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.' -version: 1.0.0 --- # TTD Reverse Debugging Triage @@ -96,5 +95,6 @@ it does not establish that instrumentation preserved all production timing. Follow `FEEDBACK.md` and report a reviewed summary to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `ttd-reverse-debugging-triage` and package version `1.0.0`; never -automatically upload a recording or its memory/query contents. +Include `ttd-reverse-debugging-triage` and the package version from +`plugin.json`; never automatically upload a recording or its memory/query +contents. diff --git a/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md b/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md index 0c19b0fa..00b6d680 100644 --- a/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md +++ b/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md @@ -1,7 +1,6 @@ --- name: um-exception-triage -description: 'Use when an app, service, or user-mode driver host (including UMDF) crashes with a structured exception; establish context and classify it. Not for kernel bugchecks or a complete C++/XAML decoder.' -version: 1.0.0 +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; establish context and classify it. Not for managed .NET exceptions, WinUI/XAML app errors, or kernel bugchecks.' --- # User-Mode Exception Triage @@ -90,5 +89,5 @@ type, faulting instruction, object layout, and valid allocation boundaries. 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 `um-exception-triage` and package version `1.0.0`; do not upload dumps or -private source automatically. +Include `um-exception-triage` and the package version from `plugin.json`; do not +upload dumps or private source automatically. diff --git a/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md b/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md index 44012a22..eefe80c6 100644 --- a/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md +++ b/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md @@ -1,171 +1,69 @@ --- name: validate-diagnosis-output description: Use after a Diagnostician report is written to verify required sections, trigger evidence, Mermaid, contrarian verdict, and JSON summary. Not for judging whether the diagnosis is technically correct. -version: 1.0.0 user-invocable: false --- # Validate Diagnosis Output -Deterministic, no-LLM structural validator that the **Debugging Diagnostician -agent** runs against the markdown report it just wrote, before calling -`final completion`. It enforces the agent's stated Output Contract in -`diagnostician.agent.md` so direct-invocation deliverables can't silently ship -without the required artifacts. - -## When to Use - -- Called by the Diagnostician agent **after** writing the diagnosis markdown - to `/.diagnoses//.md`. -- Called **before** rendering the Pre-Completion Checklist and `final completion`. -- May be invoked by a user explicitly to re-validate an existing diagnosis md - ("re-run validate-diagnosis-output against "). - -## What It Checks - -The validator is a structural / regex scan — no semantic judgment. Each check is -binary pass/fail. The full list: - -| # | Check | Pass when | -|---|---|---| -| 1 | **Analysis** section | The markdown contains a heading matching `^##\s+Analysis\b` | -| 2 | **Root Cause** section | Heading matches `^##\s+Root Cause\b` | -| 3 | **Fix** section | Heading matches `^##\s+Fix\b` *(may be a routing recommendation when status is `candidate-pending-verification`)* | -| 4 | **Reasoning Chain** | Heading matches `^##\s+Reasoning Chain\b` AND contains at least one of `OBSERVE`, `HYPOTHESIZE`, `TEST`, `EVALUATE`, `CONCLUDE` | -| 5 | **Alternatives Considered** | Heading matches `^##\s+Alternatives\b` AND the section body contains ≥2 list items (bulleted or numbered) | -| 6 | **Trigger Verification** | Heading matches `^##\s+Trigger Verification\b` AND a markdown table follows with at least one row whose cells include either `VERIFIED`, `UNVERIFIED`, or `verified by` | -| 7 | **Mermaid sequence diagram** | Body contains a fenced block opened by ` ```mermaid` AND closed by ` ``` `, AND the block's content contains either `sequenceDiagram` or `flowchart` AND ≥2 `participant ` or node declarations | -| 8 | **Contrarian Verdict** | Heading matches `^##\s+Contrarian Verdict\b` AND the body contains `ACCEPTED` or `CHALLENGED` AND a `contrarian_loopback: (true|false)` or `**contrarian_loopback**` reference | -| 9 | **JSON Output Contract Summary** | A fenced ` ```json` block exists containing the keys `diagnosis_status`, `routing_path`, `root_cause`, `confidence`, `fix_confidence`, `fix_code_path_coverage`, `contrarian_review`, and `contrarian_loopback` | - -A single check failing means the diagnosis is **incomplete**; the agent must -loop back and fix it before completing. - -## Anti-Patterns the Validator Catches - -These are the exact failure modes observed in real CLI sessions that motivated -this skill: - -- ❌ Producing a long chat-only diagnosis with no markdown file written to - `.diagnoses/` (Output Contract violation). -- ❌ Skipping the mermaid block ("the analysis is mostly textual, the diagram - felt redundant"). The agent.md says it is mandatory; the validator refuses - to pass without it. -- ❌ Putting devil's-advocate prose inline and calling it "contrarian review" - without actually invoking the contrarian sub-agent via the task tool. - Validator only checks structure (verdict line exists), but the agent - constraint that the contrarian be a real sub-agent run still applies. -- ❌ Dropping the `contrarian_loopback` line when the contrarian returned - `CHALLENGED`. This is a workflow violation per `diagnostician.agent.md`. -- ❌ "Diagnosis status: final" with `Trigger Verification: UNVERIFIED` — - inconsistent state. Validator surfaces both rows; agent must reconcile. - -## Reference Implementation (PowerShell, embedded) - -The skill is implementation-light by design — the agent itself runs the check -inline. This snippet is the canonical reference; agents may reproduce its -logic in whatever way matches their runtime. +Use this skill after the Diagnostician writes a report to +`/.diagnoses//.md`. + +The bundled +[`validate-diagnosis-output.ps1`](scripts/validate-diagnosis-output.ps1) +performs deterministic structural validation. It does not judge whether the +technical diagnosis is correct. + +## Run the validator + +Run the script with PowerShell 7: ```powershell -param([Parameter(Mandatory=$true)][string]$Path) -if (-not (Test-Path $Path)) { throw "diagnosis file not found: $Path" } -$content = Get-Content -Raw -Path $Path -$lines = Get-Content -Path $Path - -function HasHeading($pattern) { ($lines | Select-String -Pattern $pattern).Count -gt 0 } -function MermaidBlock { - $start = [regex]::Match($content, '(?m)^```mermaid\s*$') - if (-not $start.Success) { return $null } - $rest = $content.Substring($start.Index + $start.Length) - $end = [regex]::Match($rest, '(?m)^```\s*$') - if (-not $end.Success) { return $null } - return $rest.Substring(0, $end.Index) -} - -$results = [ordered]@{} -$results.AnalysisHeading = HasHeading '^##\s+Analysis\b' -$results.RootCauseHeading = HasHeading '^##\s+Root Cause\b' -$results.FixHeading = HasHeading '^##\s+Fix\b' -$results.ReasoningChainHeading = HasHeading '^##\s+Reasoning Chain\b' -and ($content -match 'OBSERVE|HYPOTHESIZE|TEST|EVALUATE|CONCLUDE') -$results.AlternativesHeading = HasHeading '^##\s+Alternatives\b' -$results.TriggerVerification = HasHeading '^##\s+Trigger Verification\b' -and ($content -match 'VERIFIED|UNVERIFIED|verified by') - -$mermaid = MermaidBlock -$results.MermaidDiagram = $null -ne $mermaid -and ( - ($mermaid -match 'sequenceDiagram' -or $mermaid -match 'flowchart') -and - ([regex]::Matches($mermaid, '(?m)^\s*(participant\s|[A-Za-z0-9_]+\s*-->)').Count -ge 2) -) - -$results.ContrarianVerdict = HasHeading '^##\s+Contrarian Verdict\b' -and - ($content -match 'ACCEPTED|CHALLENGED') -and - ($content -match 'contrarian_loopback') - -$jsonBlocks = [regex]::Matches($content, '(?s)```json\s*(.*?)```') -$results.JsonSummary = $false -foreach ($m in $jsonBlocks) { - $body = $m.Groups[1].Value - if ($body -match '"diagnosis_status"' -and - $body -match '"routing_path"' -and - $body -match '"root_cause"' -and - $body -match '"confidence"' -and - $body -match '"fix_confidence"' -and - $body -match '"fix_code_path_coverage"' -and - $body -match '"contrarian_review"' -and - $body -match '"contrarian_loopback"') { - $results.JsonSummary = $true; break - } -} - -$pass = -not ($results.Values | Where-Object { $_ -eq $false }) -[pscustomobject]@{ Pass = $pass; File = $Path; Checks = $results } +pwsh -NoProfile -File \scripts\validate-diagnosis-output.ps1 ` + -Path ``` -## Output Format - -The validator returns a small object (or its markdown equivalent): - -```json -{ - "pass": false, - "file": "C:\\p\\repo\\.diagnoses\\sample-crash-12345\\20260512-145200.md", - "checks": { - "AnalysisHeading": true, - "RootCauseHeading": true, - "FixHeading": true, - "ReasoningChainHeading": true, - "AlternativesHeading": true, - "TriggerVerification": true, - "MermaidDiagram": false, - "ContrarianVerdict": true, - "JsonSummary": true - } -} -``` +Use the installed skill directory for ``. The script emits a +JSON result and exits nonzero when any check fails. -The agent maps each check to a row of the Pre-Completion Checklist: +## Checks -| Check (JSON key) | Checklist row | +| Check | Requirement | |---|---| -| `AnalysisHeading` | Analysis section | -| `RootCauseHeading` | Root Cause section | -| `FixHeading` | Fix section | -| `ReasoningChainHeading` | Reasoning Chain | -| `AlternativesHeading` | Alternatives Considered (≥2) | -| `TriggerVerification` | Trigger Verification table | -| `MermaidDiagram` | Mermaid sequence diagram | -| `ContrarianVerdict` | Contrarian Verdict | -| `JsonSummary` | JSON Output Contract Summary | - -## Completion Criteria - -A diagnosis is "structurally complete" when all 9 checks pass. The agent MUST -NOT call `final completion` while any check is failing; instead it must produce -the missing content, re-run the validator, and re-render the checklist. - -This skill does NOT replace the semantic constraints in `diagnostician.agent.md` -(e.g. "the contrarian sub-agent must be a real task-tool invocation, not -inline prose"). It enforces the **structural** floor; semantic correctness -remains the agent's responsibility. +| Analysis | An `## Analysis` section exists. | +| Root Cause | An `## Root Cause` section exists. | +| Fix | An `## Fix` section exists. | +| Reasoning Chain | Its section contains at least one phase marker: `OBSERVE`, `HYPOTHESIZE`, `TEST`, `EVALUATE`, or `CONCLUDE`. | +| Alternatives | Its section contains at least two bulleted or numbered alternatives. | +| Trigger Verification | Its section contains a Markdown table and a `VERIFIED`, `UNVERIFIED`, or `verified by` status. | +| Mermaid | A sequence diagram names or implicitly uses at least two actors, or a flowchart has at least two connected nodes. | +| Contrarian Verdict | Its section contains `ACCEPTED` or `CHALLENGED` and a Boolean `contrarian_loopback: true\|false`. | +| JSON summary | A parseable JSON block contains the required output-contract properties and a Boolean `contrarian_loopback`. | + +The required JSON properties are: + +- `diagnosis_status` +- `routing_path` +- `root_cause` +- `confidence` +- `fix_confidence` +- `fix_code_path_coverage` +- `contrarian_review` +- `contrarian_loopback` + +## Completion criteria + +When validation fails: + +1. Read the `Checks` object in the script output. +2. Correct only the missing or malformed report sections. +3. Re-run the script. +4. Do not present the report as structurally complete until every check passes. + +Structural validation does not replace semantic review. The diagnostician must +still invoke the independent `contrarian` agent through the host's agent +mechanism and respond to a challenged verdict. ## Feedback -For feedback about this validator, follow the package `FEEDBACK.md`. Do not attach private diagnosis files automatically. +For feedback about this validator, follow the package `FEEDBACK.md`. Do not +attach private diagnosis files automatically. diff --git a/plugins/debugging-diagnostician/skills/validate-diagnosis-output/scripts/validate-diagnosis-output.ps1 b/plugins/debugging-diagnostician/skills/validate-diagnosis-output/scripts/validate-diagnosis-output.ps1 new file mode 100644 index 00000000..7248b926 --- /dev/null +++ b/plugins/debugging-diagnostician/skills/validate-diagnosis-output/scripts/validate-diagnosis-output.ps1 @@ -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(?.*?)(?=^##\s+|\z)" + return [regex]::Match($content, $pattern) +} + +function Test-MermaidDiagram { + $blocks = [regex]::Matches($content, '(?ims)^```mermaid\s*\r?\n(?.*?)^```\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*(?.*?)```')) { + 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 +} diff --git a/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md b/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md index 7606a4f2..852f4392 100644 --- a/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md +++ b/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md @@ -1,7 +1,6 @@ --- name: virtual-memory-exhaustion -description: 'Use when an app, service, or user-mode driver host allocation fails; distinguish VA exhaustion, fragmentation, and commit pressure. Not for proving a leak from one snapshot or corruption.' -version: 1.0.0 +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 @@ -105,5 +104,5 @@ required constraints. Document configured system/job limits separately. Follow `FEEDBACK.md` and submit reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `virtual-memory-exhaustion` and package version `1.0.0`; no automatic -dump or memory-content upload. +Include `virtual-memory-exhaustion` and the package version from `plugin.json`; +no automatic dump or memory-content upload. diff --git a/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md b/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md index 9eb5ef0e..6b6c366a 100644 --- a/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md +++ b/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md @@ -1,7 +1,6 @@ --- name: 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.' -version: 1.0.0 --- # Cross-Process Wait Chain Analysis @@ -107,5 +106,6 @@ If the server dump or an owner edge is missing, state the unresolved hypothesis. Follow `FEEDBACK.md` and submit only reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `wait-chain-analysis` and package version `1.0.0`; no automatic capture -or public upload of process dumps or full diagnostic transcripts. +Include `wait-chain-analysis` and the package version from `plugin.json`; no +automatic capture or public upload of process dumps or full diagnostic +transcripts. diff --git a/scripts/tests/test-debugging-diagnostician-validator.mjs b/scripts/tests/test-debugging-diagnostician-validator.mjs new file mode 100644 index 00000000..7c76043a --- /dev/null +++ b/scripts/tests/test-debugging-diagnostician-validator.mjs @@ -0,0 +1,134 @@ +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { spawnSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const repositoryRoot = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + "..", + "..", +); +const validator = path.join( + repositoryRoot, + "plugins", + "debugging-diagnostician", + "skills", + "validate-diagnosis-output", + "scripts", + "validate-diagnosis-output.ps1", +); +const temporaryDirectory = fs.mkdtempSync( + path.join(os.tmpdir(), "diagnosis-validator-"), +); + +const validReport = `## Analysis +Observed evidence. + +## Root Cause +Candidate cause. + +## Fix +Candidate fix. + +## Reasoning Chain +OBSERVE: evidence. + +## Alternatives Considered +- Alternative one +- Alternative two + +## Trigger Verification +| Evidence | Status | +|---|---| +| Trigger | VERIFIED | + +## Mermaid +\`\`\`mermaid +sequenceDiagram +A->>B: request +B-->>A: response +\`\`\` + +## Contrarian Verdict +ACCEPTED + +contrarian_loopback: false + +## JSON Output Contract Summary +\`\`\`json +{"diagnosis_status":"final","routing_path":"validate","root_cause":"cause","confidence":0.8,"fix_confidence":0.7,"fix_code_path_coverage":"symbol-or-disassembly","contrarian_review":"ACCEPTED","contrarian_loopback":false} +\`\`\` +`; + +const invalidReport = `## Analysis +The words OBSERVE and VERIFIED appear outside their required sections. + +## Root Cause +Candidate cause. + +## Fix +Candidate fix. + +## Reasoning Chain +No phase marker appears here. + +## Alternatives Considered +- Only one alternative + +## Trigger Verification +No table appears here. + +## Mermaid +\`\`\`mermaid +sequenceDiagram +participant A +\`\`\` + +## Contrarian Verdict +ACCEPTED + +contrarian_loopback: 1 + +## JSON Output Contract Summary +\`\`\`json +{"diagnosis_status":"final","routing_path":"validate","root_cause":"cause","confidence":0.8,"fix_confidence":0.7,"fix_code_path_coverage":"symbol-or-disassembly","contrarian_review":"ACCEPTED","contrarian_loopback":1} +\`\`\` +`; + +function runValidator(file) { + return spawnSync( + "pwsh", + ["-NoProfile", "-File", validator, "-Path", file], + { encoding: "utf8" }, + ); +} + +try { + const validPath = path.join(temporaryDirectory, "valid.md"); + const invalidPath = path.join(temporaryDirectory, "invalid.md"); + fs.writeFileSync(validPath, validReport); + fs.writeFileSync(invalidPath, invalidReport); + + const validResult = runValidator(validPath); + assert.equal(validResult.status, 0, validResult.stderr || validResult.stdout); + const validOutput = JSON.parse(validResult.stdout); + assert.equal(validOutput.Pass, true); + assert.equal(validOutput.Checks.MermaidDiagram, true); + + const invalidResult = runValidator(invalidPath); + assert.equal(invalidResult.status, 1, invalidResult.stderr); + const invalidOutput = JSON.parse(invalidResult.stdout); + assert.equal(invalidOutput.Pass, false); + assert.equal(invalidOutput.Checks.ReasoningChain, false); + assert.equal(invalidOutput.Checks.Alternatives, false); + assert.equal(invalidOutput.Checks.TriggerVerification, false); + assert.equal(invalidOutput.Checks.MermaidDiagram, false); + assert.equal(invalidOutput.Checks.ContrarianVerdict, false); + assert.equal(invalidOutput.Checks.JsonSummary, false); + + console.log("Diagnosis validator accepts valid reports and rejects malformed sections."); +} finally { + fs.rmSync(temporaryDirectory, { recursive: true, force: true }); +} diff --git a/scripts/validate-debugging-diagnostician.mjs b/scripts/validate-debugging-diagnostician.mjs new file mode 100644 index 00000000..a295546c --- /dev/null +++ b/scripts/validate-debugging-diagnostician.mjs @@ -0,0 +1,130 @@ +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import { createRequire } from "node:module"; +import { fileURLToPath } from "node:url"; + +const repositoryRoot = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + "..", +); +const pluginRoot = path.join( + repositoryRoot, + "plugins", + "debugging-diagnostician", +); +const require = createRequire( + path.join(repositoryRoot, "scripts", "vally", "package.json"), +); +const { parseDocument } = require("yaml"); + +const inventory = JSON.parse( + fs.readFileSync(path.join(pluginRoot, "skills.json"), "utf8"), +); +assert.deepEqual(inventory.auxiliarySkills, ["validate-diagnosis-output"]); + +const allowedSkills = [ + ...inventory.diagnosticSkills, + ...inventory.auxiliarySkills, +].sort(); +const skillDirectories = fs + .readdirSync(path.join(pluginRoot, "skills"), { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name) + .sort(); +assert.deepEqual(skillDirectories, allowedSkills); + +const allowedUrlHosts = new Set([ + "agent-plugins.org", + "devblogs.microsoft.com", + "github.com", + "learn.microsoft.com", +]); + +function assertPublicText(text, label) { + for (const match of text.matchAll(/https?:\/\/[^\s<>"'`]+/g)) { + const value = match[0].replace(/[),.;:]+$/, ""); + const host = new URL(value).hostname.toLowerCase(); + assert.ok( + allowedUrlHosts.has(host), + `${label} references unapproved URL host ${host}`, + ); + } + + assert.doesNotMatch( + text, + /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i, + `${label} contains an email address`, + ); +} + +for (const skill of skillDirectories) { + const relativePath = path.join("skills", skill, "SKILL.md"); + const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); + const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text); + assert.ok(frontmatter, relativePath); + + const document = parseDocument(frontmatter[1], { uniqueKeys: true }); + assert.equal(document.errors.length, 0, relativePath); + + const header = document.toJS(); + assert.equal(header.name, skill); + assert.ok(!("owner" in header)); + assert.ok(!("metadata" in header)); + assert.ok(!("version" in header)); + assertPublicText(text, relativePath); +} + +assert.ok(!fs.existsSync(path.join(pluginRoot, ".mcp.json"))); +assert.ok(!fs.existsSync(path.join(pluginRoot, "mcp"))); + +const workflowFiles = [ + "README.md", + "FEEDBACK.md", + "com.github.copilot/agents/diagnostician.agent.md", + "com.github.copilot/agents/contrarian.agent.md", + "com.github.copilot/instructions/diagnostic-reasoning.instructions.md", + "com.github.copilot/instructions/root-cause-analysis.instructions.md", +]; + +for (const relativePath of workflowFiles) { + const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); + assertPublicText(text, relativePath); +} + +const confidenceContractFiles = [ + "README.md", + "com.github.copilot/agents/diagnostician.agent.md", + "com.github.copilot/agents/contrarian.agent.md", + "com.github.copilot/instructions/diagnostic-reasoning.instructions.md", + "skills/validate-diagnosis-output/SKILL.md", + "skills/validate-diagnosis-output/scripts/validate-diagnosis-output.ps1", +]; + +for (const relativePath of confidenceContractFiles) { + const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); + assert.match(text, /fix_confidence/, `${relativePath} omits fix_confidence`); + assert.match( + text, + /fix_code_path_coverage/, + `${relativePath} omits fix_code_path_coverage`, + ); +} + +assert.ok( + fs.existsSync( + path.join( + pluginRoot, + "skills", + "validate-diagnosis-output", + "scripts", + "validate-diagnosis-output.ps1", + ), + ), +); + +console.log( + `Validated ${inventory.diagnosticSkills.length} diagnostic skills, ` + + `${inventory.auxiliarySkills.length} auxiliary skill, agent workflow, ` + + "validator script, and public-only links.", +); From e1050cdc39de2c9c4bc0d326656533a813cb3d86 Mon Sep 17 00:00:00 2001 From: Rade Trimceski Date: Wed, 7 Oct 2026 11:20:31 -0700 Subject: [PATCH 3/5] Rename diagnostician plugin to windbg Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .agents/plugins/marketplace.json | 4 +- .claude-plugin/marketplace.json | 4 +- .github/CODEOWNERS | 2 +- .github/plugin/marketplace.json | 4 +- .github/workflows/pr-validation.yml | 8 +- CHANGELOG.md | 6 +- README.md | 2 +- .../diagnostic-reasoning.instructions.md | 74 -------- .../root-cause-analysis.instructions.md | 44 ----- plugins/debugging-diagnostician/skills.json | 19 -- .../skills/validate-diagnosis-output/SKILL.md | 69 ------- .../.claude-plugin/plugin.json | 2 +- .../CHANGELOG.md | 4 +- .../FEEDBACK.md | 2 +- .../README.md | 63 +++--- .../agents/contrarian.agent.md | 0 .../agents/diagnostician.agent.md | 35 ++-- .../plugin.json | 5 +- plugins/windbg/skills.json | 19 ++ .../skills/windbg-diagnostic-method/SKILL.md | 179 ++++++++++++++++++ .../scripts/validate-diagnosis-output.ps1 | 0 .../windbg-kernel-bugcheck-triage}/SKILL.md | 18 +- .../SKILL.md | 14 +- .../SKILL.md | 14 +- .../windbg-kernel-verifier-triage}/SKILL.md | 18 +- .../windbg-user-exception-triage}/SKILL.md | 22 ++- .../SKILL.md | 12 +- .../SKILL.md | 14 +- .../SKILL.md | 18 +- .../SKILL.md | 12 +- .../windbg-user-wait-chain-analysis}/SKILL.md | 12 +- scripts/tests/test-windbg-validator.mjs | 134 +++++++++++++ scripts/validate-windbg.mjs | 128 +++++++++++++ 33 files changed, 629 insertions(+), 332 deletions(-) delete mode 100644 plugins/debugging-diagnostician/com.github.copilot/instructions/diagnostic-reasoning.instructions.md delete mode 100644 plugins/debugging-diagnostician/com.github.copilot/instructions/root-cause-analysis.instructions.md delete mode 100644 plugins/debugging-diagnostician/skills.json delete mode 100644 plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md rename plugins/{debugging-diagnostician => windbg}/.claude-plugin/plugin.json (93%) rename plugins/{debugging-diagnostician => windbg}/CHANGELOG.md (74%) rename plugins/{debugging-diagnostician => windbg}/FEEDBACK.md (98%) rename plugins/{debugging-diagnostician => windbg}/README.md (83%) rename plugins/{debugging-diagnostician => windbg}/com.github.copilot/agents/contrarian.agent.md (100%) rename plugins/{debugging-diagnostician => windbg}/com.github.copilot/agents/diagnostician.agent.md (83%) rename plugins/{debugging-diagnostician => windbg}/plugin.json (82%) create mode 100644 plugins/windbg/skills.json create mode 100644 plugins/windbg/skills/windbg-diagnostic-method/SKILL.md rename plugins/{debugging-diagnostician/skills/validate-diagnosis-output => windbg/skills/windbg-diagnostic-method}/scripts/validate-diagnosis-output.ps1 (100%) rename plugins/{debugging-diagnostician/skills/kernel-bugcheck-triage => windbg/skills/windbg-kernel-bugcheck-triage}/SKILL.md (85%) rename plugins/{debugging-diagnostician/skills/km-irp-lifecycle-triage => windbg/skills/windbg-kernel-irp-lifecycle-triage}/SKILL.md (86%) rename plugins/{debugging-diagnostician/skills/km-lock-deadlock-triage => windbg/skills/windbg-kernel-lock-deadlock-triage}/SKILL.md (86%) rename plugins/{debugging-diagnostician/skills/km-verifier-triage => windbg/skills/windbg-kernel-verifier-triage}/SKILL.md (84%) rename plugins/{debugging-diagnostician/skills/um-exception-triage => windbg/skills/windbg-user-exception-triage}/SKILL.md (82%) rename plugins/{debugging-diagnostician/skills/heap-corruption-investigation => windbg/skills/windbg-user-heap-corruption-investigation}/SKILL.md (91%) rename plugins/{debugging-diagnostician/skills/mutex-held-across-co-await => windbg/skills/windbg-user-mutex-held-across-co-await}/SKILL.md (86%) rename plugins/{debugging-diagnostician/skills/ttd-reverse-debugging-triage => windbg/skills/windbg-user-ttd-reverse-debugging-triage}/SKILL.md (84%) rename plugins/{debugging-diagnostician/skills/virtual-memory-exhaustion => windbg/skills/windbg-user-virtual-memory-exhaustion}/SKILL.md (90%) rename plugins/{debugging-diagnostician/skills/wait-chain-analysis => windbg/skills/windbg-user-wait-chain-analysis}/SKILL.md (90%) create mode 100644 scripts/tests/test-windbg-validator.mjs create mode 100644 scripts/validate-windbg.mjs diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index f4829c5f..6ff6ba73 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -5,10 +5,10 @@ }, "plugins": [ { - "name": "debugging-diagnostician", + "name": "windbg", "source": { "source": "local", - "path": "./plugins/debugging-diagnostician" + "path": "./plugins/windbg" }, "policy": { "installation": "AVAILABLE", diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1fd5f709..5fc584e2 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,10 +8,10 @@ "version": "0.7.1", "plugins": [ { - "name": "debugging-diagnostician", + "name": "windbg", "description": "WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", "version": "1.0.0", - "source": "./plugins/debugging-diagnostician", + "source": "./plugins/windbg", "author": { "name": "Microsoft", "url": "https://github.com/microsoft/WinDbg-Feedback" diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 84bb8ade..50dd3025 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -17,4 +17,4 @@ # # winui and winappcli are maintained in microsoft/winappCli and reviewed # there; their catalog entries are covered above. -/plugins/debugging-diagnostician/ @nmetulev @azchohfi @niels9001 @rtrimceski-MS +/plugins/windbg/ @nmetulev @azchohfi @niels9001 @rtrimceski-MS diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index a660dbd4..9db83f1a 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -10,10 +10,10 @@ }, "plugins": [ { - "name": "debugging-diagnostician", + "name": "windbg", "description": "WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers.", "version": "1.0.0", - "source": "./plugins/debugging-diagnostician" + "source": "./plugins/windbg" }, { "name": "winui", diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml index 18d366d2..9f0a4ae2 100644 --- a/.github/workflows/pr-validation.yml +++ b/.github/workflows/pr-validation.yml @@ -48,11 +48,11 @@ jobs: - name: Install local plugin lint dependencies run: npm ci --prefix scripts/vally --no-audit --no-fund - - name: Check debugging diagnostician package - run: node scripts/validate-debugging-diagnostician.mjs + - name: Check WinDbg package + run: node scripts/validate-windbg.mjs - - name: Test debugging diagnostician validator - run: node scripts/tests/test-debugging-diagnostician-validator.mjs + - name: Test WinDbg diagnosis validator + run: node scripts/tests/test-windbg-validator.mjs - name: Lint local plugin skills run: node scripts/vally/lint-skills.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index 545606bd..fb47f178 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,9 +14,9 @@ to `## [X.Y.Z] — YYYY-MM-DD` (see RELEASING.md). ### Added -- **`debugging-diagnostician` plugin**: focused WinDbg diagnosis workflows, - auxiliary output validation, contrarian review, and public WinDbg-Feedback - guidance. +- **`windbg` plugin**: focused WinDbg diagnosis workflows, + deterministic output validation, contrarian review, and public + WinDbg-Feedback guidance. - **`winappcli` plugin** (WinApp CLI 0.7.1: MSIX packaging, signing, package identity, appxmanifest, Windows SDK setup, Store distribution) for Copilot, Claude Code, and Codex, pinned to microsoft/winappCli `v0.7.1`. Install with diff --git a/README.md b/README.md index 43663785..f227d39d 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Agent plugins for Windows development and debugging—from apps and services to |---|---|---|---| | **`winappcli`** | Packaging, signing, and distributing Windows apps with [WinApp CLI](https://github.com/microsoft/winappCli): MSIX, certificates, package identity, appxmanifest, Windows SDK setup, and the Microsoft Store. Works with Electron, .NET, C++, Rust, Flutter, and Tauri. | [microsoft/winappCli](https://github.com/microsoft/winappCli/tree/main/plugins/winapp) | Copilot, Claude Code, Codex, OpenClaw, OpenCode | | **`winui`** | Native Windows apps with **WinUI 3** and the **Windows App SDK**: scaffold, design, build, run, test, package, and ship. | [microsoft/winappCli](https://github.com/microsoft/winappCli/tree/main/plugins/winui) | Copilot, Claude Code, Codex, OpenClaw, OpenCode | -| **`debugging-diagnostician`** | WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers. [Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). | [This repo](plugins/debugging-diagnostician/README.md) | Copilot, Claude Code, Codex, OpenCode | +| **`windbg`** | WinDbg diagnosis workflows and report validation for applications, services, UMDF/user-mode drivers, and kernel-mode drivers. [Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). | [This repo](plugins/windbg/README.md) | Copilot, Claude Code, Codex, OpenCode | On Codex, OpenClaw, and OpenCode, skills load; agents aren't available. diff --git a/plugins/debugging-diagnostician/com.github.copilot/instructions/diagnostic-reasoning.instructions.md b/plugins/debugging-diagnostician/com.github.copilot/instructions/diagnostic-reasoning.instructions.md deleted file mode 100644 index 5ac20fff..00000000 --- a/plugins/debugging-diagnostician/com.github.copilot/instructions/diagnostic-reasoning.instructions.md +++ /dev/null @@ -1,74 +0,0 @@ -# Diagnostic Reasoning Instructions - -## Five phases - -1. **OBSERVE**: establish dump/trace type, architecture, symbols, code, stack, - registers, thread/resource state, and missing evidence. -2. **HYPOTHESIZE**: form a primary mechanism and at least two plausible - alternatives when the evidence permits. -3. **TEST**: identify direct debugger/source/repro 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 | -|---|---| -| User-mode exception in an app, service, or UMDF/user-mode driver host | `um-exception-triage` | -| User-mode heap corruption or allocation/free history | `heap-corruption-investigation` | -| Cross-thread/process, COM/RPC, or service wait | `wait-chain-analysis` | -| User-mode TTD history question | `ttd-reverse-debugging-triage` | -| User-mode VA fragmentation, allocation failure, or commit pressure | `virtual-memory-exhaustion` | -| Thread-affine lock across coroutine suspension | `mutex-held-across-co-await` | -| Kernel bugcheck, trap frame, or saved context | `kernel-bugcheck-triage` | -| Driver Verifier violation | `km-verifier-triage` | -| Outstanding/power IRP, completion, or cancellation | `km-irp-lifecycle-triage` | -| Kernel lock owner/waiter chain | `km-lock-deadlock-triage` | -| Structural report validation | `validate-diagnosis-output` | - -These are the complete skills. Continue general evidence-led reasoning for -unsupported families; never dispatch to an absent skill. - -## Routing paths - -- **Fast (indicative confidence ≥0.8)**: validate the pattern and alternatives. -- **Validate (0.4–0.79)**: test the leading pattern plus alternatives. -- **Full reasoning (<0.4/no match)**: reason from observations and preserve - uncertainty. - -Confidence is judgment, not measured probability. - -## 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. - -## Trigger and fix gates - -- Verify the trigger condition in dump, disassembly, source, or controlled repro - before declaring a final fix. -- A fix must restore the violated invariant, not merely suppress the reproducer. -- Fix confidence of 0.90 or higher requires reading the actual code path in - this session. -- If the trigger is unverified, use candidate-pending-verification, null fix, - and name the evidence/fix matrix required. - -## Output contract - -A full report contains: Analysis, Root Cause, Fix, Reasoning Chain, -Alternatives Considered, Trigger Verification table, Mermaid, Contrarian -Verdict, and JSON Output Contract Summary. Mermaid must reflect verified -evidence and use valid VS Code syntax. Run the independent contrarian once, then -the structural validator. A second challenge ends as pending verification. diff --git a/plugins/debugging-diagnostician/com.github.copilot/instructions/root-cause-analysis.instructions.md b/plugins/debugging-diagnostician/com.github.copilot/instructions/root-cause-analysis.instructions.md deleted file mode 100644 index 478078a7..00000000 --- a/plugins/debugging-diagnostician/com.github.copilot/instructions/root-cause-analysis.instructions.md +++ /dev/null @@ -1,44 +0,0 @@ -# Root-Cause Analysis Instructions - -## Evidence ladder - -Prefer direct evidence in this order: - -1. Faulting instruction/context, bugcheck/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. - -## 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. - -## Quality bar - -- Name the violated invariant and the parties/path that violate it. -- Separate detector/victim from original writer/freeing/holding actor. -- Test alternatives with direct evidence. -- Do not blame a module solely from a bucket or `MODULE_NAME`. -- Never claim commands, source access, or artifacts unavailable to the session. -- State whether the conclusion is final or pending verification and why. - -## 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/Page Heap can disrupt workloads and must use a recoverable -test plan and restoration steps. Public feedback follows `FEEDBACK.md` and -defaults to a minimal reviewed summary with no automatic attachments. diff --git a/plugins/debugging-diagnostician/skills.json b/plugins/debugging-diagnostician/skills.json deleted file mode 100644 index bf6285bd..00000000 --- a/plugins/debugging-diagnostician/skills.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "name": "debugging-diagnostician", - "version": "1.0.0", - "diagnosticSkills": [ - "um-exception-triage", - "heap-corruption-investigation", - "wait-chain-analysis", - "ttd-reverse-debugging-triage", - "virtual-memory-exhaustion", - "mutex-held-across-co-await", - "kernel-bugcheck-triage", - "km-verifier-triage", - "km-irp-lifecycle-triage", - "km-lock-deadlock-triage" - ], - "auxiliarySkills": [ - "validate-diagnosis-output" - ] -} diff --git a/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md b/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md deleted file mode 100644 index eefe80c6..00000000 --- a/plugins/debugging-diagnostician/skills/validate-diagnosis-output/SKILL.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: validate-diagnosis-output -description: Use after a Diagnostician report is written to verify required sections, trigger evidence, Mermaid, contrarian verdict, and JSON summary. Not for judging whether the diagnosis is technically correct. -user-invocable: false ---- -# Validate Diagnosis Output - -Use this skill after the Diagnostician writes a report to -`/.diagnoses//.md`. - -The bundled -[`validate-diagnosis-output.ps1`](scripts/validate-diagnosis-output.ps1) -performs deterministic structural validation. It does not judge whether the -technical diagnosis is correct. - -## Run the validator - -Run the script with PowerShell 7: - -```powershell -pwsh -NoProfile -File \scripts\validate-diagnosis-output.ps1 ` - -Path -``` - -Use the installed skill directory for ``. The script emits a -JSON result and exits nonzero when any check fails. - -## Checks - -| Check | Requirement | -|---|---| -| Analysis | An `## Analysis` section exists. | -| Root Cause | An `## Root Cause` section exists. | -| Fix | An `## Fix` section exists. | -| Reasoning Chain | Its section contains at least one phase marker: `OBSERVE`, `HYPOTHESIZE`, `TEST`, `EVALUATE`, or `CONCLUDE`. | -| Alternatives | Its section contains at least two bulleted or numbered alternatives. | -| Trigger Verification | Its section contains a Markdown table and a `VERIFIED`, `UNVERIFIED`, or `verified by` status. | -| Mermaid | A sequence diagram names or implicitly uses at least two actors, or a flowchart has at least two connected nodes. | -| Contrarian Verdict | Its section contains `ACCEPTED` or `CHALLENGED` and a Boolean `contrarian_loopback: true\|false`. | -| JSON summary | A parseable JSON block contains the required output-contract properties and a Boolean `contrarian_loopback`. | - -The required JSON properties are: - -- `diagnosis_status` -- `routing_path` -- `root_cause` -- `confidence` -- `fix_confidence` -- `fix_code_path_coverage` -- `contrarian_review` -- `contrarian_loopback` - -## Completion criteria - -When validation fails: - -1. Read the `Checks` object in the script output. -2. Correct only the missing or malformed report sections. -3. Re-run the script. -4. Do not present the report as structurally complete until every check passes. - -Structural validation does not replace semantic review. The diagnostician must -still invoke the independent `contrarian` agent through the host's agent -mechanism and respond to a challenged verdict. - -## Feedback - -For feedback about this validator, follow the package `FEEDBACK.md`. Do not -attach private diagnosis files automatically. diff --git a/plugins/debugging-diagnostician/.claude-plugin/plugin.json b/plugins/windbg/.claude-plugin/plugin.json similarity index 93% rename from plugins/debugging-diagnostician/.claude-plugin/plugin.json rename to plugins/windbg/.claude-plugin/plugin.json index c6a3bd51..4ac52d2a 100644 --- a/plugins/debugging-diagnostician/.claude-plugin/plugin.json +++ b/plugins/windbg/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { - "name": "debugging-diagnostician", + "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": { diff --git a/plugins/debugging-diagnostician/CHANGELOG.md b/plugins/windbg/CHANGELOG.md similarity index 74% rename from plugins/debugging-diagnostician/CHANGELOG.md rename to plugins/windbg/CHANGELOG.md index 62feef33..61ce0cdc 100644 --- a/plugins/debugging-diagnostician/CHANGELOG.md +++ b/plugins/windbg/CHANGELOG.md @@ -3,8 +3,8 @@ ## 1.0.0 - Initial contribution - Included the curated debugging skill inventory in `skills.json`. -- Added the auxiliary `validate-diagnosis-output` skill, contrarian agent, - and two reasoning instruction files required for the complete workflow. +- 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. diff --git a/plugins/debugging-diagnostician/FEEDBACK.md b/plugins/windbg/FEEDBACK.md similarity index 98% rename from plugins/debugging-diagnostician/FEEDBACK.md rename to plugins/windbg/FEEDBACK.md index 94ba3cd8..055de00e 100644 --- a/plugins/debugging-diagnostician/FEEDBACK.md +++ b/plugins/windbg/FEEDBACK.md @@ -41,7 +41,7 @@ Title: `[Debugging skills][] ` ```markdown ### Skill and version -Plugin: debugging-diagnostician +Plugin: windbg Package version: Skill: diff --git a/plugins/debugging-diagnostician/README.md b/plugins/windbg/README.md similarity index 83% rename from plugins/debugging-diagnostician/README.md rename to plugins/windbg/README.md index a7757d60..97c67841 100644 --- a/plugins/debugging-diagnostician/README.md +++ b/plugins/windbg/README.md @@ -4,13 +4,12 @@ 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 a reasoning-first hypothesis-test-pivot method -with focused user-mode and kernel-mode debugging skills, the auxiliary -`validate-diagnosis-output` skill, a contrarian reviewer, and reasoning -instructions for the complete workflow. 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. +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 @@ -18,7 +17,7 @@ Install from the catalog: ```powershell copilot plugin marketplace add microsoft/win-dev-skills -copilot plugin install debugging-diagnostician@win-dev-skills +copilot plugin install windbg@win-dev-skills ``` Claude Code and Codex use their normal marketplace install commands described in @@ -62,9 +61,9 @@ symptom, or debugger output: You can also invoke a skill directly on a skill-capable host: ```text -Use heap-corruption-investigation on the dump open in WinDbg. Establish what -evidence is available, distinguish competing explanations, and state what -remains unproven. +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 @@ -120,7 +119,10 @@ trace, stack, or debugger session in this conversation. "candidate-pending-verification" and name the next evidence required. ```` -The package includes a public contrarian sub-agent and the auxiliary `validate-diagnosis-output` 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. +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 @@ -239,27 +241,27 @@ The authoritative skill inventory is `skills.json`. | Skill | Use it for | |---|---| -| `um-exception-triage` | Establish exception context and classify native process crashes, including user-mode driver host failures. | -| `heap-corruption-investigation` | Investigate use-after-free, double-free, and overruns in applications, services, or user-mode driver hosts. | -| `wait-chain-analysis` | Follow application, service, user-mode driver, COM/RPC, and process waits to a supported blocker or cycle. | -| `ttd-reverse-debugging-triage` | Find earlier writes, frees, and calls in a recorded user-mode process, including a user-mode driver host. | -| `virtual-memory-exhaustion` | Separate address-space pressure, fragmentation, commit pressure, and applicable limits. | -| `mutex-held-across-co-await` | Investigate thread-affine locks held across coroutine suspension in user-mode components. | +| `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 | |---|---| -| `kernel-bugcheck-triage` | Decode bugchecks and recover original exception or trap context. | -| `km-verifier-triage` | Interpret Driver Verifier violations and available I/O verification evidence. | -| `km-irp-lifecycle-triage` | Investigate outstanding I/O, completion/cancel ownership, and power IRPs. | -| `km-lock-deadlock-triage` | Build supported kernel owner/waiter graphs and investigate lock-order inversions. | +| `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 -`kernel-bugcheck-triage`, not additional skills. Feedback guidance and the -optional agent are support content, not an eleventh diagnostic skill. +`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. `um-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. +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 @@ -276,11 +278,11 @@ These are starting hypotheses, never automatic diagnoses: | 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. | -### Auxiliary skill +### Shared method skill | Skill | Purpose | |---|---| -| `validate-diagnosis-output` | Deterministically checks the complete report structure after the contrarian review. | +| `windbg-diagnostic-method` | Applies the shared evidence, reasoning, confidence, review, reporting, and deterministic validation method. | ## File Inventory @@ -290,16 +292,15 @@ These are starting hypotheses, never automatic diagnoses: | `.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. | -| `com.github.copilot/instructions/*.instructions.md` | Five-phase reasoning, routing, evidence, output, and privacy contracts. | -| `skills//SKILL.md` | Debugging skills plus the auxiliary output validator. | +| `skills//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 auxiliary validator is explicitly -inventoried and is not a debugging skill. +service, or feedback automation. The shared method is explicitly inventoried +and is not a bug-family-specific skill. ### Authoring and calibration material not bundled diff --git a/plugins/debugging-diagnostician/com.github.copilot/agents/contrarian.agent.md b/plugins/windbg/com.github.copilot/agents/contrarian.agent.md similarity index 100% rename from plugins/debugging-diagnostician/com.github.copilot/agents/contrarian.agent.md rename to plugins/windbg/com.github.copilot/agents/contrarian.agent.md diff --git a/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md b/plugins/windbg/com.github.copilot/agents/diagnostician.agent.md similarity index 83% rename from plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md rename to plugins/windbg/com.github.copilot/agents/diagnostician.agent.md index 97e875ba..e730ef36 100644 --- a/plugins/debugging-diagnostician/com.github.copilot/agents/diagnostician.agent.md +++ b/plugins/windbg/com.github.copilot/agents/diagnostician.agent.md @@ -5,6 +5,9 @@ description: Diagnose native Windows application, service, user-mode driver (inc # 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 @@ -38,16 +41,16 @@ Confidence is explanatory judgment, not measured probability. | Evidence | Skill | |---|---| -| Application, service, or user-mode driver host structured exception | `um-exception-triage` | -| Application, service, or user-mode driver host heap corruption/history | `heap-corruption-investigation` | -| Blocked UI, service, user-mode driver host, COM/RPC, or thread/process wait | `wait-chain-analysis` | -| A recorded application, service, or user-mode driver host execution with a history question | `ttd-reverse-debugging-triage` | -| User-mode allocation failure, VA fragmentation, or commit pressure | `virtual-memory-exhaustion` | -| Thread-affine lock surviving coroutine suspension in a user-mode component | `mutex-held-across-co-await` | -| Kernel bugcheck, trap frame, or saved exception context | `kernel-bugcheck-triage` | -| Driver Verifier violation | `km-verifier-triage` | -| Outstanding/power IRP, cancellation, or completion | `km-irp-lifecycle-triage` | -| Kernel lock owner/waiter chain | `km-lock-deadlock-triage` | +| 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 @@ -83,9 +86,9 @@ Before finalizing a full diagnosis: 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 apply - `validate-diagnosis-output` by running its bundled PowerShell script. Correct - structural failures and re-run the script before finalizing. +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 @@ -104,9 +107,9 @@ 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 `validate-diagnosis-output` against the report. -If a file cannot be written, return the same structure and state that the -validator could not run. +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 diff --git a/plugins/debugging-diagnostician/plugin.json b/plugins/windbg/plugin.json similarity index 82% rename from plugins/debugging-diagnostician/plugin.json rename to plugins/windbg/plugin.json index f611a084..d326d6e5 100644 --- a/plugins/debugging-diagnostician/plugin.json +++ b/plugins/windbg/plugin.json @@ -1,6 +1,6 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", - "name": "debugging-diagnostician", + "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": { @@ -21,8 +21,7 @@ ], "extensions": { "com.github.copilot": { - "agents": "./com.github.copilot/agents", - "instructions": "./com.github.copilot/instructions" + "agents": "./com.github.copilot/agents" } } } diff --git a/plugins/windbg/skills.json b/plugins/windbg/skills.json new file mode 100644 index 00000000..ce178211 --- /dev/null +++ b/plugins/windbg/skills.json @@ -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" + ] +} diff --git a/plugins/windbg/skills/windbg-diagnostic-method/SKILL.md b/plugins/windbg/skills/windbg-diagnostic-method/SKILL.md new file mode 100644 index 00000000..16c7c34e --- /dev/null +++ b/plugins/windbg/skills/windbg-diagnostic-method/SKILL.md @@ -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 \scripts\validate-diagnosis-output.ps1 ` + -Path +``` + +Use the installed `windbg-diagnostic-method` directory for +``. 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. diff --git a/plugins/debugging-diagnostician/skills/validate-diagnosis-output/scripts/validate-diagnosis-output.ps1 b/plugins/windbg/skills/windbg-diagnostic-method/scripts/validate-diagnosis-output.ps1 similarity index 100% rename from plugins/debugging-diagnostician/skills/validate-diagnosis-output/scripts/validate-diagnosis-output.ps1 rename to plugins/windbg/skills/windbg-diagnostic-method/scripts/validate-diagnosis-output.ps1 diff --git a/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md b/plugins/windbg/skills/windbg-kernel-bugcheck-triage/SKILL.md similarity index 85% rename from plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md rename to plugins/windbg/skills/windbg-kernel-bugcheck-triage/SKILL.md index dc6d7ae8..7c5dd7c7 100644 --- a/plugins/debugging-diagnostician/skills/kernel-bugcheck-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-kernel-bugcheck-triage/SKILL.md @@ -1,10 +1,14 @@ --- -name: kernel-bugcheck-triage +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Scope Use a kernel crash dump or authorized live kernel session. A process dump @@ -39,8 +43,8 @@ for many investigations; do not require private Windows source or PDBs. | `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 `km-irp-lifecycle-triage` where applicable. | -| Verifier-class stop | Use `km-verifier-triage` and the exact code/subcode definition. | +| `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. @@ -95,8 +99,8 @@ 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 `km-lock-deadlock-triage` or -`km-irp-lifecycle-triage`. Kernel `~` commands select processors, not the +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`. @@ -106,7 +110,7 @@ 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 -`km-verifier-triage`. Do not call a guessed module assignment a proven cause. +`windbg-kernel-verifier-triage`. Do not call a guessed module assignment a proven cause. ## References @@ -120,5 +124,5 @@ an instrumented test/repro only with approval; route Verifier evidence to Follow `FEEDBACK.md` and submit only reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `kernel-bugcheck-triage` and the package version from `plugin.json`; no +Include `windbg-kernel-bugcheck-triage` and the package version from `plugin.json`; no automatic kernel dump, private-symbol, or source upload. diff --git a/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md b/plugins/windbg/skills/windbg-kernel-irp-lifecycle-triage/SKILL.md similarity index 86% rename from plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md rename to plugins/windbg/skills/windbg-kernel-irp-lifecycle-triage/SKILL.md index fa5a7783..1b64b93b 100644 --- a/plugins/debugging-diagnostician/skills/km-irp-lifecycle-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-kernel-irp-lifecycle-triage/SKILL.md @@ -1,10 +1,14 @@ --- -name: km-irp-lifecycle-triage +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Scope Investigate I/O Request Packets in a kernel dump or authorized live kernel @@ -49,9 +53,9 @@ may change the responsible path. | Evidence | Next investigation | |---|---| -| I/O verifier violation or available shadow history | `km-verifier-triage` | -| Owner/waiter kernel lock chain | `km-lock-deadlock-triage` | -| Exception or trap during request handling | `kernel-bugcheck-triage` | +| 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. @@ -92,5 +96,5 @@ which driver lost the completion. Follow `FEEDBACK.md` and report only reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `km-irp-lifecycle-triage` and the package version from `plugin.json`; no +Include `windbg-kernel-irp-lifecycle-triage` and the package version from `plugin.json`; no automatic kernel dump or request-content upload. diff --git a/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md b/plugins/windbg/skills/windbg-kernel-lock-deadlock-triage/SKILL.md similarity index 86% rename from plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md rename to plugins/windbg/skills/windbg-kernel-lock-deadlock-triage/SKILL.md index f2e2469d..ee70c7a6 100644 --- a/plugins/debugging-diagnostician/skills/km-lock-deadlock-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-kernel-lock-deadlock-triage/SKILL.md @@ -1,10 +1,14 @@ --- -name: km-lock-deadlock-triage +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Detection Use kernel thread stacks, synchronization-object evidence, and Driver Verifier @@ -40,7 +44,7 @@ records: 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 `km-verifier-triage`. +the lock order is safe. For Verifier setup/safety use `windbg-kernel-verifier-triage`. ### 3. Build and test the graph @@ -59,8 +63,8 @@ Distinguish: - 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 `km-irp-lifecycle-triage`; if a chain crosses into a -user-mode COM/RPC operation use `wait-chain-analysis`. Carry the proven graph +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 @@ -96,5 +100,5 @@ Separate a demonstrated fix from an unproven contention hypothesis. Follow `FEEDBACK.md` and report reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `km-lock-deadlock-triage` and the package version from `plugin.json`; no +Include `windbg-kernel-lock-deadlock-triage` and the package version from `plugin.json`; no automatic dump, lock-history transcript, or driver-source upload. diff --git a/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md b/plugins/windbg/skills/windbg-kernel-verifier-triage/SKILL.md similarity index 84% rename from plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md rename to plugins/windbg/skills/windbg-kernel-verifier-triage/SKILL.md index f758cdb8..a14cc957 100644 --- a/plugins/debugging-diagnostician/skills/km-verifier-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-kernel-verifier-triage/SKILL.md @@ -1,14 +1,18 @@ --- -name: km-verifier-triage +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Scope Driver Verifier checks kernel driver contracts. Application Verifier is a -different user-mode facility; use `heap-corruption-investigation` for its heap +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 @@ -43,14 +47,14 @@ state is available: ``` Shadow state may preserve information lost from the live request. Correlate it -with the decoded contract and use `km-irp-lifecycle-triage` for completion, +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: `kernel-bugcheck-triage`. -- Lock-order evidence: `km-lock-deadlock-triage`. -- Outstanding or power request: `km-irp-lifecycle-triage`. +- 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. @@ -98,5 +102,5 @@ single repro is not proof that every driver path is safe. Follow `FEEDBACK.md` and submit reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `km-verifier-triage` and the package version from `plugin.json`; do not +Include `windbg-kernel-verifier-triage` and the package version from `plugin.json`; do not automatically upload dumps or proprietary driver source. diff --git a/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md b/plugins/windbg/skills/windbg-user-exception-triage/SKILL.md similarity index 82% rename from plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md rename to plugins/windbg/skills/windbg-user-exception-triage/SKILL.md index 00b6d680..48e6034e 100644 --- a/plugins/debugging-diagnostician/skills/um-exception-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-user-exception-triage/SKILL.md @@ -1,10 +1,14 @@ --- -name: um-exception-triage +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; establish context and classify it. Not for managed .NET exceptions, WinUI/XAML app errors, or kernel bugchecks.' --- # User-Mode Exception Triage +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## When to use Start here for access violations, heap corruption, stack overflow, fail-fast, @@ -37,13 +41,13 @@ Investigate mismatches or truncated stacks before naming a failing source line. | Evidence | Next step | |---|---| -| `0xC0000005` with allocation/free or overrun evidence | `heap-corruption-investigation` | -| `0xC0000374` heap corruption | `heap-corruption-investigation` | -| `0xC0000017`, `0x8007000E`, or an allocation-failure path | `virtual-memory-exhaustion` | -| Lock/unlock failure following coroutine suspension | `mutex-held-across-co-await` | -| A TTD recording is available and earlier mutation is in question | `ttd-reverse-debugging-triage` | -| No crash exception and evidence of blocked work | `wait-chain-analysis` | -| A kernel dump reports a bugcheck | `kernel-bugcheck-triage` | +| `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. @@ -89,5 +93,5 @@ type, faulting instruction, object layout, and valid allocation boundaries. 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 `um-exception-triage` and the package version from `plugin.json`; do not +Include `windbg-user-exception-triage` and the package version from `plugin.json`; do not upload dumps or private source automatically. diff --git a/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md b/plugins/windbg/skills/windbg-user-heap-corruption-investigation/SKILL.md similarity index 91% rename from plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md rename to plugins/windbg/skills/windbg-user-heap-corruption-investigation/SKILL.md index 1756089a..1dc8ee24 100644 --- a/plugins/debugging-diagnostician/skills/heap-corruption-investigation/SKILL.md +++ b/plugins/windbg/skills/windbg-user-heap-corruption-investigation/SKILL.md @@ -1,10 +1,14 @@ --- -name: heap-corruption-investigation +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Detection and limits Look for `STATUS_HEAP_CORRUPTION` (`0xC0000374`), Application Verifier stops, @@ -12,7 +16,7 @@ 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 -`virtual-memory-exhaustion`. +`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 @@ -83,7 +87,7 @@ 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 `ttd-reverse-debugging-triage` to +If a user-mode TTD trace is available, use `windbg-user-ttd-reverse-debugging-triage` to find the relevant mutation or free. ## Fix patterns @@ -115,5 +119,5 @@ Report unresolved writer history rather than presenting a guessed fix as proven. Follow `FEEDBACK.md` and report reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `heap-corruption-investigation` and the package version from +Include `windbg-user-heap-corruption-investigation` and the package version from `plugin.json`; no automatic dump, source, or transcript upload. diff --git a/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md b/plugins/windbg/skills/windbg-user-mutex-held-across-co-await/SKILL.md similarity index 86% rename from plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md rename to plugins/windbg/skills/windbg-user-mutex-held-across-co-await/SKILL.md index 7423831a..8a389a95 100644 --- a/plugins/debugging-diagnostician/skills/mutex-held-across-co-await/SKILL.md +++ b/plugins/windbg/skills/windbg-user-mutex-held-across-co-await/SKILL.md @@ -1,10 +1,14 @@ --- -name: mutex-held-across-co-await +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Detection This pattern can occur in native application, service, or user-mode driver @@ -31,9 +35,9 @@ the awaited operation needs a lock the coroutine still holds. 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 `wait-chain-analysis`. For damaged -heap objects use `heap-corruption-investigation`. If a recording is available, -`ttd-reverse-debugging-triage` can help establish the ownership timeline. +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 @@ -77,5 +81,5 @@ Keep the object and any captured interfaces alive across asynchronous work. Follow `FEEDBACK.md` and report reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `mutex-held-across-co-await` and the package version from `plugin.json`; +Include `windbg-user-mutex-held-across-co-await` and the package version from `plugin.json`; no automatic source, dump, or transcript upload. diff --git a/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md b/plugins/windbg/skills/windbg-user-ttd-reverse-debugging-triage/SKILL.md similarity index 84% rename from plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md rename to plugins/windbg/skills/windbg-user-ttd-reverse-debugging-triage/SKILL.md index 24d1b54b..b0332dba 100644 --- a/plugins/debugging-diagnostician/skills/ttd-reverse-debugging-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-user-ttd-reverse-debugging-triage/SKILL.md @@ -1,10 +1,14 @@ --- -name: ttd-reverse-debugging-triage +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Requirements and scope Time Travel Debugging records a user-mode process for replay, including an @@ -69,13 +73,13 @@ identity, valid lifetime, intended invariant, and relevant cross-thread order. | Evidence | Skill | |---|---| -| Bad free/write or allocation-boundary violation | `heap-corruption-investigation` | -| Growing allocation/reservation usage | `virtual-memory-exhaustion` | -| Lock survives coroutine suspension | `mutex-held-across-co-await` | -| Blocker or cross-process dependency at the selected moment | `wait-chain-analysis` | +| 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 `kernel-bugcheck-triage`; +dispatching to absent skills. For a kernel crash use `windbg-kernel-bugcheck-triage`; TTD is not a kernel-history substitute. ## Validation @@ -95,6 +99,6 @@ it does not establish that instrumentation preserved all production timing. Follow `FEEDBACK.md` and report a reviewed summary to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `ttd-reverse-debugging-triage` and the package version from +Include `windbg-user-ttd-reverse-debugging-triage` and the package version from `plugin.json`; never automatically upload a recording or its memory/query contents. diff --git a/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md b/plugins/windbg/skills/windbg-user-virtual-memory-exhaustion/SKILL.md similarity index 90% rename from plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md rename to plugins/windbg/skills/windbg-user-virtual-memory-exhaustion/SKILL.md index 852f4392..2d8eac51 100644 --- a/plugins/debugging-diagnostician/skills/virtual-memory-exhaustion/SKILL.md +++ b/plugins/windbg/skills/windbg-user-virtual-memory-exhaustion/SKILL.md @@ -1,10 +1,14 @@ --- -name: virtual-memory-exhaustion +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Detection Investigate `E_OUTOFMEMORY` (`0x8007000E`), `STATUS_NO_MEMORY` (`0xC0000017`), @@ -71,8 +75,8 @@ 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 `ttd-reverse-debugging-triage`; for damaged allocations -use `heap-corruption-investigation` instead. +user-mode recording use `windbg-user-ttd-reverse-debugging-triage`; for damaged allocations +use `windbg-user-heap-corruption-investigation` instead. ## Fix patterns @@ -104,5 +108,5 @@ required constraints. Document configured system/job limits separately. Follow `FEEDBACK.md` and submit reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `virtual-memory-exhaustion` and the package version from `plugin.json`; +Include `windbg-user-virtual-memory-exhaustion` and the package version from `plugin.json`; no automatic dump or memory-content upload. diff --git a/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md b/plugins/windbg/skills/windbg-user-wait-chain-analysis/SKILL.md similarity index 90% rename from plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md rename to plugins/windbg/skills/windbg-user-wait-chain-analysis/SKILL.md index 6b6c366a..13820952 100644 --- a/plugins/debugging-diagnostician/skills/wait-chain-analysis/SKILL.md +++ b/plugins/windbg/skills/windbg-user-wait-chain-analysis/SKILL.md @@ -1,10 +1,14 @@ --- -name: wait-chain-analysis +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 +Apply `windbg-diagnostic-method` throughout this investigation for evidence +ranking, hypothesis testing, confidence calibration, independent review, and +report validation. + ## Detection Look for blocked work in an application, service, or user-mode driver host @@ -55,8 +59,8 @@ For kernel context use documented commands such as: ``` Available user pages and symbol/context support vary by dump type. If the chain -ends in a kernel lock use `km-lock-deadlock-triage`; if blocked I/O is supported -by IRP evidence use `km-irp-lifecycle-triage`. Do not promise process heaps or +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 @@ -106,6 +110,6 @@ If the server dump or an owner edge is missing, state the unresolved hypothesis. Follow `FEEDBACK.md` and submit only reviewed, sanitized feedback to [WinDbg-Feedback](https://github.com/microsoft/WinDbg-Feedback/issues). -Include `wait-chain-analysis` and the package version from `plugin.json`; no +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. diff --git a/scripts/tests/test-windbg-validator.mjs b/scripts/tests/test-windbg-validator.mjs new file mode 100644 index 00000000..c9c91ec2 --- /dev/null +++ b/scripts/tests/test-windbg-validator.mjs @@ -0,0 +1,134 @@ +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { spawnSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const repositoryRoot = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + "..", + "..", +); +const validator = path.join( + repositoryRoot, + "plugins", + "windbg", + "skills", + "windbg-diagnostic-method", + "scripts", + "validate-diagnosis-output.ps1", +); +const temporaryDirectory = fs.mkdtempSync( + path.join(os.tmpdir(), "diagnosis-validator-"), +); + +const validReport = `## Analysis +Observed evidence. + +## Root Cause +Candidate cause. + +## Fix +Candidate fix. + +## Reasoning Chain +OBSERVE: evidence. + +## Alternatives Considered +- Alternative one +- Alternative two + +## Trigger Verification +| Evidence | Status | +|---|---| +| Trigger | VERIFIED | + +## Mermaid +\`\`\`mermaid +sequenceDiagram +A->>B: request +B-->>A: response +\`\`\` + +## Contrarian Verdict +ACCEPTED + +contrarian_loopback: false + +## JSON Output Contract Summary +\`\`\`json +{"diagnosis_status":"final","routing_path":"validate","root_cause":"cause","confidence":0.8,"fix_confidence":0.7,"fix_code_path_coverage":"symbol-or-disassembly","contrarian_review":"ACCEPTED","contrarian_loopback":false} +\`\`\` +`; + +const invalidReport = `## Analysis +The words OBSERVE and VERIFIED appear outside their required sections. + +## Root Cause +Candidate cause. + +## Fix +Candidate fix. + +## Reasoning Chain +No phase marker appears here. + +## Alternatives Considered +- Only one alternative + +## Trigger Verification +No table appears here. + +## Mermaid +\`\`\`mermaid +sequenceDiagram +participant A +\`\`\` + +## Contrarian Verdict +ACCEPTED + +contrarian_loopback: 1 + +## JSON Output Contract Summary +\`\`\`json +{"diagnosis_status":"final","routing_path":"validate","root_cause":"cause","confidence":0.8,"fix_confidence":0.7,"fix_code_path_coverage":"symbol-or-disassembly","contrarian_review":"ACCEPTED","contrarian_loopback":1} +\`\`\` +`; + +function runValidator(file) { + return spawnSync( + "pwsh", + ["-NoProfile", "-File", validator, "-Path", file], + { encoding: "utf8" }, + ); +} + +try { + const validPath = path.join(temporaryDirectory, "valid.md"); + const invalidPath = path.join(temporaryDirectory, "invalid.md"); + fs.writeFileSync(validPath, validReport); + fs.writeFileSync(invalidPath, invalidReport); + + const validResult = runValidator(validPath); + assert.equal(validResult.status, 0, validResult.stderr || validResult.stdout); + const validOutput = JSON.parse(validResult.stdout); + assert.equal(validOutput.Pass, true); + assert.equal(validOutput.Checks.MermaidDiagram, true); + + const invalidResult = runValidator(invalidPath); + assert.equal(invalidResult.status, 1, invalidResult.stderr); + const invalidOutput = JSON.parse(invalidResult.stdout); + assert.equal(invalidOutput.Pass, false); + assert.equal(invalidOutput.Checks.ReasoningChain, false); + assert.equal(invalidOutput.Checks.Alternatives, false); + assert.equal(invalidOutput.Checks.TriggerVerification, false); + assert.equal(invalidOutput.Checks.MermaidDiagram, false); + assert.equal(invalidOutput.Checks.ContrarianVerdict, false); + assert.equal(invalidOutput.Checks.JsonSummary, false); + + console.log("Diagnosis validator accepts valid reports and rejects malformed sections."); +} finally { + fs.rmSync(temporaryDirectory, { recursive: true, force: true }); +} diff --git a/scripts/validate-windbg.mjs b/scripts/validate-windbg.mjs new file mode 100644 index 00000000..678ffcee --- /dev/null +++ b/scripts/validate-windbg.mjs @@ -0,0 +1,128 @@ +import assert from "node:assert/strict"; +import fs from "node:fs"; +import path from "node:path"; +import { createRequire } from "node:module"; +import { fileURLToPath } from "node:url"; + +const repositoryRoot = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + "..", +); +const pluginRoot = path.join( + repositoryRoot, + "plugins", + "windbg", +); +const require = createRequire( + path.join(repositoryRoot, "scripts", "vally", "package.json"), +); +const { parseDocument } = require("yaml"); + +const inventory = JSON.parse( + fs.readFileSync(path.join(pluginRoot, "skills.json"), "utf8"), +); +assert.deepEqual(inventory.methodSkills, ["windbg-diagnostic-method"]); + +const allowedSkills = [ + ...inventory.diagnosticSkills, + ...inventory.methodSkills, +].sort(); +const skillDirectories = fs + .readdirSync(path.join(pluginRoot, "skills"), { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name) + .sort(); +assert.deepEqual(skillDirectories, allowedSkills); + +const allowedUrlHosts = new Set([ + "agent-plugins.org", + "devblogs.microsoft.com", + "github.com", + "learn.microsoft.com", +]); + +function assertPublicText(text, label) { + for (const match of text.matchAll(/https?:\/\/[^\s<>"'`]+/g)) { + const value = match[0].replace(/[),.;:]+$/, ""); + const host = new URL(value).hostname.toLowerCase(); + assert.ok( + allowedUrlHosts.has(host), + `${label} references unapproved URL host ${host}`, + ); + } + + assert.doesNotMatch( + text, + /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i, + `${label} contains an email address`, + ); +} + +for (const skill of skillDirectories) { + const relativePath = path.join("skills", skill, "SKILL.md"); + const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); + const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text); + assert.ok(frontmatter, relativePath); + + const document = parseDocument(frontmatter[1], { uniqueKeys: true }); + assert.equal(document.errors.length, 0, relativePath); + + const header = document.toJS(); + assert.equal(header.name, skill); + assert.ok(!("owner" in header)); + assert.ok(!("metadata" in header)); + assert.ok(!("version" in header)); + assertPublicText(text, relativePath); +} + +assert.ok(!fs.existsSync(path.join(pluginRoot, ".mcp.json"))); +assert.ok(!fs.existsSync(path.join(pluginRoot, "mcp"))); + +const workflowFiles = [ + "README.md", + "FEEDBACK.md", + "com.github.copilot/agents/diagnostician.agent.md", + "com.github.copilot/agents/contrarian.agent.md", + "skills/windbg-diagnostic-method/SKILL.md", +]; + +for (const relativePath of workflowFiles) { + const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); + assertPublicText(text, relativePath); +} + +const confidenceContractFiles = [ + "README.md", + "com.github.copilot/agents/diagnostician.agent.md", + "com.github.copilot/agents/contrarian.agent.md", + "skills/windbg-diagnostic-method/SKILL.md", + "skills/windbg-diagnostic-method/scripts/validate-diagnosis-output.ps1", +]; + +for (const relativePath of confidenceContractFiles) { + const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); + assert.match(text, /fix_confidence/, `${relativePath} omits fix_confidence`); + assert.match( + text, + /fix_code_path_coverage/, + `${relativePath} omits fix_code_path_coverage`, + ); +} + +assert.ok( + fs.existsSync( + path.join( + pluginRoot, + "skills", + "windbg-diagnostic-method", + "scripts", + "validate-diagnosis-output.ps1", + ), + ), +); + +console.log( + `Validated ${inventory.diagnosticSkills.length} diagnostic skills, ` + + `${inventory.methodSkills.length} method skill, agent workflow, ` + + "validator script, and public-only links.", +); From 977859c2a0fc9e8ed37ff7b0b45b1e925f6cb1f5 Mon Sep 17 00:00:00 2001 From: Rade Trimceski Date: Wed, 7 Oct 2026 11:20:46 -0700 Subject: [PATCH 4/5] Remove legacy diagnostician validation scripts Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- ...test-debugging-diagnostician-validator.mjs | 134 ------------------ scripts/validate-debugging-diagnostician.mjs | 130 ----------------- 2 files changed, 264 deletions(-) delete mode 100644 scripts/tests/test-debugging-diagnostician-validator.mjs delete mode 100644 scripts/validate-debugging-diagnostician.mjs diff --git a/scripts/tests/test-debugging-diagnostician-validator.mjs b/scripts/tests/test-debugging-diagnostician-validator.mjs deleted file mode 100644 index 7c76043a..00000000 --- a/scripts/tests/test-debugging-diagnostician-validator.mjs +++ /dev/null @@ -1,134 +0,0 @@ -import assert from "node:assert/strict"; -import fs from "node:fs"; -import os from "node:os"; -import path from "node:path"; -import { spawnSync } from "node:child_process"; -import { fileURLToPath } from "node:url"; - -const repositoryRoot = path.resolve( - path.dirname(fileURLToPath(import.meta.url)), - "..", - "..", -); -const validator = path.join( - repositoryRoot, - "plugins", - "debugging-diagnostician", - "skills", - "validate-diagnosis-output", - "scripts", - "validate-diagnosis-output.ps1", -); -const temporaryDirectory = fs.mkdtempSync( - path.join(os.tmpdir(), "diagnosis-validator-"), -); - -const validReport = `## Analysis -Observed evidence. - -## Root Cause -Candidate cause. - -## Fix -Candidate fix. - -## Reasoning Chain -OBSERVE: evidence. - -## Alternatives Considered -- Alternative one -- Alternative two - -## Trigger Verification -| Evidence | Status | -|---|---| -| Trigger | VERIFIED | - -## Mermaid -\`\`\`mermaid -sequenceDiagram -A->>B: request -B-->>A: response -\`\`\` - -## Contrarian Verdict -ACCEPTED - -contrarian_loopback: false - -## JSON Output Contract Summary -\`\`\`json -{"diagnosis_status":"final","routing_path":"validate","root_cause":"cause","confidence":0.8,"fix_confidence":0.7,"fix_code_path_coverage":"symbol-or-disassembly","contrarian_review":"ACCEPTED","contrarian_loopback":false} -\`\`\` -`; - -const invalidReport = `## Analysis -The words OBSERVE and VERIFIED appear outside their required sections. - -## Root Cause -Candidate cause. - -## Fix -Candidate fix. - -## Reasoning Chain -No phase marker appears here. - -## Alternatives Considered -- Only one alternative - -## Trigger Verification -No table appears here. - -## Mermaid -\`\`\`mermaid -sequenceDiagram -participant A -\`\`\` - -## Contrarian Verdict -ACCEPTED - -contrarian_loopback: 1 - -## JSON Output Contract Summary -\`\`\`json -{"diagnosis_status":"final","routing_path":"validate","root_cause":"cause","confidence":0.8,"fix_confidence":0.7,"fix_code_path_coverage":"symbol-or-disassembly","contrarian_review":"ACCEPTED","contrarian_loopback":1} -\`\`\` -`; - -function runValidator(file) { - return spawnSync( - "pwsh", - ["-NoProfile", "-File", validator, "-Path", file], - { encoding: "utf8" }, - ); -} - -try { - const validPath = path.join(temporaryDirectory, "valid.md"); - const invalidPath = path.join(temporaryDirectory, "invalid.md"); - fs.writeFileSync(validPath, validReport); - fs.writeFileSync(invalidPath, invalidReport); - - const validResult = runValidator(validPath); - assert.equal(validResult.status, 0, validResult.stderr || validResult.stdout); - const validOutput = JSON.parse(validResult.stdout); - assert.equal(validOutput.Pass, true); - assert.equal(validOutput.Checks.MermaidDiagram, true); - - const invalidResult = runValidator(invalidPath); - assert.equal(invalidResult.status, 1, invalidResult.stderr); - const invalidOutput = JSON.parse(invalidResult.stdout); - assert.equal(invalidOutput.Pass, false); - assert.equal(invalidOutput.Checks.ReasoningChain, false); - assert.equal(invalidOutput.Checks.Alternatives, false); - assert.equal(invalidOutput.Checks.TriggerVerification, false); - assert.equal(invalidOutput.Checks.MermaidDiagram, false); - assert.equal(invalidOutput.Checks.ContrarianVerdict, false); - assert.equal(invalidOutput.Checks.JsonSummary, false); - - console.log("Diagnosis validator accepts valid reports and rejects malformed sections."); -} finally { - fs.rmSync(temporaryDirectory, { recursive: true, force: true }); -} diff --git a/scripts/validate-debugging-diagnostician.mjs b/scripts/validate-debugging-diagnostician.mjs deleted file mode 100644 index a295546c..00000000 --- a/scripts/validate-debugging-diagnostician.mjs +++ /dev/null @@ -1,130 +0,0 @@ -import assert from "node:assert/strict"; -import fs from "node:fs"; -import path from "node:path"; -import { createRequire } from "node:module"; -import { fileURLToPath } from "node:url"; - -const repositoryRoot = path.resolve( - path.dirname(fileURLToPath(import.meta.url)), - "..", -); -const pluginRoot = path.join( - repositoryRoot, - "plugins", - "debugging-diagnostician", -); -const require = createRequire( - path.join(repositoryRoot, "scripts", "vally", "package.json"), -); -const { parseDocument } = require("yaml"); - -const inventory = JSON.parse( - fs.readFileSync(path.join(pluginRoot, "skills.json"), "utf8"), -); -assert.deepEqual(inventory.auxiliarySkills, ["validate-diagnosis-output"]); - -const allowedSkills = [ - ...inventory.diagnosticSkills, - ...inventory.auxiliarySkills, -].sort(); -const skillDirectories = fs - .readdirSync(path.join(pluginRoot, "skills"), { withFileTypes: true }) - .filter((entry) => entry.isDirectory()) - .map((entry) => entry.name) - .sort(); -assert.deepEqual(skillDirectories, allowedSkills); - -const allowedUrlHosts = new Set([ - "agent-plugins.org", - "devblogs.microsoft.com", - "github.com", - "learn.microsoft.com", -]); - -function assertPublicText(text, label) { - for (const match of text.matchAll(/https?:\/\/[^\s<>"'`]+/g)) { - const value = match[0].replace(/[),.;:]+$/, ""); - const host = new URL(value).hostname.toLowerCase(); - assert.ok( - allowedUrlHosts.has(host), - `${label} references unapproved URL host ${host}`, - ); - } - - assert.doesNotMatch( - text, - /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i, - `${label} contains an email address`, - ); -} - -for (const skill of skillDirectories) { - const relativePath = path.join("skills", skill, "SKILL.md"); - const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); - const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text); - assert.ok(frontmatter, relativePath); - - const document = parseDocument(frontmatter[1], { uniqueKeys: true }); - assert.equal(document.errors.length, 0, relativePath); - - const header = document.toJS(); - assert.equal(header.name, skill); - assert.ok(!("owner" in header)); - assert.ok(!("metadata" in header)); - assert.ok(!("version" in header)); - assertPublicText(text, relativePath); -} - -assert.ok(!fs.existsSync(path.join(pluginRoot, ".mcp.json"))); -assert.ok(!fs.existsSync(path.join(pluginRoot, "mcp"))); - -const workflowFiles = [ - "README.md", - "FEEDBACK.md", - "com.github.copilot/agents/diagnostician.agent.md", - "com.github.copilot/agents/contrarian.agent.md", - "com.github.copilot/instructions/diagnostic-reasoning.instructions.md", - "com.github.copilot/instructions/root-cause-analysis.instructions.md", -]; - -for (const relativePath of workflowFiles) { - const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); - assertPublicText(text, relativePath); -} - -const confidenceContractFiles = [ - "README.md", - "com.github.copilot/agents/diagnostician.agent.md", - "com.github.copilot/agents/contrarian.agent.md", - "com.github.copilot/instructions/diagnostic-reasoning.instructions.md", - "skills/validate-diagnosis-output/SKILL.md", - "skills/validate-diagnosis-output/scripts/validate-diagnosis-output.ps1", -]; - -for (const relativePath of confidenceContractFiles) { - const text = fs.readFileSync(path.join(pluginRoot, relativePath), "utf8"); - assert.match(text, /fix_confidence/, `${relativePath} omits fix_confidence`); - assert.match( - text, - /fix_code_path_coverage/, - `${relativePath} omits fix_code_path_coverage`, - ); -} - -assert.ok( - fs.existsSync( - path.join( - pluginRoot, - "skills", - "validate-diagnosis-output", - "scripts", - "validate-diagnosis-output.ps1", - ), - ), -); - -console.log( - `Validated ${inventory.diagnosticSkills.length} diagnostic skills, ` + - `${inventory.auxiliarySkills.length} auxiliary skill, agent workflow, ` + - "validator script, and public-only links.", -); From 790b577d39157a369359634e5a5c9ef8cc6aa4b9 Mon Sep 17 00:00:00 2001 From: Nikola Metulev <711864+nmetulev@users.noreply.github.com> Date: Wed, 7 Oct 2026 13:51:58 -0700 Subject: [PATCH 5/5] Tighten windbg skill loading guidance - Shorten windbg-user-exception-triage description to 271 chars (under the 300-char bar) while keeping the managed .NET / WinUI exclusions. - Ask each bug-family skill to load windbg-diagnostic-method first, so Claude-family models apply the method without the Copilot agent (Sonnet co-load 1/17 -> 10/17 in routing benchmark; no routing or false-positive regressions). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../windbg/skills/windbg-kernel-bugcheck-triage/SKILL.md | 7 ++++--- .../skills/windbg-kernel-irp-lifecycle-triage/SKILL.md | 7 ++++--- .../skills/windbg-kernel-lock-deadlock-triage/SKILL.md | 7 ++++--- .../windbg/skills/windbg-kernel-verifier-triage/SKILL.md | 7 ++++--- .../windbg/skills/windbg-user-exception-triage/SKILL.md | 9 +++++---- .../windbg-user-heap-corruption-investigation/SKILL.md | 7 ++++--- .../windbg-user-mutex-held-across-co-await/SKILL.md | 7 ++++--- .../windbg-user-ttd-reverse-debugging-triage/SKILL.md | 7 ++++--- .../windbg-user-virtual-memory-exhaustion/SKILL.md | 7 ++++--- .../skills/windbg-user-wait-chain-analysis/SKILL.md | 7 ++++--- 10 files changed, 41 insertions(+), 31 deletions(-) diff --git a/plugins/windbg/skills/windbg-kernel-bugcheck-triage/SKILL.md b/plugins/windbg/skills/windbg-kernel-bugcheck-triage/SKILL.md index 7c5dd7c7..022fb8f7 100644 --- a/plugins/windbg/skills/windbg-kernel-bugcheck-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-kernel-bugcheck-triage/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when a kernel dump reports a Windows bugcheck; decode paramete # Kernel Bugcheck Triage -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-kernel-irp-lifecycle-triage/SKILL.md b/plugins/windbg/skills/windbg-kernel-irp-lifecycle-triage/SKILL.md index 1b64b93b..ee366f36 100644 --- a/plugins/windbg/skills/windbg-kernel-irp-lifecycle-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-kernel-irp-lifecycle-triage/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when kernel evidence shows stalled I/O, a power IRP, or comple # IRP Lifecycle Triage -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-kernel-lock-deadlock-triage/SKILL.md b/plugins/windbg/skills/windbg-kernel-lock-deadlock-triage/SKILL.md index ee70c7a6..81807fe9 100644 --- a/plugins/windbg/skills/windbg-kernel-lock-deadlock-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-kernel-lock-deadlock-triage/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when kernel threads block on driver synchronization or Verifie # Kernel Lock and Deadlock Triage -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-kernel-verifier-triage/SKILL.md b/plugins/windbg/skills/windbg-kernel-verifier-triage/SKILL.md index a14cc957..b1e4183e 100644 --- a/plugins/windbg/skills/windbg-kernel-verifier-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-kernel-verifier-triage/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when a kernel dump contains Driver Verifier violations; inspec # Driver Verifier Triage -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-user-exception-triage/SKILL.md b/plugins/windbg/skills/windbg-user-exception-triage/SKILL.md index 48e6034e..9492cd35 100644 --- a/plugins/windbg/skills/windbg-user-exception-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-user-exception-triage/SKILL.md @@ -1,13 +1,14 @@ --- 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; establish context and classify it. Not for managed .NET exceptions, WinUI/XAML app errors, or kernel bugchecks.' +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 -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-user-heap-corruption-investigation/SKILL.md b/plugins/windbg/skills/windbg-user-heap-corruption-investigation/SKILL.md index 1dc8ee24..8a3c6167 100644 --- a/plugins/windbg/skills/windbg-user-heap-corruption-investigation/SKILL.md +++ b/plugins/windbg/skills/windbg-user-heap-corruption-investigation/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when an app, service, or user-mode driver host heap fails or A # Heap Corruption Investigation -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-user-mutex-held-across-co-await/SKILL.md b/plugins/windbg/skills/windbg-user-mutex-held-across-co-await/SKILL.md index 8a389a95..5d3385c2 100644 --- a/plugins/windbg/skills/windbg-user-mutex-held-across-co-await/SKILL.md +++ b/plugins/windbg/skills/windbg-user-mutex-held-across-co-await/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when app, service, or user-mode driver C++ coroutine code hold # Mutex Held Across co_await -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-user-ttd-reverse-debugging-triage/SKILL.md b/plugins/windbg/skills/windbg-user-ttd-reverse-debugging-triage/SKILL.md index b0332dba..e587398e 100644 --- a/plugins/windbg/skills/windbg-user-ttd-reverse-debugging-triage/SKILL.md +++ b/plugins/windbg/skills/windbg-user-ttd-reverse-debugging-triage/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when an app, service, or user-mode driver host TTD recording i # TTD Reverse Debugging Triage -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-user-virtual-memory-exhaustion/SKILL.md b/plugins/windbg/skills/windbg-user-virtual-memory-exhaustion/SKILL.md index 2d8eac51..b1c036ee 100644 --- a/plugins/windbg/skills/windbg-user-virtual-memory-exhaustion/SKILL.md +++ b/plugins/windbg/skills/windbg-user-virtual-memory-exhaustion/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when a native app, service, or user-mode driver host allocatio # Virtual Memory Exhaustion -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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 diff --git a/plugins/windbg/skills/windbg-user-wait-chain-analysis/SKILL.md b/plugins/windbg/skills/windbg-user-wait-chain-analysis/SKILL.md index 13820952..b8ff3df4 100644 --- a/plugins/windbg/skills/windbg-user-wait-chain-analysis/SKILL.md +++ b/plugins/windbg/skills/windbg-user-wait-chain-analysis/SKILL.md @@ -5,9 +5,10 @@ description: 'Use when an app, service, or user-mode driver host is unresponsive # Cross-Process Wait Chain Analysis -Apply `windbg-diagnostic-method` throughout this investigation for evidence -ranking, hypothesis testing, confidence calibration, independent review, and -report validation. +**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