systematic-debugging

The systematic-debugging skill is designed to prevent the common engineering anti-pattern of applying ad-hoc patches to complex software issues. By enforcing a strict sequence of investigative phases, this skill ensures that agents identify the fundamental source of a bug rather than masking symptoms. It is intended for software developers and coding agents operating in high-stakes environments where reliability is paramount. The skill is triggered automatically whenever a test failure, production bug, unexpected runtime behavior, or performance regression is identified, mandating a 'root cause first' approach.

• Phase 1: Comprehensive investigation including stack trace analysis, consistent reproduction steps, delta analysis of recent git commits, and multi-component boundary instrumentation.

• Phase 2: Pattern analysis by comparing broken code against working references to identify minute environmental or logical discrepancies.

• Phase 3: The scientific method of hypothesis formulation, requiring developers to write down the reasoning before executing a single-variable test.

• Phase 4: Implementation of targeted fixes, with built-in guardrails for architectural assessment if more than three attempts fail to resolve the issue.

• Mandatory usage for any technical issue, including CI/CD failures, integration problems, and race conditions.

• Requires evidence-based debugging: agents must document findings at each boundary (e.g., API layers, database queries, build scripts) before proposing a change.

• Prevents 'thrashing' by requiring a pivot to architectural review if multiple attempted fixes do not achieve the desired state.

• Works seamlessly with test-driven-development and other Superpowers skills to ensure that every fix is verified by a failing test case that subsequently passes.

• Integrates with tracing techniques to locate the origin of corrupted data values, ensuring the fix happens at the source rather than the point of failure.