Debugging

What it does

This skill, "Debugging," guides an AI agent through a systematic process for identifying and suggesting fixes for code errors. It emphasizes finding the root cause of issues before proposing solutions to avoid creating new bugs or masking underlying problems. The debugging process is structured around distinct phases focused on investigation and verification rather than quick fixes. This skill is designed to be used within an agent context, not as a standalone utility.

When to use it

This skill is valuable in the following situations:

• When encountering test failures, bugs in production, unexpected behavior, performance problems, build failures, or integration issues.
• Under time pressure when quick fixes are tempting but potentially risky.
• After previous fix attempts have failed.
• When you lack a full understanding of the issue at hand.
• For seemingly simple bugs – even these can have complex root causes.

Key capabilities

• Root Cause Investigation: Prioritizes identifying the underlying cause of errors before suggesting fixes.
• Reproducibility Focus: Requires reliable reproduction of the bug as a prerequisite for debugging.
• Single Change Hypothesis Testing: Mandates making only one change at a time when testing potential solutions.
• Architectural Review Trigger: Prompts questioning the architecture after three failed fix attempts.
• Test Case Creation: Requires creating a failing test case before implementing any fix to ensure verification and prevent regressions.

Example prompts

Here are some example prompts you could give an AI agent with this skill installed:

• "I'm seeing intermittent failures in our integration tests. Can you help me debug it using your systematic approach?"
• "We have a build failure – can you guide me through the debugging process, starting with root cause investigation?"
• “A production bug is causing unexpected behavior. Walk me through how to systematically identify and fix the underlying issue.”

Tips & gotchas

• Phase-Based Approach: The skill enforces a strict phase-based approach; you must complete each phase before moving on. Skipping phases can lead to incorrect fixes or new bugs.
• Not for Simple Bugs (Sometimes): While useful for complex issues, it might be overkill for very simple, locally reproducible bugs. Consider the "smart-debug" skill for more advanced scenarios involving hypothesis ranking and instrumentation.