# Systematic Debugging

4-phase root cause analysis: observe, hypothesize, verify, fix.

- Repository: https://github.com/SethGammon/Citadel (927 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

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

## Description

4-phase root cause analysis: observe, hypothesize, verify, fix. Enforces investigation before any code changes. Emergency stop after 2 failed fixes. Prevents shotgun debugging and fix cascades.

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

# /systematic-debugging, Root Cause Before Fix

## Orientation

**Use when:** root cause is unknown and premature fixes keep failing -- enforces observe -> hypothesize -> verify before touching code.
**Don't use when:** root cause is already known (use /marshal to implement the fix); the bug is shallow and the stack trace is enough (use /do).

## Protocol

### Phase 1: OBSERVATION & REPRODUCTION

1. Read the error message, stack trace, or bug description
2. Reproduce the issue:
   - If it's a type error: run typecheck and read the full error
   - If it's a runtime error: identify the triggering conditions
   - If it's a behavioral bug: document expected vs actual behavior
3. Isolate the failing component/function:
   - What file? What function? What line?
   - What are the inputs when it fails?
   - Does it fail consistently or intermittently?

**Output**: A clear problem statement:
"{Component} does {X} when it should do {Y}, triggered by {condition}"

### Phase 2: HYPOTHESIS & VERIFICATION

1. Formulate up to 3 hypotheses for WHY the bug exists:
   - H1: {most likely cause}, because {evidence}
   - H2: {second candidate}, because {evidence}
   - H3: {third candidate}, because {evidence}

2. For each hypothesis, define a verification step:
   - Add a console.log / diagnostic read / breakpoint
   - Check a specific value at a specific point
   - DO NOT change any logic yet, only observe

3. Run the verification:
   - Which hypothesis was confirmed?
   - Which were eliminated?
   - If none confirmed: formulate new hypotheses with the new information

**CRITICAL**: Do not skip this phase. Do not "just try" a fix. Verify first.

### Phase 3: ROOT CAUSE ANALYSIS

Once a hypothesis is confirmed:

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