К основному содержанию
скилл CX Codex

systematic-debugging · sethgammon — скилл для Claude Code

Скилл systematic-debugging ограничивает хаотичные правки: заставляет модель сначала воспроизвести баг, проверить гипотезы без изменения кода и остановиться после двух неудачных правок.

MIT ★ 937 обновлён 2026-10-29

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Открыть на GitHub

Что делает systematic-debugging

Скилл переводит отладку на строгий четырёхэтапный протокол: наблюдение, проверка гипотез, поиск первопричины и только потом исправление. Первые три фазы работают в режиме чтения. Модель не имеет права трогать логику приложения, пока не локализует сбой и не подтвердит гипотезу диагностическим чтением или точечным логом.

Действует правило экстренной остановки: если предложенное исправление сорвалось дважды подряд, агент обязан прекратить попытки и запросить контекст или вернуться к гипотезам. Это исключает каскадные поломки и слепой перебор вариантов. По регламенту скилла, если причина сбоя уже очевидна по трассировке стека, автор рекомендует использовать команду /do вместо запуска полного расследования.

Какие задачи решает

  • найти скрытую первопричину бага вместо маскировки симптомов
  • остановить хаотичные правки кода при повторных неудачных попытках
  • сформировать воспроизводимый тест перед внесением изменений
  • проверить код на похожие ошибки в соседних модулях

Примеры запросов агенту

  • Вызови /systematic-debugging: пользователи жалуются, что корзина сбрасывается при переходе к оплате
  • Найди первопричину ошибки: процесс падает с ошибкой типа при пустом ответе API
  • Продиагностируй intermittent-сбой в расчёте скидок по четырём фазам анализа

Как установить systematic-debugging

1Через маркетплейс плагинов

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

Команда ставит плагин citadel целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

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

3Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/systematic-debugging/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о systematic-debugging

Как установить systematic-debugging в Claude Code?

Выполните в консоли /plugin marketplace add SethGammon/Citadel, а затем /plugin install citadel@citadel-local. Также можно подключить скилл командой npx skills add SethGammon/Citadel --skill systematic-debugging -a claude-code.

Что делает systematic-debugging?

Задаёт строгий регламент поиска дефектов: запрещает править код до верификации гипотез и заставляет локализовать первопричину перед подготовкой патча.

Что произойдёт, если исправление не сработает?

Срабатывает аварийный стоп: после двух неудачных правок подряд модель прекращает попытки и возвращается к анализу гипотез либо просит контекст у разработчика.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Тесты и QA» →

Сначала — systematic-debugging от других авторов.

systematic-debugging Jesse Vincent Скилл systematic-debugging для Claude Code и Codex блокирует фиксы до завершения анализа первопричины. Включается при падении тестов, баге или неожиданном поведении. CX Codex +1 306 118установок systematic-debugging spencerpauly Скилл systematic-debugging для Claude Code и других агентов: заставляет искать причину бага по шагам вместо случайных правок. Держит под контролем баги, которые проявляются только в продакшене. CX Codex +1 604установок systematic-debugging bobmatnyc Скилл systematic-debugging для Claude Code ведёт агента от воспроизведения ошибки до проверки исправления. Выявляет причину сбоя или неожиданного поведения. CX Codex +1 400установок systematic-debugging ChrisWiles Скилл systematic-debugging задаёт четырёхэтапный протокол отладки с упором на первопричину бага. Скилл пригодится при расследовании падений тестов или внезапных сбоев рантайма без поверхностных правок. CX Codex +1 ★ 6 091звёзд репо systematic-debugging GanyuanRan Скилл systematic-debugging помогает разбирать ошибки, сбои тестов и неожиданное поведение до правок. Он прослеживает причину до места, которое действительно нужно исправить. CX Codex +1 ★ 1 450звёзд репо debugging sentimony Скилл debugging для Claude Code задаёт протокол расследования багов и сбоев тестов: агент проверяет факты и воспроизводит ошибку до правок кода. CX Codex +1 2 800установок debugging-toolkit-debugger Seth Hobson Субагент debugging-toolkit-debugger разбирает ошибки, падения тестов и неожиданное поведение: ищет первопричину, предлагает небольшой фикс и проверяет результат. CX Codex ★ 42 780звёзд репо debugging-strategies Seth Hobson Скилл debugging-strategies для Claude Code пошагово ищет причины ошибок, сбоев и проблем с производительностью. Разбирает случаи, когда поведение проекта отличается от ожидаемого. CX Codex +1 13 414установок debug-systematic travisjneuman Скилл debug-systematic для Claude Code ведёт агента через четыре фазы отладки: воспроизведение, локализацию, поиск причины и проверку исправления. Разбирает сложные и плавающие ошибки. CX Codex +1 152установок principle-attack-the-premise backnotprop Скилл principle-attack-the-premise для Claude Code разбирает общую предпосылку после провала двух исправлений на одном этапе проверки. Он предлагает проверить её до следующей попытки. CX Codex +1 10 100установок root-cause-tracing NeoLabHQ Скилл root-cause-tracing учит агента идти по стеку вызовов назад, пока не найдётся исходный триггер ошибки, и править там, а не на месте падения. CX Codex +1 1 400установок

Из того же набора55

Весь набор →
grill Скилл grill превращает размытый план в чёткое техническое задание через интервью: по одному вопросу, каждый с готовым ответом на выбор. CX Codex +1 ★ 937звёзд репо autopilot Скилл autopilot автоматизирует очередь задач из папки .planning/intake/: составляет бриф, вносит правки в код и проверяет результат. CX Codex +1 ★ 937звёзд репо doc-gen Скилл doc-gen создаёт комментарии к функциям, README для каталогов и справку по API, подстраиваясь под стиль проекта. Полезен, когда документацию нужно сверить с кодом, а не пересказать сигнатуры. CX Codex +1 ★ 937звёзд репо policy-enforcer Субагент policy-enforcer для Claude Code сверяет планируемое действие с правилами Citadel и возвращает вердикт: разрешить или заблокировать. Archon и Fleet запускают его перед операциями с низкой обратимостью. CX Codex ★ 937звёзд репо decision-map Скилл decision-map превращает расплывчатую идею в карту вопросов, которую можно продолжать между сессиями. Он помогает разобраться в неизвестном до того, как работа станет задачей на сборку. CX Codex +1 ★ 937звёзд репо archon Субагент archon, который ведёт большую задачу по фазам: разбивает направление на шаги, передаёт их другим агентам и хранит состояние кампании между запусками. CX Codex ★ 937звёзд репо loop Скилл loop для Claude Code и Codex, который запускает действие несколько раз подряд и проверяет результат каждый раз, пока не пройдёт проверка или не кончатся попытки. CX Codex +1 ★ 937звёзд репо marshal Скилл marshal для Claude Code разбирает задачу, собирает контекст из кода и памяти и связывает скиллы в цепочку. Работает за одну сессию и спрашивает, только если не может продолжить. CX Codex +1 ★ 937звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой