Agentic Debugger

---
name: agentic-debugger
description: Reproduces a bug before fixing it, then verifies the fix with a guarded test run. Use when a developer hits a runtime error, a failing test, or "almost-correct" AI-generated code. Trigger phrases include "调试这个bug", "debug this error", "修复这个报错", "为什么报错了", "agentic debug", "复现并修复", "这个测试红了".
---

# agentic-debugger

A debugging skill built on one rule: never fix blind. Reproduce first,
apply the smallest possible fix, then prove it with a guarded test run.

## When to use

- A runtime traceback or stack trace was pasted in.
- A test is red and the cause is unclear.
- AI-generated code "looks about right" but behaves wrong.
- The user says any of: 调试这个bug / debug this error / 修复这个报错 /
  为什么报错了 / agentic debug / 复现并修复 / 这个测试红了.

## The loop

Follow these steps in order. Do not skip the reproduce step.

### 1. Locate — parse the trace

Read the pasted trace from stdin, or save it to a file and pass `--file`:

```bash
python scripts/parse_trace.py --file trace.txt
cat trace.txt | python scripts/parse_trace.py --format json
```

The report shows the failing `file:line`, the exception type, and the call
frames. Start your hypothesis from the deepest frame — that is where the
exception was raised.

### 2. Reproduce — build a minimal repro

```bash
python scripts/make_repro.py --file path/to/source.py --line <n> \
    --test-cmd "pytest tests/ -q"
```

This writes `test_repro.py` next to the source, with a call skeleton to the
enclosing function and one failing assert. Fill in the inputs that drive the
code to the failing line, then confirm the test is RED. A bug you cannot
reproduce is a bug you cannot prove you fixed.

### 3. Fix — make the smallest change

Edit only what the hypothesis requires. If the fix needs three lines, fine;
if it touches three files, you are probably solving the wrong problem.

### 4. Verify — run the guarded test

```bash
python scripts/run_guard.py pytest path/to/test_repro.py -q
```

If the command is missing, `run_guard` prints the install hint. All tests
must be green before you move on. If it stays red, the hypothesis was wrong
— go back to step 1. Do not pile on more changes.

### 5. Regress — run the project's full suite

```bash
python scripts/run_guard.py <the project's normal test command>
```

If anything else turned red, the fix was too broad; narrow it.

Iterate steps 2-5 until the repro is green and the full suite stays green.

## Exit criteria

Deliver only when all of the following hold:

- There is a red-before / green-after reproduction for the reported failure.
- The fix is the minimum diff that makes it green.
- The full suite passes under `run_guard`.

## References

- `references/debug-loop.md` — the repro-first loop in detail, with
  anti-patterns to avoid.