debugging-patterns

Debugging Patterns

Domain skill for structured investigation of bugs and unexpected behavior.

Iron Law

ALWAYS FIND ROOT CAUSE BEFORE ATTEMPTING FIXES. Symptom fixes are failure.

A fix that doesn't address root cause creates a new bug later. Every. Single. Time.

Four-Phase Investigation

1. Gather Evidence

Collect before theorizing:

# Error logs, stack traces, recent changes
git log --oneline -10
git diff HEAD~3..HEAD --stat

• Read error messages and stack traces FULLY — don't skim
• Check logs in chronological order around the failure
• Note what changed recently (git log, git diff)
• Reproduce the error — if you can't reproduce it, you can't verify the fix

2. Pattern Analysis

Look for patterns in the evidence:

• When does it fail vs succeed? (inputs, timing, environment)
• What's different between working and broken states?
• Is the error consistent or intermittent?
• Use Grep to find similar patterns: error messages, function calls, data flows

3. Hypothesis Testing

Form and test hypotheses systematically. Use TaskCreate for each hypothesis:

TaskCreate("Hypothesis 1: {theory}", "Confidence: High\nTest: {specific test}\nEvidence: {what points here}")
TaskCreate("Hypothesis 2: {theory}", "Confidence: Medium\nTest: {specific test}\nEvidence: {what points here}")
TaskCreate("Hypothesis 3: {theory}", "Confidence: Low\nTest: {specific test}\nEvidence: {what points here}")

#	Hypothesis	Confidence	Test	Result
1	{theory}	High/Med/Low	{specific test}	{outcome}
2	{theory}	High/Med/Low	{specific test}	{outcome}
3	{theory}	High/Med/Low	{specific test}	{outcome}

For each hypothesis: TaskUpdate(status: "in_progress") before testing, TaskUpdate(status: "completed") after — whether confirmed or disproven. Record the result.

Rules:

• Maximum 3 hypotheses at a time (more means insufficient evidence — go back to phase 1)
• Test highest confidence first
• Test ONE at a time — never change two things simultaneously
• A disproven hypothesis is progress, not failure