skills.rest
HarmAalbers
HarmAalbersCOMMUNITY
Explore all skills by this author →
GitHub

systematic-debugging

Diagnose bugs through a four-phase root cause investigation process before proposing fixes.

1|Updated Dec 11, 2025
Search Tags:#debugging#troubleshooting#root cause analysis#stack trace#test failures#flaky tests#hypothesis testing
One-click install
npx skills add https://github.com/HarmAalbers/claude-requirements-framework --skill systematic-debugging-harmaalbers
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/HarmAalbers/claude-requirements-framework/tree/main/plugins/requirements-framework/skills/systematic-debugging
Command: npx skills add https://github.com/HarmAalbers/claude-requirements-framework --skill systematic-debugging-harmaalbers

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Developers often jump to quick fixes that mask symptoms instead of resolving root causes, leading to recurring bugs, wasted time, and new defects. This Skill enforces a disciplined debugging methodology that requires root cause investigation before any fix is attempted. ## Core Features & Use Cases - Four-Phase Debugging Process: Enforces Root Cause Investigation, Pattern Analysis, Hypothesis Testing, and Implementation in strict order, with an iron rule of no fixes before investigation. - Root Cause Tracing & Defense-in-Depth: Reference guides cover tracing bugs backward through the call stack, adding validation at multiple layers, and replacing arbitrary timeouts with condition-based waiting. - Escalation Guardrails: After three failed fix attempts, the process stops and questions the underlying architecture instead of attempting a fourth fix. - Use Case: When a test fails in CI or a production bug appears, use this Skill to reproduce the issue, gather evidence across component boundaries, form a single hypothesis, and verify the fix with a failing test case. ## Quick Start Use the systematic-debugging skill to investigate why my test suite fails intermittently before suggesting any code changes.

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema
How do I debug a test failure systematically instead of guessing?▼

Follow the four-phase process: first investigate the root cause by reading error messages and reproducing the issue, then analyze patterns against working code, form a single hypothesis and test it minimally, and finally implement one fix verified by a failing test case.

How to find the root cause of a bug deep in the call stack?▼

Trace backward through the call chain from the symptom to the original trigger, asking what called each function and what values were passed. Add stack trace instrumentation with traceback.format_stack() when manual tracing is not possible.

When should I stop trying fixes and question the architecture?▼

Stop after three failed fix attempts. If each fix reveals a new problem in a different place or requires massive refactoring, the pattern indicates an architectural problem that needs discussion before further fixes.

How do I fix flaky tests caused by timing issues?▼

Replace arbitrary sleep delays with condition-based waiting that polls for the actual condition you care about, such as an event, state change, or file existing. Only use fixed timeouts when testing actual timing behavior, and document why.

Why is one validation check not enough after fixing a bug?▼

A single validation point can be bypassed by different code paths, refactoring, or mocks. Defense-in-depth adds validation at every layer data passes through: entry points, business logic, environment guards, and debug instrumentation.

Related Skills

Explore More Software Engineering Skills→
deflosjdeflosj

gstack-openclaw-investigate

Trace code paths from symptoms to root-cause hypotheses with regression tests.

Official
Advanced
penpotpenpot
59.4k

testing

Enforces TDD workflow and testing conventions for Penpot feature and bug-fix development.

Official
Intermediate
yousufjoyianyousufjoyian

defense-in-depth

Enforce defense-in-depth data validation across API entry points, business logic, environment guards, and debug instrumentation.

Community
Advanced
i-bebsii-bebsi

python-debugpy

Debug Python code using pdb breakpoints and debugpy remote DAP attach.

Community
Advanced