bug-investigation

Verifies bug root causes through reproduction before implementing fixes.

Updated Mar 10, 2026
One-click install
npx skills add https://github.com/jasoncrawford/brunel --skill bug-investigation-jasoncrawford
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: bug-investigation
Source: https://github.com/jasoncrawford/brunel/tree/main/.claude-plugin/skills/bug-investigation
Command: npx skills add https://github.com/jasoncrawford/brunel --skill bug-investigation-jasoncrawford

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers often jump straight to fixing code that merely "looks suspicious," shipping speculative changes that may not address the real cause and can introduce regressions. This Skill enforces a disciplined hypothesis → verify → fix workflow so every bug fix is grounded in observed evidence. ## Core Features & Use Cases - Reproduction-First Workflow: Requires writing a test, script, or REPL invocation that demonstrates the failure before any code change, turning the repro into a regression test. - Diagnostics When Reproduction Fails: Guides adding targeted logging and assertions tied to specific hypotheses when bugs depend on production data, timing, or environment conditions. - Anti-Pattern Guardrails: Explicitly rejects speculative fixes, unverified root-cause claims, and hedged changes that address multiple possible causes at once. - Use Case: An agent assigned to a GitHub issue reporting intermittent crashes uses this Skill to first reproduce the crash locally, confirm the failing code path, and only then implement and verify the fix. ## Quick Start Investigate this reported bug by first reproducing the failure with a test before making any code changes.

Frequently Asked Questions about bug-investigation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I verify a bug's root cause before fixing it?▼

Write a test, script, or REPL invocation that exercises the suspected code path and watch it fail in the way the bug describes. That observed failure is your proof of cause, and the repro doubles as a regression test after the fix.

What should I do when I cannot reproduce a bug locally?▼

Do not guess at a fix. Add targeted logging, assertions, or error messages at the specific points your hypotheses implicate, then report what evidence each diagnostic would produce so the next real occurrence confirms or refutes each hypothesis.

Why is fixing code that looks suspicious a bad practice?▼

A suspicious-looking code path is only a hypothesis, not a verified cause. Changing it without observing the failure has no confirmed effect and risks introducing regressions while leaving the actual bug unresolved.

When should I add logging instead of a code fix?▼

Add diagnostics when a bug genuinely cannot be reproduced due to production data, timing, or environment constraints. Each log or assertion should target one specific hypothesis, and you should state what output would confirm or refute it.

Can one change address multiple possible bug causes?▼

No. Hedging with a change that might address several possible causes is explicitly rejected because it masks which cause was real. Verify a single hypothesis first, then fix that confirmed cause.