systematic-debugging

Enforces evidence-based debugging protocol to confirm root causes before code changes.

3|Updated Jan 20, 2026

Search Tags:#tdd #debugging #troubleshooting #root cause analysis #bug fixing #software quality

Ready to run

npx skills add https://github.com/alunadev/ald-skills --skill systematic-debugging-alunadev

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/alunadev/ald-skills/tree/main/workflows/systematic-debugging
Command: npx skills add https://github.com/alunadev/ald-skills --skill systematic-debugging-alunadev

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill enforces a rigorous, evidence-based protocol to identify and fix bugs, preventing the common anti-patterns of guessing, treating symptoms, or refactoring prematurely.

Core Features & Use Cases

Root Cause Investigation: Guides users through gathering logs, reproducing issues, and pinpointing the exact cause.
Pattern Analysis: Helps identify similar working code and analyze differences.
Test-Driven Fixes: Ensures fixes are validated by failing tests before implementation and passing tests afterward.
Circuit Breaker: Prevents endless cycles of failed fixes by enforcing a limit on attempts.
Use Case: When a critical API endpoint suddenly starts returning 500 errors, this Skill will guide the engineer through analyzing logs, reproducing the error, formulating a hypothesis, and writing a test before any code is changed.

Quick Start

Use the /debug command with a brief description of the bug you are experiencing.

Frequently Asked Questions about systematic-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I find the root cause of a bug instead of just treating symptoms?▼

To find a root cause, you must gather evidence through log analysis and issue reproduction. This approach enforces a disciplined protocol to confirm the exact cause through hypothesis testing before implementing any fixes, preventing premature symptom treatment.

What is the best way to fix bugs using test-driven development?▼

The best way to fix bugs using test-driven development is to write a failing test that reproduces the issue before changing code. This validates the fix by ensuring the test passes afterward, maintaining software quality and preventing conflated changes.

How do I stop endless cycles of failed bug fixing attempts?▼

To stop endless cycles of failed bug fixing attempts, you need a circuit breaker mechanism. This enforces a strict limit on failed tries, preventing endless debugging loops and forcing you to step back and analyze patterns or similar working code.

How do I systematically debug a critical API endpoint returning 500 errors?▼

To systematically debug an API endpoint returning 500 errors, analyze logs and reproduce the error first. Then formulate a hypothesis, identify similar working code for pattern analysis, and write a test before implementing any code changes.

Why does debugging by guessing often introduce new issues?▼

Debugging by guessing often introduces new issues because it leads to premature fixes and conflated code changes. An evidence-based protocol requires confirming the root cause through investigation first, ensuring fixes target the actual problem.

Can I use this debugging protocol for troubleshooting complex software issues?▼

Yes, you can use this debugging protocol for troubleshooting complex software issues. It guides users through root cause investigation, pattern analysis, and test-driven fixes, ensuring disciplined, evidence-based resolution for critical problems.