| name | systematic-debugging |
| description | Систематическая отладка при любых багах, ошибках, неожиданном поведении. Используй ПЕРЕД предложением фиксов. Триггеры: 'не работает', 'баг', 'ошибка', 'сломалось', 'debug', 'почему не', 'странное поведение', 'крон не запустился', 'скрипт падает'. |
Систематическая отладка
Железное правило
НИКАКИХ ФИКСОВ БЕЗ ПОНИМАНИЯ ПРИЧИНЫ
Рандомные фиксы тратят время и создают новые баги. Если не прошёл Фазу 1 - нельзя предлагать решения.
Когда использовать
Любая техническая проблема:
- Крон не запустился / выдал ошибку
- Скрипт падает
- Gateway не отвечает
- Docker контейнер упал
- Память не ищет нужное
- Бот не отправляет сообщения
- Любое "раньше работало, теперь нет"
Особенно когда: под давлением, "очевидный фикс" напрашивается, уже пробовал 2+ решения.
Четыре фазы
Фаза 1: Расследование причины
ПЕРЕД любым фиксом:
-
Прочитай ошибку целиком
- Не пропускай стектрейсы и warnings
- Часто ответ прямо в тексте ошибки
- Запиши: файл, строка, код ошибки
-
Воспроизведи
- Можешь повторить проблему?
- Какие точные шаги?
- Если не воспроизводится - собирай больше данных, не гадай
-
Что изменилось?
git diff, последние коммиты- Обновление платформы? (проверь версию)
- Новые зависимости, конфиг?
memory/progress-log.md - что делалось недавно
-
Проследи поток данных
Для многокомпонентных систем (крон → gateway → агент → tool → результат):
На каждом стыке:
- Что входит?
- Что выходит?
- Где ломается?
Фаза 2: Анализ паттерна
- Найди рабочий пример - похожий скрипт/крон который работает
- Сравни - что отличается между рабочим и сломанным?
- Проверь зависимости - всё ли на месте (docker, npm, пути, права)?
Фаза 3: Гипотеза и тест
- Сформулируй гипотезу - "Я думаю причина в X потому что Y"
- Минимальный тест - ОДНО изменение, ОДНА переменная
- Проверь - сработало → Фаза 4. Нет → новая гипотеза
- НЕ лепи фиксы поверх - если не сработало, откати и думай заново
Фаза 4: Реализация фикса
- Фикси причину, не симптом
- Одно изменение за раз
- Проверь - проблема ушла? Ничего другого не сломалось?
- Запиши -
bash scripts/progress-log.sh + daily notes если важное
- Если 3+ фикса не сработали - СТОП. Проблема архитектурная. Обсуди с Алексеем.
Красные флаги - ОСТАНОВИСЬ
Если ловишь себя на мысли:
- "Быстрый фикс, потом разберусь"
- "Попробую поменять X, вдруг поможет"
- "Добавлю несколько изменений сразу"
- "Не совсем понимаю, но может сработает"
- "Ещё один фикс..." (когда уже 2+ не сработали)
→ СТОП. Вернись к Фазе 1.
Наши типичные проблемы и где искать
| Проблема | Первым делом проверь |
|---|
| Крон не запустился | Проверь cron list → consecutiveErrors, lastStatus |
| Gateway не отвечает | Проверь gateway status, порт |
| Скрипт не найден | Путь, chmod +x, shebang |
| Docker упал | docker ps -a, docker logs <name> |
| Память не ищет | sqlite3 <path>/memory.sqlite "SELECT count(*) FROM chunks;" |
| Бот молчит | message tool → проверь to, channel |
| После обновления | Проверь health-check, перезапусти сервисы |
