skill_debug

Purpose

This document defines a self-directed debugging workflow for a Large Language Model (LLM) operating inside or alongside Visual Studio Code: (VS Code:). The goal is for the LLM to:

1. Inspect a codebase without human intervention
2. Identify likely failure points
3. Insert breakpoints programmatically
4. Generate a valid VS Code: launch.json debugging configuration
5. Enter VS Code: debug mode
6. Capture runtime errors, logs, and stack traces
7. Filter noise while preserving full raw error telemetry
8. Transmit all collected diagnostic data back to the LLM for analysis

This workflow assumes the LLM has:

• Read access to the workspace
• Write access to configuration files
• The ability to invoke VS Code: commands (directly or via an agent/tooling layer)

---

High-Level Debugging Strategy

The LLM must operate as a deterministic debugger, not a conversational assistant.

Core principles:

• Prefer evidence over speculation
• Favor runtime inspection over static guesses
• Never suppress errors at source
• Always preserve original error output

---

Step 1: Workspace Reconnaissance

1. Enumerate the workspace root
2. Identify:
   • Primary language(s)
   • Entry points (e.g. main.py, index.js, app.ts, Program.cs)
   • Existing test suites
   • Existing .vscode configuration
3. Detect build systems and runtimes:
   • Node.js, Python, Java, .NET, Go, etc.

Output a workspace map internally before proceeding.

---

Step 2: Static Code Analysis

For each execution path:

1. Parse the AST (or equivalent)
2. Identify:
   • Unhandled exceptions
   • Unsafe casts
   • Null/undefined dereferences
   • Infinite loops
   • Race conditions (async / threading)
   • External I/O boundaries (filesystem, network, DB)

Mark all high-risk lines.

---

Step 3: Breakpoint Placement Heuristics

Automatically insert breakpoints at:

• Program entry point
• All caught and uncaught exception blocks
• Function boundaries with:
  • Complex conditionals
  • State mutation
  • External side effects
• Before and after async boundaries
• Any line referenced in stack traces from prior runs