Systematic Debugging

What it does

This skill, Systematic Debugging, provides a structured approach to identifying and resolving software bugs. It emphasizes finding the root cause of issues before attempting any fixes, preventing wasted time and avoiding the creation of new problems. The process is divided into four phases, ensuring comprehensive investigation and targeted solutions for technical issues like test failures, production bugs, or performance problems.

When to use it

This skill is valuable in a variety of situations:

• When dealing with test failures.
• Addressing bugs found in production environments.
• Investigating unexpected software behavior.
• Troubleshooting performance problems and build failures.
• Resolving integration issues between different components.
• Especially useful when under time pressure or when a "quick fix" seems tempting.

Key capabilities

• Root Cause Investigation: The core focus is identifying the underlying cause of an issue, not just addressing symptoms.
• Error Message Analysis: Requires careful reading and understanding of error messages, stack traces, line numbers, file paths, and error codes.
• Reproducibility Testing: Emphasizes reliably reproducing issues to understand their triggers.
• Change Tracking: Reviewing recent code changes (Git diffs, commits) and configuration updates.
• Diagnostic Instrumentation: For multi-component systems, it involves adding logging at component boundaries to trace data flow and identify failing components.
• Data Flow Tracing: Requires the use of a "superpower" skill: root-cause-tracing for backward tracing techniques when errors are deep in call stacks.

Example prompts

Here are some example prompts you might give an AI agent using this skill:

• “I’m seeing test failures; can you help me systematically debug them?”
• “We have a bug in production; walk me through the steps for root cause investigation.”
• "This build is failing. Use systematic debugging to find out why."

Tips & gotchas

• Phase Adherence: You must complete each of the four phases sequentially before proposing any fixes. Skipping phases can lead to incorrect solutions and wasted effort.
• Root Cause First: Avoid making changes until you've thoroughly investigated the root cause. Symptom-based fixes are considered failures by this methodology.
• Multi-Component Systems: For systems with multiple components, be prepared to add diagnostic instrumentation (logging) to trace data flow between them.