debugging-patterns_skill

Overview

This skill captures a disciplined, repeatable debugging pattern to find and fix root causes instead of patching symptoms. It enforces a four-phase workflow (investigate, analyze patterns, hypothesize and test, implement fixes) and mandates evidence and minimal changes. Use it to reduce thrash, prevent regressions, and speed reliable resolutions.

How this skill works

The skill guides developers through a mandatory Phase 1 root-cause investigation before any fix is proposed. It provides concise checklists: capture full errors and stack traces, reproduce reliably, gather cross-component evidence, and trace data flow to the original trigger. For development tasks it integrates with the cc10x-router workflow to record instrumentation steps and evidence artifacts, then enforces minimal-change hypothesis testing and single-change implementation with regression testing.

When to use it

• Any technical bug: test failures, runtime errors, or unexpected behavior
• Production incidents and time-pressured emergencies
• Intermittent or timing-dependent failures
• When multiple prior fixes have failed
• Before proposing or committing any code change that touches the failing area

Best practices

• Always complete Phase 1 (investigate) before proposing fixes
• Form one specific, falsifiable hypothesis and test it with the smallest change
• Add strategic diagnostic logging at component boundaries to gather evidence
• Create a minimal reproducible test or script before implementing the fix
• Apply one change at a time and run full test suite before proceeding

Example use cases

• A failing unit test: capture stack trace, inspect fixtures, trace unexpected value to source, add failing test, implement fix
• Intermittent race condition: add instrumentation, reproduce with deterministic waits, form hypothesis about ordering, apply synchronization minimal change
• Deployment config mismatch across services: log inputs/outputs per component, identify mispropagated value, correct config at source and add validation
• Regression after recent commits: use git bisect to find commit, compare with working example, implement targeted fix and a regression test