systematic-debugging - Поиск причины ошибки до исправления

Когда звать

• Когда один сбой пережил несколько предположительных правок, а его причина ещё не подтверждена.
• Когда нужно найти границу между компонентами, на которой теряются данные или конфигурация.

Не начинать с предполагаемого исправления

Systematic-debugging предназначен для ситуации, когда тест падает, сборка ломается или программа ведёт себя неожиданно. Его первое требование относится к причине: пока агент её не исследовал, предлагать правки рано. Это отличает скилл от списка типовых способов починки. Он организует расследование, а конкретное изменение должно следовать из собранных сведений о вашем проекте.

На первом этапе агент читает сообщение целиком, включая стек вызовов, пути и коды ошибок. Затем выясняет точные шаги воспроизведения и проверяет, возникает ли сбой постоянно. Если повторить его не удаётся, инструкция предлагает собирать данные вместо догадки. История изменений помогает проверить новые зависимости, настройки и различия окружений, но близость коммита по времени ещё не доказывает причину.

Как найти сломанный переход

Для системы из нескольких компонентов автор отдельно описывает проверку границ. Нужно наблюдать, какие данные поступили в компонент, что вышло и передалась ли нужная конфигурация следующему участнику. Пример относится к цепочке сборки и подписи приложения. Его задача состоит в обнаружении конкретного перехода, на котором окружение перестало соответствовать ожиданиям. Печатать значения секретов ради такого наблюдения не требуется.

Если неверное значение обнаружилось глубоко в стеке, поиск идёт назад к месту происхождения. Исправлять только последний обработчик опасно: источник плохих данных останется прежним. На втором этапе агент ищет похожий рабочий пример в самом репозитории и выписывает отличия. Автор требует читать используемый образец полностью и учитывать даже небольшую разницу, которую хочется заранее объявить несущественной.

Третий этап посвящён одной конкретной гипотезе. Агент формулирует, что считает причиной и на каком наблюдении основан вывод, затем меняет минимально возможную переменную. Если результат не подтверждает предположение, нужна новая гипотеза. Накладывать несколько исправлений друг на друга инструкция запрещает, поскольку тогда невозможно понять, какое из них действительно изменило поведение.

Когда пора остановиться

После подтверждения причины создаётся минимальный воспроизводящий тест. Затем выполняется одно исправление и проверяются исходный симптом и остальные тесты. Если попытка не помогла, цикл исследования возобновляется с новыми данными. После трёх неудачных исправлений автор предлагает остановиться и обсудить устройство системы: повторяющиеся проблемы общего состояния или сильной связанности могут требовать архитектурного решения.

В папке упомянуты отдельные материалы о поиске источника по стеку, дополнительных проверках на разных уровнях и ожидании условия вместо случайной паузы. Эта карточка опирается на основной SKILL.md, а не утверждает, что мы испытали все вспомогательные приёмы. Внешняя или временная причина допускается, если исследование действительно пройдено и записано. Уверенное предположение агента без воспроизведения и проверки остаётся предположением, даже с подключённым Superpowers.