| name | debugging-discipline |
| description | Дисциплина отладки: стоп-линия при сбое, воспроизводящий тест до фикса, первопричина вместо симптома, минимальная правка, защита от регрессии. |
Skill: debugging-discipline
Систематическая отладка вместо угадывания. Дополняет testing-discipline (как писать тесты) и промпт debug-issue.prompt.md (разовая формулировка задачи ассистенту); источник поведенческих правил — AGENTS.md §3–§4.
Когда использовать
- Упали тесты после правки или на чистой ветке.
- Поведение системы не соответствует ожиданиям; ошибка в логах.
- Пришёл баг-репорт от пользователя.
- Что-то работало раньше, но перестало.
Алгоритм
- Стоп-линия. Прекрати добавлять новое поверх сбоя: неисправленный дефект делает недостоверными все последующие шаги. Сначала чинится сбой, потом продолжается задача.
- Сохрани доказательства. Текст ошибки, stacktrace, шаги воспроизведения, окружение — до любых правок, пока состояние не потеряно.
- Воспроизведи стабильно.
pytest tests/<модуль> -q или минимальный сценарий. Плавающий сбой — сузь причину: зависимость от времени (добавь логи с метками), от окружения (сравни версии, чистую БД), от состояния (утечки между тестами, синглтоны, общие кэши). Не воспроизвёл — не чини «наугад»: зафиксируй условия и добавь наблюдаемость (logger.debug, не print).
- Напиши воспроизводящий тест до фикса. Красный тест — критерий успеха: после фикса он зелёный и остаётся в наборе как защита от регрессии.
- Найди первопричину. Конкретное место (файл, строка, условие): сузь диапазон по
git log/git bisect, читай код от симптома вверх по стеку. Отличай причину от симптома — заплатка ниже по потоку не считается фиксом.
- Исправь минимально. Точечная правка у источника проблемы; несвязанный код не трогать (
AGENTS.md §3). Попутные находки — в _docs/current-state.md §2, не в фикс-коммит.
- Проверь и защити. Баг-тест зелёный, полный
pytest -q зелёный, flake8 чистый на изменённых файлах. Коммит — fix(<scope>): ... с тестом в том же коммите.
Чего избегать
- Обходить сбой ради следующей фичи (skip,
pytest -k, ослабление ассертов, try/except pass).
- Чинить симптом downstream-заплаткой вместо первопричины.
- Править «по гипотезе» без воспроизведения и красного теста.
- Смешивать фикс с рефакторингом и попутными улучшениями.
- Отлаживать через
print вместо точечных структурных логов.
