---
name: bug-fix-protocol
description: Structured protocol for fixing bugs with AI agents. Prevents hallucinations and fix loops by enforcing step-by-step diagnosis before code changes.
when_to_use: Use when debugging errors, fixing broken code, or when an AI agent is stuck in a fix loop. Follow before touching any code.
---

# BUG-FIX-PROTOCOL Skill

> Source: https://github.com/CodeAlive-AI/ai-driven-development/blob/main/BUG-FIX-PROTOCOL.md
> Concept by Rodion Mostovoy

## Core Philosophy

**Тест-система = страховочная сетка (safety net)**

- Баг на проде = баг тест-системы в первую очередь
- Каждый баг-фикс = **два фикса**: код + патч тест-системы
- "Тесты" — это не только unit-тесты. Это всё:
  - Unit / Integration / E2E тесты
  - PRD assessment (соответствие продукт-требованиям)
  - Review спеки и документации
  - Code review
  - Статический анализ (linters, type checkers)
  - Визуальные тесты

---

## ⚠️ ГЛАВНОЕ ПРАВИЛО

**НИКОГДА не фиксить баг без воспроизведения через тест.**

Если воспроизвести через тест невозможно — скажи явно с обоснованием. Но не фикси молча.

---

## 8-Шаговый Протокол (Чеклист)

### [ ] Шаг 1 — Понять баг
- Разберись, что именно сломалось
- Придумай способ воспроизведения
- **Непонятно → спроси, не гадай**
- Не трогай код, пока не понял проблему

### [ ] Шаг 2 — Воспроизвести через тест
- Напиши тест, который падает на баге
- Тест должен быть красным ДО фикса
- Если воспроизвести через тест невозможно — **скажи явно с обоснованием**
- Не переходи к шагу 3 без красного теста (или явного объяснения почему нельзя)

### [ ] Шаг 3 — Найти корневую причину
- Ищи **корень**, не симптом
- Задай себе "почему?" минимум 3 раза
- Не фиксируй то, что видишь — найди то, что это вызвало

### [ ] Шаг 4 — Спроектировать правильный фикс
- Придумай грамотный фикс, не костыль
- Оцени scope изменений
- **Большой рефакторинг → остановись, спроси перед началом**
- Фикс должен решать корень, не симптом

### [ ] Шаг 5 — Применить минимальные правки
- Чини с минимальными изменениями
- Не затрагивай части кода, не связанные с багом
- Каждое изменение должно быть обосновано

### [ ] Шаг 6 — Проверить тесты
- Запусти тест из шага 2 → должен быть **зелёным**
- Запусти соседние/связанные тесты → не сломались?
- Запусти полный test suite если возможно
- Только зелёный suite → идём дальше

### [ ] Шаг 7 — Deep Review: похожие проблемы
- Раз тест-система не поймала этот баг — **похожие проблемы могут быть везде**
- Проведи поиск аналогичных паттернов в кодовой базе
- Проверь похожие модули/компоненты
- Задокументируй находки

### [ ] Шаг 8 — Аудит тест-системы
- Разберись, **почему** тест-система упустила этот баг
- Улучши тест-систему чтобы предотвратить класс подобных багов
- Это обязательный шаг, не опциональный

---

## Шаблон: Документация баг-фикса

```markdown
## Bug Fix: [краткое название]

### Что сломалось
[Описание симптома с точки зрения пользователя/системы]

### Как воспроизводится
[Шаги воспроизведения или ссылка на тест]

### Корневая причина
[Настоящая причина, не симптом]

### Решение
[Что было изменено и почему именно так]

### Тест
- Файл: `path/to/test_file`
- Тест: `test_name`
- Статус до фикса: 🔴 RED
- Статус после фикса: 🟢 GREEN

### Deep Review
[Что проверили в похожих местах, что нашли]

### Патч тест-системы
[Что добавили/улучшили в тест-системе]
```

---

## Шаблон: Аудит тест-системы после бага

```markdown
## Test System Audit: [дата] — [тип бага]

### Баг, который проскочил
[Краткое описание]

### Почему тест-система не поймала?
- [ ] Тест не был написан
- [ ] Тест был написан неправильно (не тот assertion)
- [ ] Тест покрывал happy path, не edge case
- [ ] Интеграционный уровень не был покрыт
- [ ] Визуальное изменение без визуального теста
- [ ] Статический анализ не настроен на этот паттерн
- [ ] Другое: ___

### Что улучшаем
| Слой тест-системы | Текущее состояние | Что добавляем |
|---|---|---|
| Unit | | |
| Integration | | |
| E2E | | |
| Static analysis | | |
| Visual | | |

### Action items
- [ ] ...
- [ ] ...

### Принято в работу
- Исполнитель:
- Дедлайн:
```

---

## Применение скилла

Когда тебе дают баг на фикс:

1. Прочитай этот чеклист
2. Иди по шагам **строго по порядку**
3. Не перепрыгивай шаги
4. Если застрял — скажи на каком шаге и почему
5. Финальный PR должен включать: фикс кода + патч тест-системы + документацию по шаблону выше

**Помни:** быстрый фикс без теста — это не фикс, это технический долг с процентами.
