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
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-localWhat 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-localThis installs the whole citadel plugin with all its skills
2Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill systematic-debugging -a claude-code3Manually: put the files in place
~/.claude/skills/systematic-debugging/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/systematic-debugging/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill systematic-debugging -a codex2Manually: put the files in place
.agents/skills/systematic-debugging/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill systematic-debugging -a cursor2Manually: put the files in place
.cursor/skills/systematic-debugging/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install SethGammon/Citadel skills/systematic-debugging2Manually: put the files in place
.github/skills/systematic-debugging/SKILL.md1Skills CLI (Vercel)
npx skills add SethGammon/Citadel --skill systematic-debugging -a gemini-cli2Platform CLI
gemini skills install https://github.com/SethGammon/Citadel --path skills/systematic-debuggingManually: put the files in place
.devin/skills/systematic-debugging/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.