# Systematic Debugging

> Используй при любой ошибке, падении теста или неожиданном поведении — до того как предлагать фиксы

- **Type:** Skill
- **Install:** `agentstack add skill-megamott-vibe-skills-systematic-debugging`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [megamott](https://agentstack.voostack.com/s/megamott)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [megamott](https://github.com/megamott)
- **Source:** https://github.com/megamott/vibe-skills/tree/main/skills/systematic-debugging

## Install

```sh
agentstack add skill-megamott-vibe-skills-systematic-debugging
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Обзор

Случайные фиксы тратят время и создают новые баги. Быстрые патчи маскируют настоящие проблемы.

**Главный принцип:** ВСЕГДА находи корневую причину до попытки исправления. Фикс симптома — это провал.

**Нарушение буквы этого процесса — это нарушение его духа.**

## Железный закон

```
НЕТ ФИКСОВ БЕЗ РАССЛЕДОВАНИЯ КОРНЕВОЙ ПРИЧИНЫ
```

Если не завершил Фазу 1 — нельзя предлагать фиксы.

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

Для ЛЮБОЙ технической проблемы:
- Падения скриптов / тестов
- Баги в поведении
- Неожиданное поведение
- Проблемы производительности
- Ошибки интеграции
- Эндпоинт возвращает неожиданный ответ
- Тест проходит локально, падает в CI

**Используй ОСОБЕННО когда:**
- Давит время («нужно быстро починить»)
- «Очевидный быстрый фикс» кажется понятным
- Уже попробовал несколько фиксов
- Предыдущий фикс не помог
- До конца не понимаешь проблему

**Не пропускай когда:**
- Проблема кажется простой (у простых багов тоже есть корневые причины)
- Торопишься (спешка гарантирует переделку)

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

Каждую фазу нужно завершить до перехода к следующей.

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

**ДО любой попытки фикса:**

1. **Внимательно прочитай сообщения об ошибках**
   - Не пролистывай ошибки и предупреждения
   - Они часто содержат точное решение
   - Читай stack trace полностью
   - Замечай номера строк, пути к файлам, коды ошибок

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

3. **Проверь последние изменения**
   - Что изменилось и могло вызвать это?
   - Последние правки кода, конфигов, шаблонов
   - Изменения во внешних системах (БД, очереди, внешние API, инфраструктура)

4. **Собери доказательства в многокомпонентных системах**

   Когда система имеет несколько компонентов (например, источник данных → обработчик → хранилище):

   ```
   Для каждой границы между компонентами:
     - Зафиксируй что входит в компонент
     - Зафиксируй что выходит из компонента
     - Проверь состояние на каждом слое

   Запусти один раз чтобы собрать доказательства ГДЕ ломается
   ПОТОМ проанализируй доказательства чтобы найти сломанный компонент
   ПОТОМ исследуй именно этот компонент
   ```

   Пример сбора доказательств по слоям — см. [references/debug-commands.md](references/debug-commands.md)

5. **Прослеживай поток данных**

   Когда ошибка глубоко в цепочке вызовов:
   - Откуда берётся плохое значение?
   - Что передало это плохое значение?
   - Продолжай трассировать вверх пока не найдёшь источник
   - Исправляй в источнике, а не в симптоме

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

**Найди паттерн до исправления:**

1. **Найди рабочие примеры**
   - Найди похожие рабочие конфигурации в том же проекте
   - Что работает среди похожего на сломанное?

2. **Сравни с референсами**
   - Если реализуешь паттерн — прочитай референсную реализацию ПОЛНОСТЬЮ
   - Не пролистывай — читай каждую строку
   - Пойми паттерн полностью до применения

3. **Выяви различия**
   - Что отличается между рабочим и сломанным?
   - Перечисли каждое различие, каким бы мелким оно ни было
   - Не предполагай «это не может иметь значения»

4. **Пойми зависимости**
   - Что ещё нужно этому компоненту?
   - Какие настройки, конфиги, предположения?

### Фаза 3: Гипотеза и тестирование

**Научный метод:**

1. **Сформулируй одну гипотезу**
   - Сформулируй чётко: «Думаю X является корневой причиной потому что Y»
   - Запиши
   - Будь конкретным, не расплывчатым

2. **Тестируй минимально**
   - Сделай НАИМЕНЬШЕЕ возможное изменение для проверки гипотезы
   - Одна переменная за раз
   - Не исправляй несколько вещей одновременно

3. **Верифицируй до продолжения**
   - Сработало? Да → Фаза 4
   - Не сработало? Сформулируй НОВУЮ гипотезу
   - НЕ добавляй ещё фиксы сверху

4. **Когда не знаешь**
   - Скажи «Не понимаю X»
   - Не притворяйся что знаешь
   - Попроси помощи
   - Исследуй больше

### Фаза 4: Реализация

**Исправляй корневую причину, а не симптом:**

1. **Создай воспроизводящий тест**
   - Простейшее возможное воспроизведение
   - Используй скилл unit-test-writer для написания падающего теста
   - ОБЯЗАТЕЛЕН до исправления

2. **Реализуй одно исправление**
   - Адресуй выявленную корневую причину
   - ОДНО изменение за раз
   - Никаких «пока я здесь» улучшений
   - Никакого связанного рефакторинга

3. **Верифицируй исправление**
   - Тест теперь проходит?
   - Другие тесты не сломались?
   - Проблема действительно решена?
   - Используй скилл verification-before-completion перед заявлением о готовности

4. **Если исправление не работает**
   - СТОП
   - Посчитай: сколько фиксов попробовано?
   - Если < 3: вернись к Фазе 1, проанализируй с новой информацией
   - **Если ≥ 3: СТОП и ставь под сомнение архитектуру (шаг 5)**
   - НЕ пробуй Фикс №4 без обсуждения архитектуры

5. **Если 3+ фикса не помогли: ставь под сомнение архитектуру**

   **Паттерн указывающий на архитектурную проблему:**
   - Каждый фикс обнаруживает новую проблему в другом месте
   - Фиксы требуют «масштабного рефакторинга»
   - Каждый фикс создаёт новые симптомы в другом месте

   **СТОП и ставь под сомнение фундаментальное:**
   - Этот паттерн фундаментально верен?
   - Стоит ли рефакторить архитектуру vs продолжать фиксить симптомы?

   **Обсуди с пользователем до следующих попыток фикса**

## Красные флаги — СТОП и следуй процессу

Если ловишь себя на мысли:
- «Быстрый фикс сейчас, разберёмся потом»
- «Просто попробую изменить X и посмотрю»
- «Добавлю несколько изменений, запущу тесты»
- «Наверное это X, исправлю»
- «Не полностью понимаю, но это может сработать»
- «Вот основные проблемы: [перечисляет фиксы без расследования]»
- Предлагаешь решения до трассировки потока данных
- **«Ещё одна попытка» (когда уже попробовано 2+)**
- **Каждый фикс обнаруживает новую проблему в другом месте**

**ВСЁ ЭТО означает: СТОП. Вернись к Фазе 1.**

## Типичные рационализации

| Отговорка | Реальность |
|-----------|------------|
| «Проблема простая, процесс не нужен» | У простых проблем тоже есть корневые причины. Процесс быстр для простых багов. |
| «Срочно, нет времени на процесс» | Систематическая отладка БЫСТРЕЕ чем угадывание. |
| «Сначала попробую, потом разберусь» | Первый фикс задаёт паттерн. Делай правильно с начала. |
| «Вижу проблему, исправлю» | Видеть симптомы ≠ понимать корневую причину. |
| «Ещё одна попытка» (после 2+ неудач) | 3+ неудачи = архитектурная проблема. Ставь под сомнение паттерн. |

## Краткая справка

| Фаза | Ключевые действия | Критерий успеха |
|------|------------------|-----------------|
| **1. Корневая причина** | Читай ошибки, воспроизводи, проверяй изменения, собирай доказательства | Понимаю ЧТО и ПОЧЕМУ |
| **2. Паттерны** | Найди рабочие примеры, сравни | Выявлены различия |
| **3. Гипотеза** | Сформулируй теорию, тестируй минимально | Подтверждена или новая гипотеза |
| **4. Реализация** | Создай тест, исправь, верифицируй | Баг решён, тесты проходят |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [megamott](https://github.com/megamott)
- **Source:** [megamott/vibe-skills](https://github.com/megamott/vibe-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-megamott-vibe-skills-systematic-debugging
- Seller: https://agentstack.voostack.com/s/megamott
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.