---
name: bug-fix-task
description: Исследовать баг или проблему, найти корневую причину в кодовой базе и сформировать задачу на исправление с TDD-планом. Использовать, когда пользователь сообщает о баге, просит разобраться в проблеме, выполнить диагностику, найти причину сбоя или составить план исправления.
metadata:
  author: Stanislav [MADTeacher] Chernyshev
  url: https://github.com/MADTeacher
  version: "1.0"
---

# Диагностика бага

Исследуй заявленную проблему, найди корневую причину и сформируй задачу на исправление с планом работы через TDD.

Это преимущественно автономный сценарий: задавай пользователю как можно меньше вопросов. Если проблему можно исследовать по коду, тестам, логам или уже предоставленному контексту, сначала исследуй, а не спрашивай.

## Процесс

### 1. Зафиксируй проблему

Получить от пользователя краткое описание проблемы.

Если пользователь еще не описал проблему, задай только один вопрос:

> Что именно не работает или выглядит неправильно?

Не задавай цепочку уточняющих вопросов на старте. После краткого описания сразу переходи к исследованию.

Зафиксируй:

- что происходит сейчас;
- что пользователь ожидал увидеть;
- где проявляется проблема: интерфейс, API, фоновые задачи, данные, интеграция, тесты, сборка, производительность;
- есть ли известный способ воспроизведения;
- есть ли сообщение об ошибке, лог или пример некорректного поведения.

Если части информации нет, не останавливайся. Отметь пробелы и продолжай диагностику по доступным данным.

### 2. Исследуй кодовую базу и найди причину

Изучи кодовую базу, чтобы понять не только симптом, но и причину проблемы.

Цель исследования:

- **где** проявляется баг: входная точка, экран, API-ответ, обработчик события, команда, интеграция;
- **какой путь выполнения** задействован: от входа в систему до места сбоя;
- **почему** возникает ошибка: корневая причина, а не поверхностный симптом;
- **какой связанный код** уже существует: похожие сценарии, соседние модули, существующие тесты, повторяющиеся паттерны.

Проверь:

- связанные исходные файлы и зависимости;
- существующие тесты: что уже покрыто, чего не хватает;
- недавние изменения в затронутой области, если доступна история изменений;
- обработку ошибок на проблемном пути;
- похожие сценарии в кодовой базе, которые работают корректно;
- отличия между рабочим и нерабочим поведением;
- границы модулей и контрактов, которые участвуют в проблеме.

Если есть доступные тесты, запусти релевантные тесты или определи, какие тесты должны падать.

Если проблему можно воспроизвести автоматически, зафиксируй минимальный сценарий воспроизведения.

### 3. Определи подход к исправлению

На основе диагностики определи:

- минимальное изменение, которое исправляет корневую причину;
- какие модули, интерфейсы или контракты затронуты;
- какое поведение нужно проверить тестами;
- является ли проблема регрессией, недостающей функцией, ошибкой в требованиях, ошибкой интеграции или архитектурным дефектом;
- есть ли риск сломать соседние сценарии;
- какие проверки нужны, чтобы исправление было надежным.

Не предлагай исправление, которое лечит только симптом.

Плохой подход:

> Добавить проверку на `null` в месте падения.

Хороший подход:

> Гарантировать, что сценарий обработки неполных данных возвращает корректное состояние ошибки и не передает невалидные данные дальше по контракту.

### 4. Составь TDD-план исправления

Сформируй конкретный упорядоченный список циклов **RED → GREEN**.

Каждый цикл должен быть узким вертикальным срезом:

- **RED** — какой тест нужно написать, чтобы зафиксировать сломанное или отсутствующее поведение;
- **GREEN** — какое минимальное изменение нужно сделать, чтобы этот тест прошел.

Правила:

- каждый тест проверяет наблюдаемое поведение через публичный интерфейс;
- не проверяй приватные методы и внутреннее состояние;
- не привязывай тесты к текущей внутренней структуре кода;
- не пиши сначала все тесты, а потом всю реализацию;
- двигайся по одному тесту за раз;
- каждый цикл должен давать проверяемое улучшение;
- финальный рефакторинг добавляй только после зеленых тестов;
- тесты должны переживать внутренний рефакторинг.

Тест должен выглядеть как спецификация поведения.

Хорошая формулировка:

> RED: написать тест, который проверяет, что API возвращает предсказуемую ошибку валидации при отсутствии обязательного поля.

Плохая формулировка:

> RED: написать тест, который проверяет, что метод `validateInput` вызван один раз.

### 5. Учитывай устойчивость задачи

Итоговая задача должна оставаться полезной даже после существенного рефакторинга кодовой базы.

Описывай:

- поведение;
- контракты;
- пользовательский или системный результат;
- условия воспроизведения;
- ожидаемые результаты;
- проверяемые критерии.

Не привязывай итоговую задачу к хрупким деталям:

- конкретным путям к файлам;
- номерам строк;
- приватным методам;
- внутреннему порядку вызовов;
- временной структуре классов;
- фрагментам кода, которые могут быстро устареть.

Хорошая задача читается как спецификация.

Плохая задача читается как краткое описание будущего diff.

### 6. Сформируй задачу на исправление

После диагностики сформируй готовую задачу по шаблону ниже и запиши ее в markdown-файлы в каталог docs/bug-fix в корневой директории проекта.

<task-template>

## Проблема

Опиши баг или проблему.

Включи:

- что происходит сейчас;
- что должно происходить;
- как воспроизвести проблему, если способ известен;
- где проявляется проблема: пользовательский интерфейс, API, данные, интеграция, фоновый процесс, тесты или другое;
- какое влияние проблема оказывает на пользователя, систему или процесс.

## Анализ корневой причины

Опиши результаты исследования.

Включи:

- какой путь выполнения задействован;
- какой контракт, сценарий или инвариант нарушается;
- почему текущее поведение приводит к ошибке;
- какие факторы способствуют проблеме;
- почему это именно корневая причина, а не только симптом.

Не включай конкретные пути к файлам, номера строк и хрупкие детали текущей реализации.

## Классификация

Укажи тип проблемы:

- регрессия;
- недостающая функциональность;
- ошибка в требованиях;
- ошибка интеграции;
- ошибка обработки данных;
- архитектурный дефект;
- проблема производительности;
- проблема надежности;
- другое.

Кратко объясни классификацию.

## План исправления через TDD

Составь нумерованный список циклов RED → GREEN.

1. **RED**: написать тест, который проверяет <ожидаемое поведение>.
   **GREEN**: выполнить минимальное изменение, чтобы это поведение стало корректным.

2. **RED**: написать тест, который проверяет <следующее важное поведение>.
   **GREEN**: выполнить минимальное изменение, чтобы этот тест прошел.

3. **RED**: написать тест, который проверяет <краевой случай или регрессию>.
   **GREEN**: выполнить минимальное изменение, чтобы этот сценарий был обработан корректно.

**REFACTOR**: описать безопасную очистку кода, которую нужно выполнить после прохождения всех тестов, если она действительно нужна.

## Критерии приемки

- [ ] Проблема воспроизводится тестом до исправления.
- [ ] Исправление устраняет корневую причину, а не только симптом.
- [ ] Основной сценарий работает корректно.
- [ ] Краевые случаи обработаны предсказуемо.
- [ ] Новые тесты проходят.
- [ ] Существующие тесты продолжают проходить.
- [ ] Поведение проверяется через публичные интерфейсы, а не через детали реализации.

## Риски и проверки

Опиши:

- какие соседние сценарии могут быть затронуты;
- какие регрессии важно предотвратить;
- какие ручные проверки нужны, если автоматических тестов недостаточно;
- какие логи, метрики или наблюдаемые признаки стоит проверить после исправления.

## Открытые вопросы

Перечисли вопросы, на которые не удалось надежно ответить во время диагностики.

Не останавливай работу из-за этих вопросов, если можно сформировать безопасный план исправления.

</task-template>

## Финальный ответ пользователю

После формирования задачи дай:

1. готовую задачу на исправление;
2. краткое резюме корневой причины в одно-два предложения;
3. краткий список TDD-циклов;
4. явное указание, какие части анализа подтверждены кодом, а какие являются предположениями.