Skip to main content
skill CX Codex

systematic-debugging · sethgammon — Claude Code skill: what it does, how to install

systematic-debugging stops trial-and-error edits by enforcing a four-phase root cause protocol and freezing code changes until hypotheses are tested.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What systematic-debugging does

The skill guides an assistant through four distinct phases: observe and reproduce, formulate hypotheses, find the root cause, and implement a minimal fix. Phases one through three are strictly read-only. The agent cannot modify business logic while testing assumptions; it may only inspect values or run diagnostics.

An emergency stop triggers if two consecutive fix attempts fail. The model must halt instead of taking a third blind guess, reverting to hypothesis evaluation or asking for context. When the bug is trivial and fully explained by an obvious stack trace, the author advises using /do rather than running this investigation pipeline.

What it helps with

  • isolate root causes before touching production code
  • prevent shotgun debugging loops and broken regressions
  • halt automated modifications after two failed patch attempts
  • write reproducing test cases before applying minimal fixes

Example prompts for the agent

  • Run /systematic-debugging on the checkout timeout bug
  • Investigate bug: the worker process exits without stack traces during batch imports
  • Diagnose why order recalculation fails under concurrent updates

How to install systematic-debugging

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill systematic-debugging -a claude-code

3Manually: put the files in place

~/.claude/skills/systematic-debugging/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/systematic-debugging/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about systematic-debugging

How to install systematic-debugging in Claude Code?

Run /plugin marketplace add SethGammon/Citadel, followed by /plugin install citadel@citadel-local. Alternatively, install it with npx skills add SethGammon/Citadel --skill systematic-debugging -a claude-code.

What does systematic-debugging do?

It enforces a disciplined diagnosis workflow that isolates the root cause in read-only mode before applying any code changes.

When does the emergency stop trigger?

If a proposed fix fails twice in a row, the skill forces the agent to stop editing files and return to hypothesis verification.

Source text

SKILL.md · MIT
---
name: systematic-debugging
license: MIT
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.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - debug
  - root cause
  - diagnose
  - why is
  - investigate bug
last-updated: 2026-06-24
---

# /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:

1. Explain WHY the bug happens, not just WHERE:
   - Trace the data flow backward from the symptom to the source
   - Identify the specific incorrect assumption or logic error
   - Document the causal chain:
     "A calls B with X, B assumes X > 0, but A passes -1 when {condition}"

2. Check for related occurrences:
   - Is this pattern used elsewhere? Could the same bug exist in similar code?
   - Is there a systemic issue (e.g., missing validation at a boundary)?

**Output**: Root cause statement:
"The bug occurs because {cause}. This happens when {trigger}."

### Phase 4: IMPLEMENTATION

1. Write a failing test case that reproduces the bug (if test framework exists)
2. Apply the minimal fix — change only what's necessary to resolve the root cause
3. Verify the fix:
   - Test case now passes
   - Typecheck passes
   - No regressions in related functionality
4. If the root cause analysis revealed related occurrences, fix those too

## Emergency Stop Rule

**If a fix fails TWICE: STOP.**

Do not try a third guess. The root cause analysis was wrong. Either:
- Go back to Phase 2 with new hypotheses
- Ask the user for more context about the system's intended behavior
- Check if there's a higher-level architectural issue

Three failed fixes in a row means you're guessing, not debugging.

## What This Skill Prevents

- **Shotgun debugging** — changing random things until the error goes away
- **Symptom fixing** — patching the output without understanding the cause
- **Fix cascades** — one bad fix creating three new bugs
- **Silent regressions** — fixing one path while breaking another

## Contextual Gates

**Disclosure:** "Debugging [symptom]. Phases 1-3 read-only; will confirm before applying fixes in Phase 4."
**Reversibility:** amber — Phase 4 applies targeted fixes to source files; undo with `git checkout` on modified files. Phases 1-3 are read-only.
**Trust gates:**
- Any: investigation (Phases 1-3).
- Familiar (5+ sessions): applying fixes (Phase 4).

## Quality Gates

- A clear problem statement exists before any hypothesis is formed
- At least one hypothesis was verified (not assumed) before the fix was written
- The fix addresses the root cause, not just the symptom
- Typecheck passes after the fix with no new errors
- If related occurrences were found, they were fixed or documented

## Fringe Cases

**Bug is intermittent**: Document the triggering conditions as precisely as possible. Reproduce it at least once before forming hypotheses. If it can't be reproduced, stop at Phase 1 and ask for more context.

**Two fix attempts have already failed**: Invoke the Emergency Stop Rule. Return to Phase 2 with new hypotheses. Do not try a third guess without re-reading the relevant code.

**No test framework exists**: Skip the "write a failing test" step in Phase 4. Verify the fix manually and document how to reproduce the original bug for future reference.

**Error is in a dependency or generated file**: Document the root cause but do not modify the dependency. Propose a workaround in the consuming code instead.

## Exit Protocol

```
---HANDOFF---
- Bug: {problem statement}
- Root cause: {one-line cause}
- Fix: {what was changed}
- Verified: {typecheck + tests passing}
- Related: {any similar patterns found and fixed}
---
```

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Testing and QA →

systematic-debugging by other authors comes first.

systematic-debugging Jesse Vincent systematic-debugging is a Claude Code and Codex skill that blocks fixes until root cause analysis is complete. It activates on test failures, bugs, or unexpected behavior. CX Codex +1 306,118installs systematic-debugging spencerpauly systematic-debugging enforces a structured debugging workflow on your AI assistant instead of random edits. It helps isolate elusive bugs and verify root causes with evidence. CX Codex +1 604installs systematic-debugging bobmatnyc The systematic-debugging skill guides an agent from reproducing a bug to checking the fix. Use it when an error or unexpected behavior has no clear cause. CX Codex +1 400installs systematic-debugging ChrisWiles systematic-debugging enforces a four-phase troubleshooting protocol rooted in root cause analysis. Ideal for tracking down broken test suites or runtime errors without trial-and-error edits. CX Codex +1 ★ 6,091repo stars systematic-debugging GanyuanRan The systematic-debugging skill guides bug and test-failure investigations before code changes. Use it to trace a symptom to the logic that owns the cause. CX Codex +1 ★ 1,450repo stars debugging sentimony debugging enforces root-cause discipline during bug investigations. Prevents the agent from modifying code until it proves why a failure happens. CX Codex +1 2,800installs debugging-toolkit-debugger Seth Hobson The debugging-toolkit-debugger subagent investigates errors, failed tests, and odd behavior by tracing failures to their cause and checking a focused fix. CX Codex ★ 42,780repo stars debugging-strategies Seth Hobson The debugging-strategies skill gives an agent a step-by-step way to investigate bugs, crashes, and performance problems. Use it when a project behaves unexpectedly. CX Codex +1 13,414installs debug-systematic travisjneuman debug-systematic — a four-phase debugging skill for hard-to-reproduce failures, race conditions, and unexplained behavior. It guides the agent from reproduction to verified fix. CX Codex +1 152installs principle-attack-the-premise backnotprop principle-attack-the-premise is a Claude Code skill that tests a shared premise after two or more fixes fail at the same gate. It checks the assumption before another fix is written. CX Codex +1 10,100installs root-cause-tracing NeoLabHQ root-cause-tracing — a skill that walks the agent backward through the call stack until it finds the original trigger, then fixes there instead of at the crash site. CX Codex +1 1,400installs

From the same set55

The whole set →
grill grill turns a vague plan into a sharp technical spec through one-question-at-a-time interview, each with a default answer you edit. CX Codex +1 ★ 937repo stars autopilot autopilot processes queued tickets from .planning/intake/ through automated research, implementation, and verification. CX Codex +1 ★ 937repo stars doc-gen doc-gen generates function comments, directory READMEs, and API references while following the project’s existing conventions. Use it when docs should explain code behavior rather than repeat signatures. CX Codex +1 ★ 937repo stars policy-enforcer policy-enforcer is a Claude Code subagent that checks proposed actions against Citadel’s rules and returns an allow-or-block verdict. Archon and Fleet spawn it before actions with low reversibility. CX Codex ★ 937repo stars decision-map Turn an unresolved idea into a Git-tracked decision map, then pick up the investigation in later sessions. Useful before work is ready to build. CX Codex +1 ★ 937repo stars archon archon — a subagent that carries a big task through phases: splits a direction into steps, hands them to other agents and keeps campaign state between runs. CX Codex ★ 937repo stars loop loop — a skill for Claude Code and Codex that runs an action repeatedly and checks the result each time, stopping when verification passes or attempts run out. Useful for fixing lint errors or test failures in an active session. CX Codex +1 ★ 937repo stars marshal The marshal skill for Claude Code parses a task, gathers context from code and project memory, and chains skills. It runs in one session and asks only if it cannot continue. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open