debug

Diagnose bugs by mapping architecture and testing hypotheses.

Updated Apr 15, 2026

Search Tags:#architecture #debugging #documentation #evidence #triage #hypothesis #root-cause

Ready to run

npx skills add https://github.com/AAbdulghany/fms --skill debug-aabdulghany

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: debug
Source: https://github.com/AAbdulghany/fms/tree/main/.claude/skills/debug
Command: npx skills add https://github.com/AAbdulghany/fms --skill debug-aabdulghany

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Hypothesis-driven debugging — architecture-first reading + evidence-before-fix. For bugs that resisted naïve fix attempts.

Core Features & Use Cases

Capture exact symptoms with structured steps to prevent guesswork.
Map all layers of the architecture to locate where the failure originates.
Build a hypothesis ladder (3–5 causes) with explicit evidence tests.
Gather evidence and verify fixes against the original symptom before shipping.
Produce concise debug reports for faster collaboration and knowledge transfer.

Quick Start

Begin by capturing the exact symptom, mapping the architecture, and drafting a hypothesis ladder to guide your investigation.

Frequently Asked Questions about debug

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

FAQPage Schema

What is evidence-based debugging and how does it help resolve stubborn software bugs?▼

Evidence-based debugging identifies exact symptoms, maps architecture layers, and builds a hypothesis ladder to test potential root causes, preventing guesswork and resolving bugs that resisted naive fix attempts.

How do I find the root cause of a bug across multiple application layers?▼

To find a root cause, map every layer from input to persistence, list potential causes ordered by confidence, and perform evidence-based tests against a hypothesis ladder of three to five testable causes.

How do I document software bugs to prevent guesswork during triage?▼

Document software bugs by capturing the exact symptom, including the URL, steps to reproduce, and observed versus expected results, which creates a structured baseline for evidence-based triage.

What is the best way to structure a debugging workflow for complex system failures?▼

The best way to structure debugging is to capture symptoms, map architecture, generate a hypothesis ladder, gather evidence, implement a minimal fix, and verify the original symptom remains resolved before shipping.

When should I use hypothesis-driven debugging instead of attempting a direct code fix?▼

Use hypothesis-driven debugging when naive fix attempts have failed, requiring architecture-first reading and evidence-before-fix methodologies to systematically isolate the root cause of the failure.