debug-like-expert_skill

Overview

This skill activates a deep-analysis debugging mode for complex issues that resist standard troubleshooting. It runs a context scan, loads domain-specific expertise when available, and applies a methodical, evidence-driven investigation protocol to find root causes. The approach emphasizes skepticism—especially toward code you wrote—and forces hypothesis testing and rigorous verification before any fix.

How this skill works

On invocation it inspects the repository to detect file types and project indicators, then reports findings before beginning. If a matching domain expertise exists under ~/.claude/skills/expertise/, it offers to load that context and uses domain-specific checks and known pitfalls. The skill then guides evidence gathering, hypothesis formation, targeted tests, and minimal verified fixes.

When to use it

• When quick fixes or ad-hoc debugging have failed to resolve a recurring or opaque bug
• When an issue affects multiple components and you need a systematic root-cause analysis
• Before making changes to critical production code that requires justification and proof
• When you suspect cognitive bias about how your own code behaves
• When you need reproducible, documented investigations for code review or postmortems

Best practices

• Run the context scan first and load available domain expertise before investigating
• Document exact errors, reproduction steps, and actual vs expected outputs before changing code
• Form multiple falsifiable hypotheses and design minimal tests to prove or disprove each
• Change one variable at a time and verify the effect with concrete evidence
• Avoid drive-by fixes: only implement a change if you can explain why it works and verify regressions

Example use cases

• A production crash with unclear stack traces that spans several services and libraries
• A flaky test suite where failures are intermittent and local debugging hasn’t reproduced the issue
• A performance regression that started after dependency upgrades and needs precise root cause
• A complex integration bug in a mixed-language repo where project type detection helps load targeted checks
• Verifying a proposed patch to ensure it fixes the bug without introducing side effects