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: «наверное, тут просто надо...» без подтверждения причины.
• Шотган-дебаг: меняем несколько мест одновременно «авось пройдёт».
• Спекуляция: «может, из-за кэша» без проверки фактами.
• Магическое исчезновение: баг пропал, но никто не знает почему.
• Зацикленность: три одинаковые попытки без новых данных — остановись, пересобери факты.

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

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 не наблюдались (быстрый фикс, шотган, спекуляция).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bestdeejay-design
• Source: bestdeejay-design/agent-skills
• License: MIT
• Homepage: https://bestdeejay-design.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.