# debug-live

Adopt this skill: https://proskills.md/skills/other/microsoft-debugmcp-skills-debug-live

Page: https://proskills.md/skills/other/microsoft-debugmcp-skills-debug-live
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/debug-live/SKILL.md
size: 8063
upstream: https://github.com/microsoft/debugmcp/blob/main/skills/debug-live/SKILL.md

```text
---
name: debug-live
description: Guides root-cause investigations with debugging capabilities by setting breakpoints, starting a debug session, stepping through execution, inspecting variables, and tracing symptoms back to their origin. Prefer it for runtime bugs, failing tests, exceptions, crashes, hangs, wrong/null values, and unexpected output when live inspection is practical. Use this skill instead of modifying source code with temporary logs, print statements, or console output.
license: MIT
allowed-tools:
  - add_breakpoint
  - add_logpoint
  - remove_breakpoint
  - clear_all_breakpoints
  - list_breakpoints
  - start_debugging
  - stop_debugging
  - restart_debugging
  - step_over
  - step_into
  - step_out
  - continue_execution
  - pause_execution
  - get_debug_status
  - list_variable_names
  - get_variables_values
  - evaluate_expression
---

# DebugMCP — Interactive Debugging Skill

This skill teaches an agent how to use the DebugMCP MCP server effectively. The MCP server
itself exposes only tools (with brief, behavioral descriptions); the *workflow*, *root cause
analysis framework*, and *language-specific guidance* live here.

> The `allowed-tools` list above uses the tool names registered by the DebugMCP MCP server.
> Some runtimes namespace MCP tools (e.g. `mcp__debugmcp__start_debugging`); adapt as needed.

---

## When to invoke this skill

Invoke this skill as the **first investigation step** whenever you would otherwise guess
at runtime behavior:

- Any reported bug, failing test, exception, or unexpected output.
- A variable holds an unexpected `null` / `undefined` / wrong type / wrong value.
- A function returns something the caller didn't expect.
- A code path executes (or fails to execute) when you didn't predict it would.
- You're about to read a large amount of code "trying to figure out what happens at runtime."

---

## Core workflow

1. **Set a starting breakpoint.** Use `add_breakpoint` with the file path and the 1-based
   line number you want to pause on. Place it at the earliest point that's still
   relevant to the suspected issue.
2. **Optionally add strategic breakpoints.** Decision points, error-handling branches,
   data boundaries (where input enters, where output is produced).
3. **Start the session.** Call `start_debugging` with the source file path. For a single
   test, pass `testName`; the server routes through VS Code's Testing API so test runners
   like `dotnet test` / `pytest` / `jest` work correctly. The call returns when the
   program either hits a breakpoint (`stopped`) or runs to completion without pausing
   (`terminated`).
4. **Navigate and inspect.** Use `step_over`, `step_into`, `step_out`, `continue_execution`
   to move through code. Use `pause_execution` to interrupt a freely-running program
   (e.g. a busy loop or embedded target) when there is no breakpoint to stop at.
   Use `list_variable_names` to see what is in scope (names and types only, no values),
   then `get_variables_values` with the specific `variableNames` you care about, and
   `evaluate_expression` to test hypotheses live (call methods, read properties, run
   list comprehensions, etc.).

   > `get_variables_values` **requires** explicit `variableNames` — it will not dump the
   > whole scope. This is deliberate: a scope dump hands you unrelated process state such
   > as API keys, tokens and environment variables. Values that still look like credentials
   > are replaced with `<redacted: possible secret>`; don't try to work around it.
5. **Find the root cause** (see framework below). Don't stop at the first wrong thing
   you see — trace it back to *why*.
6. **Clean up.** Call `clear_all_breakpoints` when you're done so you don't pollute the
   next session, and `stop_debugging` if the session is still active.

---

## 🚨 Root cause analysis framework

### Never stop at symptoms — always find the root cause

When you encounter an issue during debugging (null variable, unexpected value, thrown
error, wrong branch taken), apply this systematic approach.

#### Symptom vs root cause

- **Symptom:** what you observed is wrong (e.g. "variable `user` is null").
- **Root cause:** *why* the symptom occurred (e.g. "`user` is null because `getUserById()`
  returned null because the DB query failed because the connection string in
  `appsettings.json` points at the wrong host").

#### Investigation process

1. **Identify the symptom.** What exactly is wrong? Which line, which variable, which
   thrown exception? Record the current state.
2. **Ask "why?"** Why is this value wrong? Why did this function return this? Why did
   this condition evaluate this way?
3. **Trace backwards.** Set a breakpoint *before* the symptom, restart, and step
   forward to watch where the wrong state first appears.
4. **Repeat until you reach the origin.** Keep asking "why" until you hit a fundamental
   cause — usually where data enters the system, a config is read, or an assumption
   is first violated.

#### ⚠️ Warning signs you're stopping too early

- You found a `null` / `undefined` variable but didn't check why it's that way.
- You see an error but didn't trace where it originates.
- You identified "bad data" but didn't find why the data is bad.
- You found a failing condition but didn't check why it fails.

#### ✅ Signs you've found the root cause

- You can explain the complete chain from root cause → symptom.
- Fixing this one thing would prevent the symptom from occurring.
- The issue is at a fundamental level (data input, configuration, logic invariant).
- You understand not just *what* is wrong but *why* it's wrong.

---

## Practical examples

### Example 1 — Null variable
❌ **Symptom-only:** "The `user` object is null on line 45."
✅ **Root cause:** "`user` is null because `getUserById()` returned null because the DB
query failed because the connection string is incorrect in the configuration file."

**Investigation:**
1. `user` is null → set breakpoint in `getUserById()`.
2. `getUserById()` returns null → set breakpoint inside the function.
3. DB query fails → check connection parameters.
4. Connection string wrong → root cause identified.

### Example 2 — Function exits early
❌ **Symptom-only:** "`processOrder()` exits early due to invalid payment status."
✅ **Root cause:** "`processOrder()` exits early because payment validation fails when
the payment service doesn't receive the required `currency` field, which wasn't
included in the request due to a missing form field in the UI."

**Investigation:**
1. Function exits early → breakpoint at validation check.
2. Payment status invalid → debug payment validation logic.
3. `currency` missing → trace back to request formation.
4. UI form missing `currency` field → root cause identified.

### Example 3 — Unexpected value
❌ **Symptom-only:** "Calculation result is `NaN`."
✅ **Root cause:** "The result is `NaN` because one input is a string instead of a
number, because `parseFloat()` fails when the input contains currency symbols that
weren't stripped by the sanitization function."

**Investigation:**
1. Result is `NaN` → check input parameters.
2. Parameter is a string → find where conversion should happen.
3. `parseFloat()` fails → check what's being parsed.
4. Currency symbols not stripped → root cause identified.

---

## Root cause investigation checklist

Before ending the debug session, confirm you can answer:

- [ ] What is the immediate symptom?
- [ ] What function / code caused this symptom?
- [ ] What input or condition caused that function to behave incorrectly?
- [ ] Where did that input or condition originate?
- [ ] Can I trace this back further to a more fundamental cause?
- [ ] If I fix this root cause, will it prevent the symptom from occurring?

---

## Breakpoint strategy

- **Start broad, then narrow.** Begin at the entry point of the suspect function. As
  you isolate the issue, add tighter breakpoints around the problematic region.
- **Use line numbers.** `add_breakpoint` ta
```

## File: README.md
upstream: https://github.com/microsoft/debugmcp/blob/main/README.md

````text
# DebugMCP Skill

This folder is a self-contained **Agent Skill** that teaches an AI agent how to use the
DebugMCP MCP server effectively. It follows the Anthropic-style Skills convention: a
`SKILL.md` entry point with YAML frontmatter, plus bundled reference docs.

## Why this is separate from the MCP server

The DebugMCP MCP server exposes only **tools** (with brief, behavioral descriptions).
All workflow guidance — when to debug, how to structure a root-cause investigation,
which breakpoints to set, language-specific quirks — lives in this skill, not in tool
descriptions.

This separation matches modern agent ecosystems where:
- **MCP servers** = capabilities (tools, resources, prompts)
- **Skills** = procedural knowledge an agent loads as context

## Contents

```
skills/debugmcp/
├── SKILL.md                           # Entry point + workflow + root cause framework
├── README.md                          # This file
└── references/
    └── troubleshooting/
        ├── python.md
        ├── javascript.md
        ├── java.md
        ├── csharp.md
        ├── cpp.md
        ├── go.md
        └── ruby.md
```

## Installation

How you install a skill depends on your agent runtime. Common patterns:

- **Anthropic / Claude API with the Skills feature** — point the runtime at this folder
  (or vendor the folder into your project) and the agent will read `SKILL.md` and load
  references on demand.
- **Claude Code** — drop this folder under your project's configured skills directory.
- **Cursor / Cline / other clients without native skills support** — copy the contents
  of `SKILL.md` into a project rule / system prompt, and keep the `references/` files
  available for the agent to read on request.

Refer to your client's documentation for the exact path / mechanism.

## Tool naming

The `allowed-tools` list in `SKILL.md` uses the raw tool names registered by the
DebugMCP MCP server (`start_debugging`, `add_breakpoint`, etc.). Some runtimes namespace
MCP tools (e.g. `mcp__debugmcp__start_debugging`). Adapt the list to whatever convention
your runtime uses, or omit `allowed-tools` if the runtime doesn't honor it.

## Prerequisites

You also need:

1. The DebugMCP VS Code extension installed and running (it starts an MCP server on
   `http://127.0.0.1:3001/mcp` by default).
2. The language extension for whatever you're debugging (Python, C# Dev Kit, Java
   Extension Pack, etc. — see the per-language reference for specifics).
3. Your AI agent runtime configured to connect to that MCP endpoint.

## Live trigger evaluation

Run `npm run test:skill-trigger-agent` to launch a real Copilot CLI session and verify
from its JSON tool events that `debug-live` is the first tool invoked for the default
runtime-null scenario. This is an opt-in model evaluation: it requires an authenticated
Copilot CLI, consumes AI credits, and may be nondeterministic.

Pass a different prompt after `--`:

```text
npm run test:skill-trigger-agent -- "A runtime test hangs while processing a request"
```
````