debugging

name	debugging
description	Structured debugging methodology for systematic problem-solving. Use when user asks to "отладь", "найди баг", "почему не работает", "debug this", "fix bug", "why is this failing", or when code has errors, unexpected behavior, or needs troubleshooting.

Debugging Skill — структурированная отладка

Систематический подход к поиску и устранению багов через воспроизведение, анализ и проверку гипотез.

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

• Код не работает как ожидается
• Есть ошибка или exception
• Непредсказуемое поведение
• Performance проблемы
• Регрессия после изменений

Методология Debugging

Debugging следует научному методу:

1. Reproduce — воспроизвести проблему
2. Isolate — локализовать источник
3. Hypothesize — сформулировать гипотезы
4. Test — проверить гипотезы
5. Fix — исправить и проверить
6. Prevent — предотвратить повторение

---

Шаг 1: Reproduce (Воспроизведение)

Цель: Получить стабильное воспроизведение бага

Что нужно выяснить

✅ Когда проявляется?

• При каких действиях?
• В какой среде (dev/staging/prod)?
• На каких данных?
• Всегда или иногда?

✅ Как проявляется?

• Что именно идёт не так?
• Какая ошибка выдаётся?
• Что ожидалось vs что получили?

✅ Можно ли воспроизвести?

• Шаги для воспроизведения
• Minimal reproducible example
• Условия окружения

Процесс воспроизведения

## Reproduction Steps

1. [Шаг 1]
2. [Шаг 2]
3. [Шаг 3]

**Expected:** [Что должно произойти]
**Actual:** [Что происходит]

**Environment:**
- OS: [macOS/Linux/Windows]
- Version: [версия приложения]
- Dependencies: [ключевые зависимости]

**Error message:**

[Точный текст ошибки]

**Frequency:** [Always / Sometimes / Rare]

Если не воспроизводится

🔍 Debugging the bug:

• Проверь логи — есть ли дополнительная информация?
• Спроси у пользователя точные шаги
• Проверь различия в окружениях
• Race condition или timing issue?

---

Шаг 2: Isolate (Локализация)

Цель: Сузить область поиска проблемы

Техники локализации

Binary Search (Деление пополам)

Убирай части кода пока проблема не исчезнет:

[Весь код] → баг есть
[Первая половина] → баг есть?
  Да → проблема здесь
  Нет → проблема во второй половине

Git Bisect (Поиск коммита)

Если раньше работало:

git bisect start
git bisect bad           # Текущий коммит — плохой
git bisect good <hash>   # Последний хороший коммит
# Git автоматически найдёт проблемный коммит

Isolation через тесты

Создай минимальный тест который показывает проблему:

// ❌ Так проявляется баг
test('minimal reproduction', () => {
  const result = buggyFunction(input);
  expect(result).toBe(expected); // Fails
});

Вопросы для локализации

• В каком файле проблема?
• В какой функции?
• На какой строке возникает ошибка?
• Какие данные вызывают проблему?
• Что было изменено недавно?

Вывод локализации:

## Isolation

**Проблема локализована:**
- Файл: `src/services/payment.ts`
- Функция: `processPayment()`
- Строка: 67
- Условие: Происходит когда `amount > 1000`

**Stack trace:**

Error: Payment processing failed at processPayment (payment.ts:67) at handleCheckout (checkout.ts:42) at onClick (Button.tsx:15)

---

Шаг 3: Hypothesize (Гипотезы)

Цель: Сформулировать возможные причины

Типичные категории багов

🧮 Logic Errors

• Off-by-one ошибки
• Неправильные условия (if/else)
• Неверная математика
• Edge cases не обработаны

💾 State Issues

• Race conditions
• Stale state
• Uninitialized variables
• Memory leaks

🔄 Async Problems

• Promise not awaited
• Callback hell
• Race conditions
• Timing issues

📊 Data Issues

• Null/undefined не проверены
• Неверный тип данных
• Проблемы сериализации
• Кодировка (encoding)

🔌 Integration Issues

• API изменился
• Network timeout
• Dependency версия
• Environment variables

Формулирование гипотез

Для каждой гипотезы:

### Hypothesis #1: [Название]

**Причина:**
[Что могло вызвать проблему]

**Как проверить:**
[Как подтвердить или опровергнуть]

**Likelihood:** [High / Medium / Low]

Пример:

### Hypothesis #1: Race condition в async операции

**Причина:**
Функция `updateUser` вызывается дважды параллельно,
вторая перезаписывает результат первой

**Как проверить:**
1. Добавить логи до и после `await updateUser()`
2. Проверить что функция выполняется синхронно
3. Добавить debounce/throttle

**Likelihood:** High (90%)

---

Шаг 4: Test (Проверка гипотез)

Цель: Подтвердить или опровергнуть каждую гипотезу

Методы проверки

Logging & Debugging

// Добавить логи для отслеживания
console.log('[DEBUG] Input:', input);
console.log('[DEBUG] State before:', state);
console.log('[DEBUG] Result:', result);

// Или использовать debugger
debugger; // Pause execution here

Assertions

// Проверить предположения
console.assert(user !== null, 'User should not be null');
console.assert(amount > 0, 'Amount should be positive');

Experiments

Измени код чтобы проверить теорию:

// Hypothesis: проблема в async
// Experiment: сделать синхронным
const result = await processPayment(data);
// vs
const result = processPaymentSync(data);

Tests

Напиши тест который проверяет гипотезу:

test('race condition when called twice', async () => {
  const promise1 = updateUser(userId, data1);
  const promise2 = updateUser(userId, data2);

  const results = await Promise.all([promise1, promise2]);

  // Should not lose updates
  expect(results).toContainBoth(data1, data2);
});

Проверка гипотез по порядку

Начни с наиболее вероятной (High likelihood):

## Testing Hypotheses

### ✅ Hypothesis #1: CONFIRMED
- Added logs → второй вызов перезаписывает первый
- Timing показывает overlap в выполнении
- **Root cause found!**

### ⏸️ Hypothesis #2: NOT TESTED
- Не нужно — уже нашли причину

### ❌ Hypothesis #3: REJECTED
- Добавил проверку на null → ошибка осталась

---

Шаг 5: Fix (Исправление)

Цель: Устранить root cause, не симптомы

Принципы исправления

1. Fix the cause, not the symptom

// ❌ Fixing symptom
if (result === undefined) {
  result = defaultValue; // Маскирует проблему
}

// ✅ Fixing cause
const result = await calculateResult(data);
// Теперь result всегда определён

2. Minimal change

// ❌ Слишком большое изменение
// Переписал всю функцию

// ✅ Минимальное исправление
// Добавил одну строку с await
const result = await asyncOperation();

3. Make it obvious

// ❌ Неочевидное исправление
const x = data?.value || 0;

// ✅ Очевидное исправление
// Prevent race condition by locking
if (isProcessing) return;
isProcessing = true;
try {
  await processPayment(data);
} finally {
  isProcessing = false;
}

Процесс исправления

## Fix Implementation

**Root Cause:**
Race condition — функция вызывается параллельно

**Solution:**
Добавить механизм блокировки (mutex/semaphore)

**Changes:**
```diff
+ let isProcessing = false;

  async function processPayment(data) {
+   if (isProcessing) {
+     throw new Error('Payment already processing');
+   }
+
+   isProcessing = true;
+   try {
      const result = await api.charge(data);
      return result;
+   } finally {
+     isProcessing = false;
+   }
  }

Testing the fix:

• Unit test проходит
• Integration test проходит
• Manually tested — работает

---

## Шаг 6: Prevent (Предотвращение)

**Цель:** Избежать повторения проблемы

### Добавить защиту

#### Validation

```javascript
function processPayment(amount, user) {
  // Add validation to prevent invalid input
  if (!user) throw new Error('User is required');
  if (amount <= 0) throw new Error('Amount must be positive');
  if (amount > MAX_AMOUNT) throw new Error('Amount too large');

  // ... process payment
}

Tests

// Regression test
test('should not allow concurrent payment processing', async () => {
  const promise1 = processPayment(data);
  const promise2 = processPayment(data);

  await expect(promise2).rejects.toThrow('already processing');
});

// Edge case tests
test('should handle zero amount', () => {
  expect(() => processPayment(0, user)).toThrow();
});

Documentation

/**
 * Process payment for user
 *
 * @throws {Error} If payment is already processing (prevents race condition)
 * @throws {Error} If amount is invalid
 *
 * NOTE: This function uses a lock to prevent concurrent execution.
 *       Do not call multiple times in parallel.
 */
async function processPayment(data) {
  // ...
}

Monitoring

// Add logging for debugging future issues
logger.info('Payment processing started', {
  userId,
  amount,
  timestamp: Date.now()
});

try {
  const result = await processPayment(data);
  logger.info('Payment processed successfully', { result });
} catch (error) {
  logger.error('Payment processing failed', { error, data });
  throw error;
}

---

Debugging Checklist

Quick Checklist для любого бага

• Воспроизведение: Могу стабильно воспроизвести?
• Локализация: Знаю где проблема (файл:строка)?
• Stack trace: Изучил полный stack trace?
• Логи: Проверил логи приложения?
• Данные: Какие данные вызывают проблему?
• Окружение: Проверил версии зависимостей?
• История: Когда последний раз работало?
• Гипотезы: Есть 2-3 теории о причине?
• Тестирование: Проверил гипотезы?
• Root cause: Нашёл настоящую причину?
• Fix: Исправил минимально и очевидно?
• Tests: Добавил regression test?
• Prevention: Добавил защиту от повтора?

---

Debugging Tools

Логирование

// Structured logging
const debug = require('debug')('app:payment');

debug('Processing payment', { userId, amount });
debug('API response', { status, data });

Breakpoints

// Chrome DevTools / VS Code
debugger; // Pause здесь

// Conditional breakpoint
if (amount > 1000) {
  debugger; // Только для больших сумм
}

Assertions

const assert = require('assert');

assert(user !== null, 'User should exist');
assert(amount > 0, 'Amount should be positive');

Stack trace

console.trace('How did we get here?');

// Или
const stack = new Error().stack;
console.log(stack);

Network debugging

# Проверить API запросы
curl -v https://api.example.com/endpoint

# Проверить DNS
nslookup api.example.com

# Проверить connectivity
ping api.example.com

---

Common Bug Patterns

1. Off-by-one

// ❌ Bug
for (let i = 0; i <= array.length; i++) {
  // Вылетит на последней итерации
}

// ✅ Fix
for (let i = 0; i < array.length; i++) {
  // Корректно
}

2. Async не awaited

// ❌ Bug
async function loadData() {
  const data = fetchData(); // Forgot await
  console.log(data); // Promise, not data!
}

// ✅ Fix
async function loadData() {
  const data = await fetchData();
  console.log(data); // Actual data
}

3. Mutating state

// ❌ Bug
function addItem(array, item) {
  array.push(item); // Mutates original
  return array;
}

// ✅ Fix
function addItem(array, item) {
  return [...array, item]; // Immutable
}

4. Null/undefined не проверены

// ❌ Bug
function getName(user) {
  return user.name.toUpperCase();
  // Crashes if user is null
}

// ✅ Fix
function getName(user) {
  return user?.name?.toUpperCase() ?? 'Unknown';
}

5. Race condition

// ❌ Bug
let count = 0;
async function increment() {
  const current = count;
  await delay(100);
  count = current + 1; // Lost updates!
}

// ✅ Fix
let count = 0;
const lock = new AsyncLock();
async function increment() {
  await lock.acquire('count', async () => {
    count = count + 1;
  });
}

---

Best Practices

DO ✅

1. Read error messages carefully

   • Полный текст ошибки
   • Stack trace до конца
   • Warnings тоже важны

2. Use version control

   • git bisect для поиска коммита
   • git diff для изменений
   • git blame для истории

3. Write tests first

   • Failing test = reproduction
   • Passing test = fix confirmed

4. Document findings

   • Причина бага
   • Решение
   • Почему именно так

DON'T ❌

1. Don't guess randomly

   • Не меняй код наугад
   • Сформулируй гипотезу сначала

2. Don't fix symptoms

   • Найди root cause
   • Исправь источник

3. Don't skip tests

   • Regression test обязателен
   • Иначе баг вернётся

4. Don't leave debug code

   • Убери console.log
   • Убери debugger
   • Убери commented code

---

Шаблоны запросов

Общий debugging:

Отладь этот код, он не работает как ожидалось

С ошибкой:

Почему возникает ошибка "Cannot read property 'name' of undefined"?

Performance:

Найди почему эта функция работает медленно

Поведение:

Почему кнопка не срабатывает при клике?

---

Интеграция с другими skills

• Перед debugging → используй research для понимания кода
• После debugging → используй code-review для проверки fix
• Если баг сложный → используй refactoring для улучшения структуры
• Результаты debugging → документируй в комментариях или Todoist