Debugging

Systematic debugging frameworks for finding and fixing bugs - includes root cause analysis, defense-in-depth validation, and verification protocols

Category: development Source: mrgoonie/claudekit-skills

What Is Debugging? Debugging is a disciplined process for identifying, diagnosing, and resolving defects or unexpected behaviors in software systems. The Claude Code skill “Debugging” provides a systematic, framework-driven approach to debugging, emphasizing root cause analysis, defense-in-depth validation, and rigorous verification protocols. Unlike ad-hoc bug fixing, this methodology insists on structured investigation, ensuring that every fix is based on a deep understanding of the problem and that no change is considered complete without fresh, proven evidence of correctness. ## Why Use Debugging? Software bugs are inevitable in any development lifecycle, manifesting as test failures, runtime errors, or subtle behavioral inconsistencies. Quick fixes, especially those that target symptoms rather than causes, can introduce regressions or mask deeper issues. Using the Debugging skill offers several advantages: - Reliability: Systematic debugging reduces the risk of recurring bugs and ensures that fixes address the true source. - Maintainability: By documenting and verifying each step, future developers can understand the rationale behind changes. - Security: Defense-in-depth validation makes it harder for invalid data or unanticipated behavior to propagate. - Confidence: Verification protocols ensure that the code behaves correctly before any completion claims are made. This skill is essential whenever bugs are encountered, unexpected behaviors are observed, or when validating a fix before closing an issue. ## How to Get Started The Debugging skill is language-agnostic and can be applied to any software project. To incorporate it into your workflow: 1. Install or Reference the Skill: Access the skill from the ClaudeKit Skills repository. 2. Recognize a Trigger Event: Begin when you encounter a bug, test failure, or unexplained system behavior. 3. Apply the Four-Phase Framework: - Start with root cause investigation. - Analyze recurring patterns. - Form and test hypotheses. - Only then proceed to implement and verify fixes. 4. Utilize Sub-Skills: Refer to the structured sub-skills for deeper guidance, such as root cause tracing and multi-layer validation. 5. Document and Verify: Before claiming a fix, run verification commands and gather evidence to ensure the issue is resolved. ## Key Features The Debugging skill is composed of several interlocking methodologies, each targeting a critical aspect of the debugging lifecycle. ### Systematic Debugging This four-phase approach mandates: 1. Root Cause Investigation: Trace the failure to its true origin, resisting the urge to patch symptoms. 2. Pattern Analysis: Identify whether similar bugs exist or if the issue recurs under certain conditions. 3. Hypothesis Testing: Formulate testable hypotheses about the cause and test them with controlled experiments. 4. Implementation: Only after confirmation, craft the fix. Example: Suppose a web API intermittently returns a 500 error. Instead of immediately changing error handling, use logs and stack traces to find that a null pointer exception is thrown in the UserService. Pattern analysis reveals this only happens when certain optional fields are missing. Hypothesis testing by simulating incomplete payloads confirms the cause. The fix then ensures field validation at the source. python ## Example: Defensive field validation before business logic def create_user(payload): if 'email' not in payload or not payload['email']: raise ValueError("Email is required") # Business logic proceeds only if validation passes ### Root Cause Tracing Trace errors backward through the call stack or data flow. For example, when a calculation returns an unexpected result, follow the data from the output back to the initial input, inspecting each transformation. Example: javascript function calculateTotal(cart) { if (!Array.isArray(cart.items)) { throw new Error("Invalid items array"); } // Further processing... } Here, the bug is traced to cart.items not being an array in certain invocations, revealing the original data source as the true fix location. ### Defense-in-Depth Validation Implement validation at multiple layers: - Entry Point: Initial input validation (e.g., API request payloads) - Business Logic: Assertions within domain logic - Environment Guards: Check preconditions (e.g., database connectivity) - Debug Instrumentation: Add logging and metrics to observe runtime behavior Example: go func ProcessOrder(order Order) error { if !order.IsValid() { log.Error("Order failed validation at entry point") return errors.New("invalid order") } // Business logic checks if order.Amount <= 0 { log.Error("Invalid amount in business logic") return errors.New("amount must be positive") } // Environment guard if !db.IsConnected() { log.Error("DB not connected") return errors.New("service unavailable") } // Debug instrumentation log.Info("Order processed successfully") return nil } ### Verification Before Completion No fix is complete without demonstrable evidence that the issue is resolved. Always rerun tests or verification scripts, and capture outputs as proof. Example: bash ## Run unit tests before closing the bug ticket pytest tests/test_user_service.py Attach the output to the issue tracker as verification. ## Best Practices - Never fix without root cause analysis. Resist quick patches—always investigate the original trigger. - Validate at every layer. Defense-in-depth makes entire classes of bugs impossible. -