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
Decision gist · record as of 2026-07-21
Debug Investigator helps you systematically investigate bugs through hypothesis-driven methodology, evidence analysis, and bisection strategies. 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.
Use it when
- Debug Investigator helps you rank competing hypotheses by likelihood and testability.
- Debug Investigator incorporates git bisect as a core debugging strategy to narrow down exactly which commit introduced a bug.
Verify before relying
Read SKILL.md below before installing (7 files). Open directory: indexed for reading, not audited.
Install
Mathews-Tom/armory/debug-investigator · repository language: Python
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
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
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Systematically investigate a bug using hypothesis-driven methodology”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
A disciplined, evidence-based debugging framework that walks you through reproducing issues reliably, narrowing scope to the failing component, understanding root causes through the scientific method, and implementing minimal fixes with regression tests. Eliminates guesswork and ensures you address the actual problem, not just symptoms.
This skill enforces a disciplined debugging process: establish a tight feedback loop that reproduces the exact symptom, gather evidence across system boundaries, trace data flow to its source, and form testable hypotheses before proposing any fix. By completing each phase sequentially—root cause investigation, pattern analysis, hypothesis testing, and verification—you eliminate guesswork and prevent quick patches from masking deeper issues.
Investigate walks you through a structured methodology to pinpoint what's causing bugs, test failures, build errors, and unexpected behavior. It cycles through characterization, isolation, hypothesis generation, and targeted testing—with escalation to deeper analysis when needed—to diagnose the root cause without applying fixes.
Investigate walks you through structured bug diagnosis, starting with hypothesis generation and moving through code inspection, data flow tracing, and controlled experiments to isolate the root cause. It focuses on finding and explaining problems rather than fixing them, and escalates to diagnostic logging only when code inspection alone cannot pinpoint the issue.
This skill enforces a disciplined debugging workflow: gather symptoms and code context, test hypotheses against known patterns, verify your theory before writing any fix, and document findings in a structured report. It prioritizes root cause discovery over quick patches, flagging when investigation stalls so you know when to escalate rather than guess.
Parallel Debugging applies the Analysis of Competing Hypotheses methodology to organize multi-agent investigation of complex issues. It structures hypothesis generation across six failure mode categories, establishes evidence collection standards with citation requirements, and provides arbitration protocols to identify root causes while avoiding confirmation bias.
More skills Causal Inference Root Cause (unlicensed) · bug-hunt-swarm (MIT) · H Abduct (NOASSERTION) · debug (Apache-2.0) · Debugging (unlicensed) · Systematic Debugging (unlicensed) · systematic-debugging (MIT)