debug_skill

Overview

This skill provides a structured, hypothesis-driven debugging workflow for reproducible bug investigation and efficient resolution. It guides you through assessment, targeted investigation, minimal fixes, and quality steps to prevent regressions. Use it when tests fail, unexpected errors occur, or behavior differs from expectations.

How this skill works

The skill inspects failures by reproducing the issue, tracing execution, and forming testable hypotheses about root causes. It supports adding logging, running commands, and iterating through small, verifiable fixes. After a fix, it verifies with regression tests and cleans up debug artifacts to keep the codebase healthy.

When to use it

• When tests are failing or flaky in CI or locally
• When an error or crash appears with unclear origin
• When behavior diverges from specification or expected output
• When intermittent or environment-specific failures occur
• When you need a repeatable, documented debugging process

Best practices

• Reproduce the bug consistently before changing code
• Form explicit hypotheses and design tests to confirm or reject each
• Make the smallest change that addresses the root cause
• Add a regression test that covers the failure path
• Remove debug logging and prints once verified
• If multiple fixes fail, return to assessment and re-evaluate assumptions

Example use cases

• Investigate a failing CI job that passes locally by comparing environment and dependencies
• Trace a crash to a null/None access and apply a minimal defensive fix with a unit test
• Isolate an intermittent race condition using simplified inputs and targeted logging
• Resolve wrong output by tracing variable values and applying a logic correction plus regression test
• Add a failing test to reproduce a production bug, implement fix, then verify and clean debug artifacts