/debug-live

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. `ge