whaojie797-design 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:
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
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
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
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.