systematic-debugging

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

3|Updated Jan 20, 2026
One-click install
npx skills add https://github.com/alunadev/ald-skills --skill systematic-debugging-alunadev
Or copy as Structured Prompt for Agent
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.