systematic-debugging

name	systematic-debugging
description	Систематическая отладка при любых багах, ошибках, неожиданном поведении. Используй ПЕРЕД предложением фиксов. Триггеры: 'не работает', 'баг', 'ошибка', 'сломалось', 'debug', 'почему не', 'странное поведение', 'крон не запустился', 'скрипт падает'.

Систематическая отладка

Железное правило

НИКАКИХ ФИКСОВ БЕЗ ПОНИМАНИЯ ПРИЧИНЫ

Рандомные фиксы тратят время и создают новые баги. Если не прошёл Фазу 1 - нельзя предлагать решения.

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

Любая техническая проблема:

• Крон не запустился / выдал ошибку
• Скрипт падает
• Gateway не отвечает
• Docker контейнер упал
• Память не ищет нужное
• Бот не отправляет сообщения
• Любое "раньше работало, теперь нет"

Особенно когда: под давлением, "очевидный фикс" напрашивается, уже пробовал 2+ решения.

Четыре фазы

Фаза 1: Расследование причины

ПЕРЕД любым фиксом:

1. Прочитай ошибку целиком

   • Не пропускай стектрейсы и warnings
   • Часто ответ прямо в тексте ошибки
   • Запиши: файл, строка, код ошибки

2. Воспроизведи

   • Можешь повторить проблему?
   • Какие точные шаги?
   • Если не воспроизводится - собирай больше данных, не гадай

3. Что изменилось?

   • git diff, последние коммиты
   • Обновление платформы? (проверь версию)
   • Новые зависимости, конфиг?
   • memory/progress-log.md - что делалось недавно

4. Проследи поток данных Для многокомпонентных систем (крон → gateway → агент → tool → результат):

   На каждом стыке:
   - Что входит?
   - Что выходит?
   - Где ломается?
   

Фаза 2: Анализ паттерна

1. Найди рабочий пример - похожий скрипт/крон который работает
2. Сравни - что отличается между рабочим и сломанным?
3. Проверь зависимости - всё ли на месте (docker, npm, пути, права)?

Фаза 3: Гипотеза и тест

1. Сформулируй гипотезу - "Я думаю причина в X потому что Y"
2. Минимальный тест - ОДНО изменение, ОДНА переменная
3. Проверь - сработало → Фаза 4. Нет → новая гипотеза
4. НЕ лепи фиксы поверх - если не сработало, откати и думай заново

Фаза 4: Реализация фикса

1. Фикси причину, не симптом
2. Одно изменение за раз
3. Проверь - проблема ушла? Ничего другого не сломалось?
4. Запиши - bash scripts/progress-log.sh + daily notes если важное
5. Если 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, перезапусти сервисы