targeted-debug

Files (6)

• SKILL.md
• evals.json · evals/
• trigger-evals.json · evals/
• language-patterns.md · references/
• scope-decisions.md · references/
• extract-error-paths.sh · scripts/

SKILL.md (first lines)

# Targeted Debug

Scope-bounded debugging. Reads **only** files explicitly named in the stack trace or by the user. Forms a hypothesis from observable evidence. Does NOT explore the codebase broadly. Does NOT launch a full investigation pipeline.

Find the repo root with `git rev-parse --show-toplevel`. If `git` is unavailable, treat every path as relative to the working directory and say so in the report rather than guessing a root.

## Why this skill exists

When a stack trace or error message is already in hand, broad codebase exploration adds noise without improving signal. A full investigation session is for "I don't know what's happening" — this skill is for "here's the crash, tell me why." The strict scope constraint (read only what's named) is what makes it fast, token-efficient, and precise.

## Path extraction (use the bundled script)

A deterministic path extractor is available at `scripts/extract-error-paths.sh`. Run it on the raw stack trace to get the exact file list — no manual parsing needed:

```bash
# From the repo root — feed a stack trace file to the extractor
bash scripts/extract-error-paths.sh < stacktrace.txt

# Or pass it inline
bash scripts/extract-error-paths.sh "at Foo.bar(Foo.java:42) caused by NullPointerException"
```

Output is one path per line, sorted, deduplicated. Use this list as your in-scope file set.

Recognized trace shapes:
| Language | Example frame | Extracted path |
|----------|--------------|----------------|
| Java/Scala | `at Foo.bar(Foo.scala:42)` | `Foo.scala` |
| JavaScript | `at Object.<anon> (/repo/lib/foo.js:12:7)` | `/repo/lib/foo.js` |
| Python | `File "/repo/src/parser.py", line 87, in parse` | `/repo/src/parser.py` |
| Bash | `script.sh: line 42:` | `script.sh` |
| Rust | `at src/handlers/payment.rs:91:42` | `src/handlers/payment.rs` |
| Go | `\t/app/services/order.go:114 +0x1c2` | `/app/services/order.go` |
| Generic (Vim) | `path/to/file.py:42` | `path/to/file.py` |

**Vendor/stdlib exclusion:** The extractor automatically suppresses paths from `~/.cargo/`, the Go cache under `~/go/pkg/`, `/usr/local/go/src/`, and `node_modules/`. If a trace mixes project files with runtime internals, only project-source paths remain in the output.

For language-specific panic patterns and scope rules (Rust unwrap, Go nil pointer, Bash set -u), see `references/language-patterns.md`.

## Workflow

### 1. Parse input and build the in-scope file set

Accept one or more of: pasted stack trace, error signature, explicit file paths, issue description with a concrete error.

Run the extractor (or extract manually if the trace is trivial):

```bash
# resolve relative paths against repo root
git rev-parse --show-toplevel
```

**In-scope files** = files the user named + files the extractor found in the trace. That's the complete list — nothing else.

### 2. Hypothesize from the trace ALONE (before reading any file)

State in chat: the thrown exception, the frame that threw it, the call chain leading to it. This step forces reasoning from the evidence already provided before adding new evidence.

Example hypothesis statement:
> "The `NullPointerException` is thrown at `UserService.java:142`. The chain shows it was called from `OrderController.java:88`. My hypothesis: a null `User` object is being dereferenced — either `findUser()` returned null and the caller didn't check."

### 3. Read only the in-scope files (targeted sections)

For each file, read the **section relevant to the stack frame** — the failing function and its immediate local callers within the same file. Do not read entire 1000-line files.

```bash
# Confirm the file exists before reading
ls -la path/to/File.java

# Check git blame on the failing lines to see when they changed
git log -n 5 --oneline -- path/to/File.java
git blame -L 138,148 path/to/File.java
```

### 4. Refine the hypothesis

Combine trace evidence with code evidence. Three outcomes:

| Outcome | Meaning | Next step |
|---------|---------|-----------|
| **Confirmed** | Code clearly produces the observed error | Report root cause + fix |
| **Refined** | Trace was misleading; real cause is upstream | Report new hypothesis, name ONE additional file (ask user before reading) |
| **Insufficient** | In-scope files don't reveal a single root cause | Say so explicitly — name what additional evidence is needed |

### 5. Produce the structured diagnosis

The diagnosis is a **structured finding**, in the same shape every reviewer role in this
framework emits (`core/roles/reviewer.md`). That is deliberate: an orchestrator merging a
debugger's output with a reviewer's, a security reviewer's and a test engineer's must not
need a special case for this skill.

```
## Hypothesis (from stack trace, before reading code)
<one paragraph from step 2>

## Finding
| Field | Value |
|-------|-------|
| severity | critical \| high \| medium \| low |
| confidence | high \| medium \| low |
| files | <path:line>, <path:line> — in-scope files only |
| evidence | <the specific lines / signatures that confirm or refute the hypothesis> |
| recommended_fix | <the smallest concrete change, with file:line> |
| blocking | true \| false |

## Root cause
<the proximate cause — one sentence. If undetermined, write "undetermined" and set
confidence to low. Never invent one to fill the field.>

## Out-of-scope follow-ups
- <file NOT read but potentially relevant> — <one-line justification>
- Whether a broader investigation session is now warranted
```

Field discipline:

- **severity** describes the defect's impact on the system, not how hard it was to find.
- **confidence** is about this diagnosis being correct. An "Insufficient" outcome in step 4
  means `confidence: low` and `root cause: undetermined` — it does not mean guessing

From Tamircohen28/tamirs-superpowers, MIT.

More from Tamircohen28/tamirs-superpowers