| name | systematic-debugger |
| description | "Систематическая отладка по Iron Law: 4 фазы (воспроизведение → гипотезы → изоляция причины → фикс + регресс-тест), Red Flags (quick-fix, спекуляции, шотган-дебаг), Rationalization Table для отсева гипотез. Скрипт debug_log.py оформляет отчёт по фазам (среда, команда, ожидание, факт, гипотезы 1..3, регресс-план). Скилл не автофиксит: фиксирует причину, предлагает минимальный фикс и тест-регрессию. Триггеры: 'debug', 'отладить', 'почему не работает', 'баг', 'исправить ошибку', 'разобраться почему', 'дебаг', 'debugging', 'fix the bug', 'ошибка в коде', 'не работает как ожидалось'.", |
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 — Воспроизведение
- Зафиксируй точные шаги, при которых баг проявляется.
- Зафиксируй «факт»: что происходит на самом деле (вывод, лог, скрин).
- Попробуй минимизировать: убрать переменные, пока баг воспроизводится.
Фаза 2 — Гипотезы
- Выдвини 1..3 гипотезы о причине (не больше).
- Для каждой — как её проверить (команда/тест/лог) и какой результат ожидаем.
- Заполни Rationalization Table: гипотеза → проверка → результат → вердикт.
Фаза 3 — Изоляция причины
- Проверяй гипотезы по одной; после каждой проверки обновляй таблицу.
- Используй минимальные вмешательства: точечный лог, изолированный репродюсер.
- Red Flag: если «внезапно заработало» без понимания почему — это НЕ фикс.
Фаза 4 — Фикс + регрессия
- Внеси минимальное изменение, устраняющее подтверждённую причину.
- Напиши/обнови тест, который ловил бы баг (регрессия).
- Прогони связанные тесты: старый баг не вернулся, фикс работает.
🛡 Red Flags (стоп-сигналы)
- Quick-fix: «наверное, тут просто надо...» без подтверждения причины.
- Шотган-дебаг: меняем несколько мест одновременно «авось пройдёт».
- Спекуляция: «может, из-за кэша» без проверки фактами.
- Магическое исчезновение: баг пропал, но никто не знает почему.
- Зацикленность: три одинаковые попытки без новых данных — остановись, пересобери факты.
🧰 Скрипт отчёта
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 не наблюдались (быстрый фикс, шотган, спекуляция).
