Systematic Debugger

---
name: systematic-debugger
description: "Систематическая отладка по Iron Law: 4 фазы (воспроизведение → гипотезы → изоляция причины → фикс + регресс-тест), Red Flags (quick-fix, спекуляции, шотган-дебаг), Rationalization Table для отсева гипотез. Скрипт debug_log.py оформляет отчёт по фазам (среда, команда, ожидание, факт, гипотезы 1..3, регресс-план). Скилл не автофиксит: фиксирует причину, предлагает минимальный фикс и тест-регрессию. Триггеры: 'debug', 'отладить', 'почему не работает', 'баг', 'исправить ошибку', 'разобраться почему', 'дебаг', 'debugging', 'fix the bug', 'ошибка в коде', 'не работает как ожидалось'.",
license: MIT
metadata:
  author: best
  version: 1.0.0
compatibility: "Requires Python 3 stdlib; works on any language codebase"
when_to_use: "Use when there's a bug or unexpected behavior and you need root cause, not a quick fix. Triggers: 'debug this', 'why is X not working', 'почему не работает', 'отладить', 'исправить ошибку', 'дебаг'. Examples: 'Why does login return 401?' / 'Что-то сломалось, найди причину'."
---

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

## Boundaries

- Do not use for a speculative rewrite without reproduction evidence; first capture the failure.