|
| 1 | +--- |
| 2 | +name: java-debug-inspection |
| 3 | +description: Use when inspecting a Java program that is already being debugged — read local variables, walk the call stack, list threads, evaluate expressions, step in/over/out, continue execution, or set / remove breakpoints in an active Java debug session. NOT for starting, launching, or stopping a debug session — use `java-launch-troubleshooting` for that. |
| 4 | +--- |
| 5 | + |
| 6 | +# Java Debug Inspection |
| 7 | + |
| 8 | +Use this skill when a Java debug session is already active (the user has launched the program with `debug_java_application` or via the VS Code Run/Debug UI) and they want to **observe or steer the running program**. Typical user phrases: |
| 9 | + |
| 10 | +- "what's the value of `user.id` right now?", "show me the local variables" |
| 11 | +- "evaluate `list.size()`", "what does `service.findById(42)` return at this frame?" |
| 12 | +- "show the stack trace", "what threads are running?", "go up one frame" |
| 13 | +- "step in", "step over", "step out", "continue", "resume" |
| 14 | +- "set a breakpoint at `OrderService.placeOrder`", "remove the breakpoint on line 42" |
| 15 | + |
| 16 | +If no debug session is active, this skill should not be used — load `java-launch-troubleshooting` first to start one. |
| 17 | + |
| 18 | +## Tools |
| 19 | + |
| 20 | +These language model tools are contributed by the `Debugger for Java` extension and are deferred. Activate them with `tool_search_tool_regex` using pattern `java_breakpoint|debug` before first use. |
| 21 | + |
| 22 | +| Tool | Purpose | |
| 23 | +|---|---| |
| 24 | +| `get_debug_variables` | Read local variables, fields, and watched expressions in the current frame. | |
| 25 | +| `get_debug_stack_trace` | List call-stack frames for the focused (or specified) thread. | |
| 26 | +| `get_debug_threads` | List all threads in the session with state (running, stopped, terminated). | |
| 27 | +| `evaluate_debug_expression` | Evaluate an arbitrary Java expression in the context of the focused frame. | |
| 28 | +| `debug_step_operation` | Step in, step over, step out, or continue. Requires the program to be paused. | |
| 29 | +| `set_java_breakpoint` | Set a line / method / exception breakpoint. Works at any time during the session. | |
| 30 | +| `remove_java_breakpoints` | Remove one or more breakpoints by ID or location. | |
| 31 | + |
| 32 | +## Preferred Workflow |
| 33 | + |
| 34 | +1. **Confirm session state.** If the user asks to step or evaluate an expression, the program must be paused (typically at a breakpoint). If unsure, call `get_debug_session_info` from `java-launch-troubleshooting` to check, or list threads with `get_debug_threads`. |
| 35 | +2. **Inspect first, then act.** For "what's the value of X" — call `get_debug_variables` or `evaluate_debug_expression`. Do not guess from source code. |
| 36 | +3. **Step / continue.** For "step over" / "step in" / "step out" / "continue", call `debug_step_operation` with the matching action. After each step, re-read variables or stack as needed. |
| 37 | +4. **Breakpoints.** For "set a breakpoint at …", call `set_java_breakpoint` with the file URI + line, or fully qualified method signature, or exception class. For "remove the breakpoint at …", call `remove_java_breakpoints`. |
| 38 | +5. **Report precisely.** Quote the exact value or stack frame returned by the tool — do not paraphrase. |
| 39 | + |
| 40 | +## Common Pitfalls |
| 41 | + |
| 42 | +| Symptom | Likely cause | Fix | |
| 43 | +|---|---|---| |
| 44 | +| `debug_step_operation` returns "thread is not paused" | The program is running, not stopped at a breakpoint | Ask the user to add a breakpoint first, or wait for the next stop event | |
| 45 | +| `evaluate_debug_expression` returns `<no active frame>` | No focused stack frame, often because the session just resumed | Re-call `get_debug_stack_trace` to refocus a frame | |
| 46 | +| `get_debug_variables` returns empty for a parameter | Compilation without `-g` (no local variable table) | Inform user; offer to inspect via `evaluate_debug_expression` instead | |
| 47 | +| Step in jumps into JDK internals | Default step filters disabled | Suggest enabling `java.debug.settings.stepping.skipClasses` | |
| 48 | + |
| 49 | +## When NOT to Use This Skill |
| 50 | + |
| 51 | +- The user wants to *start* a Java program (no session yet) → use `java-launch-troubleshooting` |
| 52 | +- The user wants to *stop* the session → use `stop_debug_session` from `java-launch-troubleshooting` |
| 53 | +- The program is a non-Java language → do not load this skill |
| 54 | +- The user is editing source code without an active debug session → do nothing |
| 55 | + |
| 56 | +## Fallback |
| 57 | + |
| 58 | +If a tool returns "Java Language Server not ready" or repeats the same error twice, report the raw error to the user and stop calling debug tools for the current turn. Do not retry more than twice. |
0 commit comments