Skill v1.0.2

currentAutomated scan100/100

steelmorgan/1c-agent-based-dev-framework/runtime-investigation

~1 modified

──Details

PublishedJuly 14, 2026 at 06:01 PM

Content Hashsha256:9ba84f503b8f6a1f...

Git SHA19f67bfed6d1

Bump Typepatch

Compare with v1.0.1

──Files

Files (1 file, 23.5 KB)

SKILL.md23.5 KBactive

SKILL.md · 342 lines · 23.5 KB

version: "1.0.2" name: runtime-investigation description: "Runtime-диагностика бага: call graph, DAP, трассировка"

Runtime Investigation — расследование багов в рантайме

1. Когда применять

Цель навыка — ответить на три вопроса в строгом порядке:

Что фактически происходит? Вызывается ли процедура? С какими аргументами? Какие значения переменных? Какой путь по if/else? Что вернул запрос?
Совпадает ли это с ожиданием? (из спеки/дизайна/ассерта теста — bug-report.expectation)
Где источник расхождения?

Код неверен — поведение не соответствует требованию
Код верен, данные не те — контракт нарушен на стороне вызывающего/подготовки данных
Код соответствует спеке, спека неверна/неполна
Тест/сценарий проверяет не то

Без шага 1 шаги 2-3 невозможны.

Триггер запуска: оркестратор передал bug-report.json со статусом open.

2. Иерархия инструментов (от дешёвого к дорогому)

Уровень	Инструмент	Когда
L0	Чтение исходников + спеки/дизайна (`code-navigation`)	Всегда первым
L1	`event-log-analysis` — ЖР через ClickHouse	Уже отработавший прогон, есть Error/Warning
L2	`platform-data-core` § Query Execution — запросы к БД	Проверить состояние данных независимо от кода
L3	`dap-bsl-code-debug-procedure` — интерактивный DAP/MCP-отладчик	Есть безопасный воспроизводимый сценарий и нужны stack/locals/step по 1-3 точкам
L4	`agent-debug` точки в коде + ЖР	DAP не подходит или нужен широкий trace: факт вызова, путь if/else, значение/тип переменной
L5	Перепрогон сценария/теста после DAP/проб	Собрать наблюдения
L6	`gui-control` + `screenshot`	Симптом в UI, неясно что на форме
L7	`syntax-checking` (`get_diagnostics` / `v8-runner syntax …`)	После любого изменения кода
L8	`tech-log-analysis` — техжурнал	ТОЛЬКО с явного согласия пользователя. Тяжёлый, медленный. Когда L0-L7 не дали ответа: блокировки, deadlock, скрытые исключения платформы, медленные SQL

L0-L7 дебаггер использует автономно. Переход на L8 требует выйти к оркестратору с структурированным запросом:

Какую гипотезу нельзя проверить через L0-L7 и почему
Какие события техжурнала нужны (EXCP / DBMSSQL / TLOCK / TDEADLOCK / TTIMEOUT / CALL)
Ориентировочное время сбора

Оркестратор переспрашивает пользователя. Без согласия — НЕ поднимать.

3. Полный алгоритм

ФАЗА 1. Подготовка
1.1 Прочитать bug-report.json. Перевести status → in_investigation.
1.2 Воспроизвести баг детерминированно (запустить указанный тест/сценарий).
- Не воспроизводится → flaky, эскалация оркестратору.
1.3 Прочитать код вокруг точки симптома + спеку/дизайн (L0).
1.4 Построить ГРАФ ВЫЗОВОВ от точки входа сценария/теста до точки симптома (см. §4).
1.5 Выделить КЛЮЧЕВЫЕ ПЕРЕМЕННЫЕ (см. §5).

ФАЗА 2. Первая проходка (БЕЗ гипотез)
2.1 Выбрать способ runtime-наблюдения:
- DAP/MCP-отладчик: если безопасно остановить поток и нужно увидеть stack/locals/step.
- agent-debug + ЖР: если нужна широкая трасса или остановка потока рискованна.
2.2 Для DAP: поставить breakpoint в ключевой точке, запустить сценарий, poll `wait_for_stop`
каждые 5 секунд (быстрый код — до 30 секунд; тяжёлый — по заранее заданному пределу),
записать stack/locals/шаги в trace-run-1.md, затем очистить breakpoint, отпустить поток и выполнить detach.
2.3 Для agent-debug: расставить пробы H0 на узлах графа
(префикс `AGENTDEBUG-<bug-id>-H0-NNN`):
- маркер EXECUTED
- снимок ключевых переменных (безопасная сериализация — §6)
Прогнать сценарий/тест.
2.4 Прочитать ЖР или DAP-наблюдения, собрать трассу: какие узлы прошли, состояние переменных.
Сохранить в task_dir/.context/debug/<bug-id>/trace-run-1.md.
2.5 Сравнить трассу с ожиданием. Локализовать первое расхождение «ожидание ≠ факт».
Если трассы достаточно, чтобы сразу определить причину → переход к Фазе 4.

ФАЗА 3. Цикл гипотез (≤ 5 итераций; +3 расширение, max 8 — см. §7)
Для гипотезы N (1..5, при расширении 6..8):

3.N.1 Сформулировать наиболее вероятную гипотезу НА ОСНОВЕ ТЕКУЩЕЙ ТРАССЫ
(не из головы). Записать в debug-report.md:
- формулировка
- evidence_from_trace (на каком факте из трассы основана)

3.N.2 Выбрать способ проверки:
(a) пробный фикс — узкое изменение в коде/тесте/сценарии,
которое легко откатить;
(b) дополнительные пробы (префикс `AGENTDEBUG-<bug-id>-H<N>-NNN`) —
новые ключевые переменные, узлы между размеченными,
состояние данных через platform-data-core § Query Execution.

3.N.3 Применить, прогнать, прочитать трассу. Сохранить trace-run-<N+1>.md.

3.N.4 Развилка:
✓ ПОДТВЕРЖДЕНА → переход к Фазе 4 (фикс по правилам)
✗ НЕ подтверждена:
- откатить пробный фикс (если был)
- снять пробы ИМЕННО ЭТОЙ гипотезы (grep H<N>); пробы H0 и
предыдущих опровергнутых гипотез ОСТАЮТСЯ
- зафиксировать в debug-report.md: что проверял, результат,
почему опровергнута
- переход к гипотезе N+1

Между итерациями допустимо вернуться к Фазе 1 и расширить граф/ключевые
переменные, добавив новые H0+ пробы (например, появились новые вызывающие
места). Это не считается отдельной гипотезой.

После 5 неподтверждённых:
- если есть конкретная следующая гипотеза с высокой уверенностью →
обратиться к оркестратору с запросом на расширение +3 (max 8 всего)
- иначе → Фаза 5 (эскалация)

ФАЗА 4. Фикс (если гипотеза подтвердилась)
4.1 Оценить масштаб по критерию «локальный vs возврат» (§8).
4.2 Локальный → применить фикс, прогнать упавший тест/сценарий + смежные.
- Должно стать зелёным
- Если не стало — это была ошибочная гипотеза, вернуться в 3.N.4 с откатом
4.3 Масштабный → возврат оркестратору с пояснением и рекомендацией
(какому агенту передать).

ФАЗА 5. Эскалация (5/8 гипотез исчерпаны или масштаб слишком большой)
5.1 Краткий структурированный отчёт оркестратору (см. §9).
5.2 Оркестратор передаёт пользователю.

ФАЗА 6. Очистка (ВСЕГДА перед завершением — успехом или эскалацией)
6.1 Если использовался DAP: `clear_breakpoints`, безопасный `continue`, `detach`;
при `ibInDebug`/зависшей сессии — `force_detach` и повторная проверка targets.
6.2 grep `//[AGENTDEBUG-` → ноль вхождений во ВСЕХ затронутых файлах.
6.3 Если поднимали техжурнал — восстановить исходный конфиг.
6.4 syntax-checking по затронутым модулям.
6.5 Финальный debug-report.md с итоговым статусом и обновление
bug-report.json (status: fixed_locally / returned_to_author / escalated_to_user).

4. Построение графа вызовов

Стартовая точка — место наблюдаемого симптома (упавший ассерт, исключение, неверное значение из bug-report.symptom.fail_location).

Метод: идти НАЗАД от симптома вверх по стеку:

Какая процедура его вызвала?
Кто вызвал её?
… до точки входа сценария/теста.

Инструменты: code-navigation (навигация по символам), чтение модуля, поиск по Вызвать / Выполнить / обработчики событий формы / экспортные процедуры менеджера.

Результат: список узлов графа в виде:

[Тест.МойТест]
  → [Документ.РасходТовара.Объект.ОбработкаПроведения]
    → [ОбщийМодуль.РассчитатьСкидку]
      → [ОбщийМодуль.ПолучитьКатегориюКлиента]  ← точка симптома

Сохранить как task_dir/.context/debug/<bug-id>/call-graph.md.

5. Выделение ключевых переменных

Определение: ключевая переменная — та, которая влияет на:

Условие исполнения проблемной точки (входит в Если/Иначе/Пока/Для на пути к симптому), либо
Результат вычисления в проблемной точке (входит в формулу/запрос/возвращаемое значение), либо
Ветвление выше по стеку, ведущее к этой точке.

Метод выделения — обратный обход:

В точке симптома: какие переменные участвуют в ассерте/формуле? → ключевые.
По графу вверх: какие переменные участвуют в условиях, ведущих к этой точке? → ключевые.
Параметры процедур, передаваемые и трансформируемые по пути → ключевые.
Глобальные параметры сеанса (текущий пользователь, дата актуальности, активная организация) — по умолчанию ключевые, если не доказано обратное.

НЕ ключевые: локальные переменные, используемые только для расчёта без влияния на ветвление и не возвращаются.

Сохранить как task_dir/.context/debug/<bug-id>/instrumentation-plan.md: какие пробы куда ставит, какие ключевые переменные в каждой.

6. Безопасная сериализация при логировании

В пробах agent-debug фиксировать значения переменных. НЕ дампить целиком:

Тип	Что НЕ логировать	Что логировать вместо
Документ/Справочник Объект	Весь объект	`ТипЗнч`, `Ссылка`, релевантные реквизиты по одному
ТаблицаЗначений	Все строки	`Количество()`, поля первой/проблемной строки
Структура	Сериализацию	`Количество()`, список ключей через запятую
Соответствие	Сериализацию	`Количество()`, ключ-цель если ищем конкретный
Объект формы	Целиком	Конкретные реквизиты формы по одному
Запрос	Текст полностью	Имя, ключевые параметры
Метаданные	`Метаданные.X.<всё>`	Только имя типа: `Метаданные(Ссылка).Имя`
Двоичные данные	Содержимое	`Размер()`
Пароли, токены, ПД	Никогда	Замаскировать или пропустить

Правило главное: логируем только те поля объекта, которые код реально читает на пути к симптому (определяется по §5). Не дамп всего объекта.

Параметр-объект как ключевая переменная: если ключевая переменная — ссылка/объект, моделировать в эксперименте нужно именно тем объектом, на котором баг воспроизводится. Не подменять «похожим» из базы.

7. Лимит гипотез

По умолчанию: 5 гипотез. После 5-й неподтверждённой — эскалация.

Расширение +3 (max 8 всего): допустимо однократно, если:

появилась конкретная следующая гипотеза с высокой уверенностью (есть прямые улики из трассы),
запрос отправлен оркестратору с обоснованием,
оркестратор согласовал.

Если уверенность низкая — НЕ просить расширение, эскалировать сразу.

Качество > количество. Каждая гипотеза в debug-report.md обязана иметь evidence_from_trace — на каком факте из собранной трассы она основана. Это блокирует «гипотезы наугад».

8. Критерий «локальный фикс vs возврат оркестратору»

Дебаггер чинит сам, если выполнены ВСЕ условия:

Изменение в ≤ 2 файлах продкода ИЛИ ≤ 1 файл теста/сценария
Не меняется публичный API (экспортные процедуры, их сигнатуры)
Не меняется спека и technical-design
Не затрагивает protected_paths из bug-report
Фикс умещается в ~30 строк диффа

Возврат оркестратору в любом из случаев:

Нужно менять спеку → Analyst
Нужно менять технический дизайн или добавлять API → Architect
Нужно переписывать > 2 файлов → Developer-Code
Нужно менять .feature или step-library широко → Scenario-Author / Scenario-Coder
Баг в данных, требует пересмотра подготовки тестового окружения → Developer-Tests или Scenario-Coder

После локального фикса — обязательная верификация:

Перепрогнать упавший тест/сценарий → должен быть зелёным.
Перепрогнать связанные unit-тесты модуля и Vanessa-сценарии с тем же тегом задачи.
Проверить, что не сломалось ничего смежного (узкая регрессия).
Если verification failed — это была ошибочная гипотеза, откатить фикс, вернуться в 3.N.4.

Локальный фикс ВСЕГДА проходит ревью (Reviewer scope=debug или соответствующий типу артефакта) — иначе минует контроль качества.

9. Шаблон `debug-report.md`

Сохраняется в task_dir/.context/debug/<bug-id>/debug-report.md.

markdown

# Debug Report — <bug-id>
 
## Источник
-Bug-report: <ссылка на bug-report.json>
-Симптом: <symptom.what_ran> упал на <fail_location>
-Ожидание: <expectation.quote> (источник: <expectation.source>)
 
## Воспроизведение
-Команда: <symptom.command>
-Детерминизм: <yes/no>
 
## Граф вызовов
<ссылка на call-graph.md>
 
## Ключевые переменные
<ссылка на instrumentation-plan.md>
 
## Первая проходка (H0)
-Прогон: <ссылка на trace-run-1.md>
-Локализация расхождения: <узел графа + что не сошлось>
 
## Гипотезы
 
### H1: <формулировка>
-Evidence_from_trace: <на каком факте из трассы основана>
-Способ проверки: <фикс / доп.пробы>
-Прогон: <ссылка на trace-run-N.md>
-Результат: ПОДТВЕРЖДЕНА / ОПРОВЕРГНУТА
-Если опровергнута — почему: <...>
 
### H2: ...
...
 
## Вердикт
-Класс причины: код / данные / спека / тест/сценарий
-Корневая причина: <...>
-Затронутый слой источников правды (L1-L6): <см. source-of-truth-policy>
 
## Действие
-ВАРИАНТ A — Локальный фикс:
  -Файл(ы): <...>
  -Дифф: ≤ 30 строк
  -Верификация: упавший тест зелёный, смежные тесты зелёные
  -Подлежит ревью: scope=debug
-ВАРИАНТ B — Возврат оркестратору:
  -Кому передать: <agent>
  -Почему масштаб большой: <...>
  -Рекомендация по фиксу: <...>
-ВАРИАНТ C — Эскалация:
  -5/8 гипотез не подтверждены
  -Что точно установлено: <...>
  -Что хотелось бы проверить, но не получилось: <...>
  -Рекомендация: к кому идти (Architect / Analyst / пользователь)
 
## Очистка
-[x] DAP breakpoint сняты, поток отпущен через `continue`/release, выполнен `detach` / `force_detach` (если DAP использовался)
-[x] grep `//[AGENTDEBUG-` → 0 вхождений
-[x] техжурнал восстановлен (если поднимался)
-[x] syntax-checking пройден

10. Антипаттерны

Антипаттерн	Последствие
Гипотеза без `evidence_from_trace`	Угадывание; ресурс расследования тратится впустую
Не снять пробы опровергнутой гипотезы перед следующей	Шум в трассе, путаница в интерпретации
Оставить пробный фикс при опровергнутой гипотезе	Накопление мусора в коде
Дамп всего объекта в `agent-debug` точке	Переполнение ЖР, утечка данных
DAP breakpoint оставлен активным	Следующие прогоны останавливаются в неожиданных местах
`detach`/`force_detach` не выполнен при `ibInDebug`	База остаётся занятой debug-сессией
Подмена тестового объекта «похожим» из базы	Баг не воспроизведётся, ложный отрицательный результат
Поднять техжурнал без согласия пользователя	Нарушение политики; тяжёлый процесс зря
10+ проб H0 без чётких ключевых переменных	Широкое наблюдение, непонятный результат → разбить на гипотезы
Пропустить очистку перед завершением	Маркеры `AGENTDEBUG` уйдут в коммит
Пропустить верификацию после локального фикса	Ложный «починил», на самом деле сломали смежное

depends_on:

framework/skills/tool-usage/diagnostics/bug-reporting/SKILL.md
framework/skills/tool-usage/diagnostics/dap-bsl-code-debug-procedure/SKILL.md
framework/skills/tool-usage/diagnostics/agent-debug/SKILL.md
framework/skills/tool-usage/diagnostics/event-log-analysis/SKILL.md
framework/skills/tool-usage/diagnostics/tech-log-analysis/SKILL.md
framework/skills/tool-usage/platform-data/platform-data-core/SKILL.md
framework/skills/tool-usage/code-analysis/code-navigation/SKILL.md
framework/skills/tool-usage/code-analysis/syntax-checking/SKILL.md
framework/rules/dap-bsl-debugger/SKILL.md
framework/rules/source-of-truth/SKILL.md

← v1.0.1 All versions