ide-debug

name	ide-debug
description	Full debug workflow using IDE bridge tools. Runs tests to find failures, sets conditional breakpoints, evaluates expressions in the debugger, identifies root causes, applies fixes, and verifies. Use when debugging test failures or runtime issues.
disable-model-invocation	true
effort	high
argument-hint	[test filter or file path]

IDE Debug Workflow

Prerequisites

1. Check if the getToolCapabilities MCP tool is available to you.

   • Not available (no MCP tool by that name): stop and tell the user: "This skill requires the Claude IDE Bridge with a connected VS Code extension. It uses debug tools (breakpoints, debugger evaluation, debug state) that have no CLI equivalent.

     To use this skill:

     1. Start the bridge: npm run start-all (in claude-ide-bridge/)
     2. Ensure the Claude IDE Bridge extension is installed in your IDE
     3. Use the claude --ide session (not remote-control)

     Alternative: run tests directly via npm test to identify failures."

   • Available: call it. If extensionConnected is false: show the same message. If true: proceed.

Run a complete debug cycle using the IDE bridge's debug and test tools. This workflow automates what would normally require switching between terminal, editor, and debugger.

Workflow

Phase 1: Identify the failure

1. Run tests using runTests with the provided filter argument: $ARGUMENTS
   • If no argument provided, run the full test suite
2. If all tests pass, report success and stop
3. For each failure, note the file, line, test name, and error message

Phase 2: Set up debugging

4. For the first failing test, use goToDefinition or openFile to navigate to the failing code
5. Use getDocumentSymbols on the test file to understand the test structure
6. Use setDebugBreakpoints to set a breakpoint at the assertion line or the line referenced in the error
   • Use conditional breakpoints when the error message suggests a specific condition

Phase 3: Inspect runtime state

7. Use startDebugging with the appropriate debug configuration
   • For vitest/jest: look for "Vitest" or "Jest" debug configs
   • For pytest: look for "Python" debug configs
8. When the breakpoint hits, use evaluateInDebugger to inspect:
   • The variables mentioned in the error message
   • The expected vs actual values
   • Any intermediate computation results
9. Use getDebugState to examine the full call stack and scope variables
10. Use stopDebugging once you've identified the root cause

Phase 4: Fix and verify

11. Explain the root cause clearly
12. Use editText to apply the minimal fix
13. Use saveDocument to save the changed file
14. Re-run the failing test with runTests to verify the fix
15. If the fix introduces new failures, report them

Phase 5: Clean up

16. Use clearEditorDecorations to remove any debug highlights
17. Summarize: what was wrong, what was fixed, and what tests now pass

Guidelines

• Always explain the root cause before fixing
• Prefer minimal fixes over refactoring
• If you can't reproduce the failure in the debugger, fall back to adding strategic logging via editText and re-running
• If no debug configuration exists, suggest creating one