debug

# Debug

## Overview

This skill applies a systematic debugging methodology inspired by medical differential diagnosis. It provides a rigorous 7-step process for investigating and resolving bugs through observation, classification, hypothesis testing, and verification. This approach prioritizes evidence-based reasoning over assumptions, ensuring root causes are identified rather than symptoms treated.

## When to Use This Skill

Activate this skill in two primary scenarios:

**Scenario A: Post-Modification Anomalies**
When modifying a previously tested and working version, and any unexpected behavior emerges after the changes.

**Scenario B: User-Reported Issues**
When users report that test results don't meet expectations or the system fails to execute as intended.

## Debugging Workflow

Follow this 7-step systematic approach to diagnose and resolve issues.

For a detailed checklist of each step, refer to `{baseDir}/references/debugging_checklist.md`. For common bug patterns and their signatures, see `{baseDir}/references/common_patterns.md`.

### Step 1: Observe Without Preconception (Observe)

**Objective:** Collect all available evidence without jumping to conclusions.

**Process:**
- Gather all accessible clues: user reports, system logs, dashboards, error stack traces, version changes (git diff), configuration parameters (configs/args/env)
- Focus exclusively on facts and observable phenomena
- Avoid premature hypotheses or assumptions about causes
- Document all observations systematically

**Key Principle:** Observe, don't just see. At this stage, the goal is comprehensive data collection, not interpretation.

### Step 2: Classify and Isolate Facts (Classify & Isolate Facts)

**Objective:** Distinguish symptoms from root causes and narrow the problem scope.

**Process:**

**For Incremental Development (Scenario A - Post-Modification Anomalies):**
- Confirm the previous step still works (ensure issue is from new changes)
- List ALL changes since last working