debug

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:

1. 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.
2. 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.
3. Binary search: instrument midpoint, pick wrong half, repeat. No shotgunning ten prints — each probe answers one question.
4. 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.