# Systematic Debugger

> Systematic Debugger

- Skill: `bestdeejay-design/systematic-debugger` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bestdeejay-design/systematic-debugger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bestdeejay-design/systematic-debugger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bestdeejay-design (https://skillmd.com/u/bestdeejay-design)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bestdeejay-design/systematic-debugger

---


# Systematic Debugger

> Отладка по методу «Железного закона»: не трогаем код, пока причина не подтверждена
> гипотезами и данными. 4 фазы, Red Flags, Rationalization Table, регресс-тест.

Загружай этот скилл когда есть **баг/неожиданное поведение** и нужно найти
корневую причину (root cause), а не наколеночный фикс. Скилл ведёт процесс:
воспроизведение, гипотезы, изоляция, минимальный фикс + тест-регрессия.

## 🎯 When to use

Use this skill when:
- «Почему это не работает?», «что-то сломалось», «неожиданный результат»
- Нужен структурированный поиск причины, а не «попробуй вот так»
- Баг воспроизводится, но причина неочевидна; нужно зафиксировать факты
- Нужен отчёт для передачи коллеге/агента: среда, шаги, гипотезы, регресс-план

Do NOT use when:
- Правка тривиальна и причина очевидна — просто сделай минимальный фикс
- Нужно просто «посмотреть как работает X» — это explore, не отладка
- Произошёл сбой из-за инфраструктуры (нет кода) — сначала собери факты окружения

## 📦 Files

- `SKILL.md` — этот файл
- `scripts/debug_log.py` — формирование отчёта по фазам (Python 3 stdlib)

## ⚙️ Iron Law (Железный закон)

> Никаких изменений кода, пока причина не подтверждена минимум одной
> воспроизводимой гипотезой. Один фикс за раз — после каждого изменения
> перепроверяй по фактам.

## 🔧 Workflow (4 фазы)

### Фаза 1 — Воспроизведение
1. Зафиксируй точные шаги, при которых баг проявляется.
2. Зафиксируй «факт»: что происходит на самом деле (вывод, лог, скрин).
3. Попробуй минимизировать: убрать переменные, пока баг воспроизводится.

### Фаза 2 — Гипотезы
1. Выдвини 1..3 гипотезы о причине (не больше).
2. Для каждой — как её проверить (команда/тест/лог) и какой результат ожидаем.
3. Заполни Rationalization Table: гипотеза → проверка → результат → вердикт.

### Фаза 3 — Изоляция причины
1. Проверяй гипотезы по одной; после каждой проверки обновляй таблицу.
2. Используй минимальные вмешательства: точечный лог, изолированный репродюсер.
3. Red Flag: если «внезапно заработало» без понимания почему — это НЕ фикс.

### Фаза 4 — Фикс + регрессия
1. Внеси минимальное изменение, устраняющее подтверждённую причину.
2. Напиши/обнови тест, который ловил бы баг (регрессия).
3. Прогони связанные тесты: старый баг не вернулся, фикс работает.

## 🛡 Red Flags (стоп-сигналы)
- **Quick-fix**: «наверное, тут просто надо...» без подтверждения причины.
- **Шотган-дебаг**: меняем несколько мест одновременно «авось пройдёт».
- **Спекуляция**: «может, из-за кэша» без проверки фактами.
- **Магическое исчезновение**: баг пропал, но никто не знает почему.
- **Зацикленность**: три одинаковые попытки без новых данных — остановись, пересобери факты.

## 🧰 Скрипт отчёта

```bash
python3 skills/systematic-debugger/scripts/debug_log.py \
    --label "auth_flow" \
    --command "pytest tests/test_auth.py -k login" \
    --expected "login succeeds" \
    --actual "401 Unauthorized"
```

Секции отчёта: Среда / Команда / Ожидаем / Факт / Гипотезы (1..3) / Регресс-план.
Отчёт удобно прикладывать к issue или передавать другому агенту для фазы 2.

## ✅ Definition of Done
- Причина подтверждена: минимум одна гипотеза прошла проверку (записано «подтверждено»).
- Внесён один минимальный фикс; регресс-тест добавлен/обновлён.
- Полный набор связанных тестов зелёный.
- Red Flags не наблюдались (быстрый фикс, шотган, спекуляция).