# Systematic Debugger

> Систематическая отладка по Iron Law: 4 фазы (воспроизведение → гипотезы → изоляция причины → фикс + регресс-тест), Red Flags (quick-fix, спекуляции, шотган-дебаг), Rationalization Table для отсева гипотез. Скрипт debug_log.py оформляет отчёт по фазам (среда, команда, ожидание, факт, гипотезы 1..3, регресс-план). Скилл не автофиксит: фиксирует причину, предлагает минимальный фикс и тест-регрессию.…

- **Type:** Skill
- **Install:** `agentstack add skill-bestdeejay-design-agent-skills-systematic-debugger`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bestdeejay-design](https://agentstack.voostack.com/s/bestdeejay-design)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** https://github.com/bestdeejay-design/agent-skills/tree/main/skills/systematic-debugger
- **Website:** https://bestdeejay-design.github.io/agent-skills/

## Install

```sh
agentstack add skill-bestdeejay-design-agent-skills-systematic-debugger
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## 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](https://github.com/bestdeejay-design)
- **Source:** [bestdeejay-design/agent-skills](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bestdeejay-design-agent-skills-systematic-debugger
- Seller: https://agentstack.voostack.com/s/bestdeejay-design
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.