# Systematic Debugging

Four-phase root cause investigation for bugs and unexpected behavior

- Repository: https://github.com/taracodlabs/aiden (868 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-19
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add taracodlabs/aiden --skill systematic-debugging -g -a claude-code -y`
Codex: `npx skills add taracodlabs/aiden --skill systematic-debugging -g -a codex -y`
Cursor: `npx skills add taracodlabs/aiden --skill systematic-debugging -g -a cursor -y`
Gemini CLI: `npx skills add taracodlabs/aiden --skill systematic-debugging -g -a gemini-cli -y`

## Description

Four-phase root cause investigation for bugs and unexpected behavior

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Systematic Debugging

A structured four-phase process for diagnosing software bugs: **Reproduce → Isolate → Hypothesize → Verify**. Prevents guessing and ensures you find the root cause, not just a workaround.

## When to Use

- User reports a bug or unexpected behavior without an obvious cause
- An error message appears but the source is unclear
- A fix was applied but the problem persists
- Tests are failing intermittently (flaky tests)
- Production behavior differs from local behavior

## How to Use

### Phase 1: Reproduce reliably

A bug you can reproduce consistently is halfway solved.

```
1. Get the exact error message, stack trace, and environment
2. Identify exact steps to trigger the bug
3. Confirm the bug happens in a clean environment (not just local state)
4. Record: OS, runtime version, dependencies, config values
5. Try: does it fail on every run, or only sometimes?
```

If intermittent: add timing, logging, or retry logic to isolate the trigger.

### Phase 2: Isolate the failure

Narrow the failure to the smallest possible unit.

```
1. Add logging before/after suspected areas to find where state diverges
2. Binary search through code: comment out half, does it still fail?
3. Check: when did this last work? (git log, git bisect)
4. Check: what changed recently? (git diff main, dependency updates)
5. Reproduce in a minimal test case, strip away all unrelated code
```

```powershell
# git bisect to find the breaking commit
git bisect start
git bisect bad                  # current commit is broken
git bisect good v2.0.0          # last known good tag
# git will checkout commits, test each, then:
git bisect good   # or
git bisect bad
# Repeat until git identifies the culprit commit
git bisect reset
```

### Phase 3: Generate hypotheses

Form 2-3 specific, testable hypotheses about the root cause.

The rest: https://github.com/taracodlabs/aiden/blob/HEAD/skills/systematic-debugging/SKILL.md