systematic-debugging

Files (2)

• SKILL-public.md
• SKILL.md

SKILL.md (first lines)

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

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

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

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

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

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

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

## Четыре фазы

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

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

1. **Прочитай ошибку целиком**
   - Не пропускай стектрейсы и warnings
   - Часто ответ прямо в тексте ошибки
   - Запиши: файл, строка, код ошибки

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

3. **Что изменилось?**
   - `git diff`, последние коммиты
   - Обновление OpenClaw? (`openclaw --version`)
   - Новые зависимости, конфиг?
   - `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+ фикса не сработали** - СТОП. Проблема архитектурная. Обсуди с {{OWNER_NAME}}.

## Красные флаги - ОСТАНОВИСЬ

Если ловишь себя на мысли:
- "Быстрый фикс, потом разберусь"
- "Попробую поменять X, вдруг поможет"
- "Добавлю несколько изменений сразу"
- "Не совсем понимаю, но может сработает"
- "Ещё один фикс..." (когда уже 2+ не сработали)

→ СТОП. Вернись к Фазе 1.

## Наши типичные проблемы и где искать

| Проблема | Первым делом проверь |
|----------|---------------------|
| Крон не запустился | `openclaw cron list` → consecutiveErrors, lastStatus |
| Gateway не отвечает | `openclaw gateway status`, порт 18789 |
| Скрипт не найден | Путь, chmod +x, shebang |
| Docker упал | `docker ps -a`, `docker logs <name>` |
| Память не ищет | `sqlite3 ~/.openclaw/memory/main.sqlite "SELECT count(*) FROM chunks;"` |
| Бот молчит | message tool → проверь to, channel |
| После обновления | `bash scripts/post-update.sh`, `openclaw doctor` |

From AlekseiUL/heisenberg-team, MIT.

More from AlekseiUL/heisenberg-team