debug-investigator
Debug Investigator replaces ad-hoc troubleshooting with structured investigation: capture symptoms, build a reproducible feedback loop, analyze evidence from stacktraces and logs, generate ranked hypotheses, and design bisection strategies. Use it for non-obvious bugs—intermittent failures, performance regressions, or issues requiring systematic root cause analysis—where native debugging falls short.
Debug Investigator helps you systematically investigate bugs through hypothesis-driven methodology, evidence analysis, and bisection strategies.
AI-generated summary based on this skill's SKILL.md
Install
Mathews-Tom/armory/debug-investigator · repository language: Python
git clone https://github.com/Mathews-Tom/armory
cp -r armory/skills/debug-investigator ~/.claude/skills/debug-investigatornpx skillfed install Mathews-Tom/armory/debug-investigatorFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I debug systematically with Debug Investigator?
Debug Investigator guides you through structured investigation: first capture detailed symptoms and build a reproducible feedback loop, then analyze evidence from stacktraces and logs to generate ranked hypotheses about the root cause. For each hypothesis, design targeted instrumentation and bisection strategies to test it. This hypothesis-driven methodology replaces ad-hoc troubleshooting, especially for non-obvious bugs like intermittent failures or performance regressions where native debugging falls short.
What's the best way to rank bug hypotheses?
Debug Investigator helps you rank competing hypotheses by likelihood and testability. Start by listing all plausible explanations for the observed symptoms, then score each by how well it explains the evidence and how easily you can test it. Prioritize hypotheses that are both probable and quick to validate. This ranking approach focuses your investigation effort on the most promising leads first, accelerating root cause discovery.
How can git bisect help find when a bug was introduced?
Debug Investigator incorporates git bisect as a core debugging strategy to narrow down exactly which commit introduced a bug. Bisect performs a binary search through your commit history, testing each midpoint to identify the culprit commit. This is especially powerful when you know a feature worked in the past but fails now—bisect automates the detective work and pinpoints the exact change responsible.
How do I isolate intermittent failures with no clear stacktrace?
Debug Investigator tackles intermittent and non-obvious failures by designing a minimal reproduction strategy and targeted instrumentation points. Capture timing, concurrency context, and system state around failures. Build a reproducible feedback loop by adding logging or monitoring at suspected failure sites. Generate hypotheses about race conditions or timing-dependent bugs, then use bisection or targeted instrumentation to validate each one systematically.
What steps should I follow to create a minimal reproduction?
Debug Investigator emphasizes minimal reproduction as a foundation for investigation. Strip away unrelated code and dependencies until you have the smallest possible case that triggers the bug. Document exact steps, inputs, and environment conditions needed to reproduce it. A solid minimal repro enables faster hypothesis testing, easier collaboration with teammates, and clearer root cause analysis once you isolate the problem.
When should I use Debug Investigator instead of native debugging?
Debug Investigator excels for complex, non-obvious bugs where native debuggers alone fall short: intermittent failures, performance regressions, race conditions, and issues with no clear stacktrace. Use it when you need structured methodology to generate and rank hypotheses, design bisection strategies, or instrument code systematically. For straightforward bugs with obvious stacktraces, native debugging may be faster; for everything else, Debug Investigator's systematic approach saves time.
SKILL.md
rendered from the published skill — quoted content, verbatim
Debug Investigator
Structured debugging methodology that replaces ad-hoc exploration with hypothesis-driven investigation. Captures symptoms, builds a deterministic feedback loop, analyzes evidence (stacktraces, logs, state), generates ranked hypotheses, designs bisection strategies, identifies instrumentation points, and produces minimal reproductions — documenting every step so dead ends are never revisited.
> When to use this skill vs native debugging: The base model handles straightforward > debugging (clear stacktraces, obvious errors) natively. Use this skill for non-obvious bugs > requiring systematic investigation: intermittent failures, bugs with no clear stacktrace, >
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 7 files
skills/debug-investigator/SKILL.md
skills/debug-investigator/evals/cases.yaml
skills/debug-investigator/references/bisection-guide.md
skills/debug-investigator/references/hypothesis-templates.md
skills/debug-investigator/references/instrumentation-points.md
skills/debug-investigator/references/log-analysis.md
skills/debug-investigator/references/stacktrace-patterns.md