debugging-discipline

name	debugging-discipline
description	Дисциплина отладки: стоп-линия при сбое, воспроизводящий тест до фикса, первопричина вместо симптома, минимальная правка, защита от регрессии.

Skill: debugging-discipline

Систематическая отладка вместо угадывания. Дополняет testing-discipline (как писать тесты) и промпт debug-issue.prompt.md (разовая формулировка задачи ассистенту); источник поведенческих правил — AGENTS.md §3–§4.

Когда использовать

• Упали тесты после правки или на чистой ветке.
• Поведение системы не соответствует ожиданиям; ошибка в логах.
• Пришёл баг-репорт от пользователя.
• Что-то работало раньше, но перестало.

Алгоритм

1. Стоп-линия. Прекрати добавлять новое поверх сбоя: неисправленный дефект делает недостоверными все последующие шаги. Сначала чинится сбой, потом продолжается задача.
2. Сохрани доказательства. Текст ошибки, stacktrace, шаги воспроизведения, окружение — до любых правок, пока состояние не потеряно.
3. Воспроизведи стабильно. pytest tests/<модуль> -q или минимальный сценарий. Плавающий сбой — сузь причину: зависимость от времени (добавь логи с метками), от окружения (сравни версии, чистую БД), от состояния (утечки между тестами, синглтоны, общие кэши). Не воспроизвёл — не чини «наугад»: зафиксируй условия и добавь наблюдаемость (logger.debug, не print).
4. Напиши воспроизводящий тест до фикса. Красный тест — критерий успеха: после фикса он зелёный и остаётся в наборе как защита от регрессии.
5. Найди первопричину. Конкретное место (файл, строка, условие): сузь диапазон по git log/git bisect, читай код от симптома вверх по стеку. Отличай причину от симптома — заплатка ниже по потоку не считается фиксом.
6. Исправь минимально. Точечная правка у источника проблемы; несвязанный код не трогать (AGENTS.md §3). Попутные находки — в _docs/current-state.md §2, не в фикс-коммит.
7. Проверь и защити. Баг-тест зелёный, полный pytest -q зелёный, flake8 чистый на изменённых файлах. Коммит — fix(<scope>): ... с тестом в том же коммите.

Чего избегать

• Обходить сбой ради следующей фичи (skip, pytest -k, ослабление ассертов, try/except pass).
• Чинить симптом downstream-заплаткой вместо первопричины.
• Править «по гипотезе» без воспроизведения и красного теста.
• Смешивать фикс с рефакторингом и попутными улучшениями.
• Отлаживать через print вместо точечных структурных логов.