Agent Skills › gnomeria/usbtree › debug

debug

GitHub

系统化根因调试技能，涵盖复现、隔离、修复及验证全流程。适用于报错、崩溃或测试失败场景，强调先定位根因再修改代码，避免盲目猜测。

.agents/skills/debug/SKILL.md gnomeria/usbtree

触发场景

用户报告bug或错误程序崩溃或行为异常提供堆栈跟踪或失败测试输出

安装

npx skills add gnomeria/usbtree --skill debug -g -y

更多选项

非标准路径

npx skills add https://github.com/gnomeria/usbtree/tree/main/.agents/skills/debug -g -y

不安装直接使用

npx skills use gnomeria/usbtree@debug

指定 Agent (Claude Code)

npx skills add gnomeria/usbtree --skill debug -a claude-code -g -y

安装 repo 全部 skill

npx skills add gnomeria/usbtree --all -g -y

预览 repo 内 skill

npx skills add gnomeria/usbtree --list

SKILL.md

Frontmatter

{
    "name": "debug",
    "description": "Systematic root-cause debugging — reproduce, isolate, fix at the source, prove the fix. Use when the user reports a bug, an error, a crash, flaky behavior, \"this doesn't work\", \"why is this failing\", or pastes a stack trace or failing test output."
}

Debug

Find root cause before touching code. Fix without understood cause = guess wearing fix's clothes.

Step 1 — Reproduce

Deterministic repro first: failing test, --demo --dump diff, exact key sequence in TUI. Can't trigger = can't prove fixed.
Read actual error verbatim — full message, full backtrace (RUST_BACKTRACE=1). Answer often in the line the eye skips.
Capture repro as failing #[test] now when feasible — becomes regression test in Step 5 for free.
Flaky: loop it (while cargo test bad_test; do :; done or -- --test-threads=1 to expose ordering) — establish failure rate before changing anything.

Step 2 — Shrink search space

Cheapest checks first:

Recent changes: git log --oneline -15, git diff HEAD~5 on touched area. Most bugs days old, not years. git bisect when known-good commit exists and repro is scriptable.
Boundaries: bad value born here or delivered here? Probe at boundary (sysfs read in, nusb descriptor in, tree flatten out) to decide which side owns bug.
Binary search: instrument midpoint, pick wrong half, repeat. No shotgunning ten prints — each probe answers one question.
One assumption per probe: "this sysfs path exists", "this branch runs", "usb.ids actually loaded". Verify, don't assume.

Step 3 — Root cause

Ask "why" past first plausible answer. Symptom: panic on unwrap. Cause: field None. Root cause: scan skips devices without that descriptor. Fix the scan.
Fixing shared fn? Grep callers first. Bug can bite them too → fix belongs in shared path, not the one caller from the report.
State root cause in one sentence. Can't = haven't found it — back to Step 2.

Step 4 — Fix

Smallest change removing root cause. No drive-by refactors (see refactor skill).
Real fix large + something bleeding? Guard + TODO acceptable — say it's mitigation, name real fix, don't call bug closed.

Step 5 — Prove it

Step 1 repro now passes. cargo test green. cargo clippy -- -D warnings clean.
Remove every temp probe/eprintln!.
Report: root cause (one sentence), fix, verification. Tests still fail → say so.

Rust probes

RUST_BACKTRACE=1 (or =full) on any panic.
cargo test bad_test -- --nocapture — isolate one test, see prints.
dbg!(expr) over println! — shows file:line + expression, greppable to remove.
TUI eats stdout: probe with eprintln! + 2>/tmp/probe.log, or drop to --dump path where prints are visible.
No hardware / weird topology: reproduce in --demo, or fake sysfs dir if bug is linux-path parsing.