Smart Debug

What it does

The Smart Debug skill assists AI agents in automatically identifying and suggesting fixes for common coding errors during testing cycles. It leverages a hypothesis-first debugging methodology called "Cursor Debug Mode," prioritizing structured analysis and instrumentation before attempting any code changes. The agent analyzes error messages, reproduction steps, affected components, performance characteristics, and environment details to pinpoint the root cause of issues.

When to use it

• When dealing with intermittent or hard-to-reproduce bugs.
• For debugging production or runtime issues using observability data.
• In situations involving complex failures across multiple software components that require structured instrumentation.
• When you need a ranked list of potential causes before attempting any fixes.

Key capabilities

• Error Pattern Recognition: Identifies recurring error patterns in logs and stack traces.
• Component Dependency Analysis: Determines the relationships between different parts of a system to understand how failures propagate.
• Severity Assessment: Estimates the impact of an issue on users or services.
• Hypothesis Ranking: Generates and ranks potential root causes based on available data.
• Human-in-the-Loop (HITL) Support: Can pause execution to request human intervention for bug reproduction if automated reproduction fails (SMART_DEBUG_HITL configuration).

Example prompts

• "Analyze this error message and suggest possible causes: [paste error message here]"
• "I'm seeing intermittent failures in the payment processing service. Can you help me debug it?"
• "Here are the reproduction steps for a bug I’m encountering: [list steps]. What could be causing this?"

Tips & gotchas

• This skill operates within an agent context and does not function as a standalone utility script.
• The "Iron Law" of Smart Debug dictates that instrumentation should only occur after hypotheses are ranked, fixes are avoided before root cause confirmation, and cleanup is performed at the end.
• For straightforward, locally reproducible bugs or when the root cause area is already known, consider using a standard debugging approach instead.