Plan Audit — аудит и доводка плана до идеала

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

Делает это в два прохода разными под-агентами. Агент работает автономно: под-агенты находят проблемы и улучшения, основной агент сам перепроверяет каждую находку и сам вносит одобренные перепроверкой правки прямо в файл плана. Пользователя не дёргают за подтверждением на каждый пункт — ему показывают итоговую сводку того, что изменено и почему, уже после применения. Защита от ошибки — обязательный бэкап (единственный способ откатить) плюс адверсариальная самопроверка перед каждой правкой.

Если пользователь по ходу просит что-то конкретное не трогать, или сначала показать перед применением — слушай его. Автономность — это поведение по умолчанию, а не запрет на диалог.

Два режима

• Один план — пользователь дал путь или имя. Идёшь по этапам: Этап 0 → 0.5 → 1 → 2 → финал.
• Все планы сразу — пути нет («проверь все планы», «наведи порядок в планах»). Сначала Пакетный триаж (Этап Б): он дёшево сортирует всю папку, мёртвые/поглощённые уносит в архив, а выживших активных пускает через тот же глубокий аудит (Этапы 0→1→2). Когда планов много, это единственный разумный путь — не гонять тяжёлый аудит по каждому.

Принципы (соблюдать на всех этапах)

• Язык — русский. Всегда.
• Универсальность. Скилл работает в любом проекте. Не предполагай структуру репозитория — определи её (Этап 0, discovery). Все проектные файлы (гайд агента, ADR, миграции, spec/research) читай «если есть», с мягким fallback. Жёсткие рамки конкретного проекта (стек, облако, паттерны доступа) бери из самого проекта, а не зашивай в скилл.
• Автономность с самопроверкой. Под-агенты только находят. Основной агент перед записью в файл перепроверяет каждую находку сам (или отдельным агентом-скептиком) и применяет только то, что прошло перепроверку. Спорное и непрошедшее — не применяет, а перечисляет в сводке как «отклонено при перепроверке — почему».
• Бэкап перед любой правкой. Раз правки автономные, бэкап — единственный путь отката. Без него не начинай.
• Отчёты пользователю — простым языком, без терминов. Никаких «idempotent», «discriminated union». Пиши так, чтобы понял человек, который не пишет код. Неизбежный термин — объясни в скобках одним словом.
• Сводка — это нумерованный список. Каждый пункт: что было не так → что я изменил (или почему отклонил) → какой фазы касается.
• Два прохода разделены по смыслу. Агент №1 «Реалист» проверяет, что план правильный, безопасный и совпадает с реальным кодом. Агент №2 «Визионер» проверяет, что план лучший из возможных в мире — и для этого ищет лучшие практики в интернете и на GitHub. Глубокий внешний поиск — только во втором проходе.
• Сначала проверь, не сделано ли уже / не поглощено ли. Перед запуском любых агентов прогони план через гейт актуальности (Этап 0.5). Реализованный целиком или вошедший в другой план не аудируют — его архивируют. У частично реализованного аудируют только незавершённые фазы.

Когда срабатывать

Триггеры (один план): «проверь план», «актуализируй план», «доработай план», «разбери план по фазам», «сделай план идеальным», «убедись что план оптимален», «прогони план через аудит», /plan-audit <путь>.

Триггеры (все планы / пакетный режим): «проверь все планы», «наведи порядок в планах», «разбери планы», «какие планы уже не нужны», /plan-audit без пути.

Не срабатывай: «напиши план с нуля» (→ bulletproof), бизнес-обсуждения, код-ревью, дневной отчёт.

Этап Б. Пакетный триаж (когда плана не назвали)

Это вход для режима «все планы сразу». Дёшево рассортируй всю папку планов, наведи порядок и пусти на дорогой глубокий аудит только живые планы. Полный алгоритм — в references/batch-triage.md. Коротко:

1. Лёгкий параллельный триаж — по одному быстрому read-only агенту на план (применяют только дешёвые сигналы гейта актуальности, без Визионера и GitHub). Каждый возвращает вердикт готов/поглощён/частично/активен/мусор, уверенность, доказательство и рекомендованное действие.
2. Таблица пользователю: план → вердикт → доказательство → действие.
3. Автоуборка: высоко-уверенные готов/поглощён/мусор перемещаешь в архив сам (для поглощён — со ссылкой на план-преемник); спорные/низко-уверенные не трогаешь, выносишь пользователю вопросом.
4. Глубокий аудит выживших (активен/частично) — через Этапы 0→1→2→финал ниже (гейт 0.5 уже сделан триажем). Если выживших >3 — сначала скажи пользователю объём и подтверди.
5. Общая сводка в конце: что в архив, что спорно, что глубоко проверено, насколько чище стала папка.

Дальше — этапы для одного плана (их же использует пакетный режим для каждого выжившего).

Этап 0. Подготовка и discovery (определяем проект)

1. Определи план. Если пользователь дал путь — бери его. Если нет — найди папку планов (plans/, docs/plans/, .plans/ или та, где лежат *.md-планы) и спроси, какой аудируем. Не угадывай.
2. Сделай бэкап. Скопируй файл рядом: <имя>.bak-YYYY-MM-DD (дату возьми из системного контекста, не из головы). Скажи пользователю, что бэкап сделан.
3. Прочитай план целиком и выдели его фазы (по заголовкам и статусам [ ]/[x]).

4. Определи конвенции проекта (discovery). Подробный список того, что искать и как трактовать — в references/discovery.md. Коротко: найди и прочитай (или поручи быстрому read-only агенту) то из перечисленного, что есть в репозитории:

   • гайд для агента/репозитория — CLAUDE.md / AGENTS.md / AGENT.md / .cursorrules / .github/copilot-instructions.md / README.md (карта проекта, стек, жёсткие правила);
   • архитектурные решения — docs/adr/ / docs/decisions/ / architecture/ (план не должен их нарушать);
   • spec и research самого плана (рядом по дате/имени: specs/, thoughts/research/, docs/specs/ — если приняты в проекте);
   • связанные планы, перечисленные в шапке аудируемого плана;
   • миграции БД (если проект их использует: migrations/, prisma/migrations/, alembic/, db/migrate/ …) — для проверки коллизий номеров;
   • бизнес-цели / приоритеты (если зафиксированы — в гайде, README или отдельной папке).

   Из этого собери «контекст-пакет»: 1) короткая выжимка о проекте (что за продукт, стек, жёсткие рамки), 2) пути найденных артефактов, 3) список занятых номеров миграций. Контекст-пакет передавай под-агентам, чтобы они не перечитывали всё заново.

   Discovery делай только после того, как гейт актуальности (Этап 0.5) дал вердикт «аудировать». Для уже реализованного/поглощённого плана он не нужен.

Этап 0.5. Гейт актуальности — а есть ли что аудировать

Перед тратой токенов на агентов основной агент сам (без спавна под-агентов; максимум — один быстрый read-only агент, если кода много) проверяет: не реализован ли план уже — целиком или частично — и не поглощён ли он другим планом. Это короткая ручная сверка плана с реальностью, не полноценный аудит.

Что сверяем (от дешёвого к дорогому, до первого уверенного вывода):

1. Маркеры внутри плана — поле Status: в шапке, статусы фаз [x]/[ ], итоговый блок «Итог»/«Реализовано». Слова «реализовано», «задеплоено», «готово к архивации», коммит/образ в проде — сильный сигнал «сделано».
2. Гайд проекта и память — карта проекта (CLAUDE.md/README) и memory часто прямо фиксируют, что фича выкачена (с хешем коммита).
3. Не поглощён ли другим планом (новая, обязательная проверка). Просмотри соседние планы — активные и в архиве: не покрывает ли scope этого плана уже какой-то другой, более новый план; не были ли его фазы перенесены/слиты в другой план; нет ли «преемника» (superseded by). Сигналы: пересечение названий сущностей/фаз, ссылки «вынесено в …», одинаковые миграции/таблицы. Если scope ушёл в другой план — этот план либо мёртв, либо стал подмножеством.
4. git-история — лог + поиск по ключевым словам фичи: есть ли коммиты, закрывающие фазы.
5. Ключевые артефакты плана — реально ли уже существуют файлы/миграции/схемы/функции, которые план обещает создать (Glob/Grep/Read). Это решающая проверка: код важнее маркеров.

Не верь маркерам вслепую. [x] мог остаться от наброска, а [ ] — у уже выкаченной фичи. Подтверди вывод хотя бы одним сигналом из кода, гита или соседнего плана, а не только статусом в тексте.

Вердикт — один из четырёх. Покажи его пользователю до любого запуска агентов:

• Реализован целиком → СТОП. Аудит не запускаем. Покажи доказательства (коммит/файлы/итог-блок) и предложи перенести план в архив + при необходимости обновить гайд/память. Бэкап .bak с Этапа 0 удали как ненужный.
• Поглощён другим планом → СТОП. Назови план-преемник и доказательства пересечения. Предложи действие: архивировать этот план (со ссылкой «вошёл в …») или, если осталась незакрытая часть, перенести её в план-преемник. Аудит этого файла не гоняем.
• Реализован частично → сузь область. Перечисли, какие фазы уже сделаны (с доказательством) и какие остались. Аудит (Этапы 1–2) гоняем только по незавершённым фазам. Discovery (Этап 0, шаг 4) собирай только теперь.
• Не начат (почти ничего нет) → полный аудит. Собери контекст-пакет и переходи к Этапу 1.

Если вывод неоднозначный (маркеры и код/соседние планы расходятся) — не угадывай: покажи расхождение пользователю и спроси, как трактовать.

Этап 1. Агент №1 «Реалист» — правильно ли и безопасно ли

Цель — для каждой незавершённой фазы ответить на 4 вопроса и проверить реализуемость, безопасность, конфликты и совпадение с реальным кодом.

Запускай разбор фаз параллельно — по одному под-агенту на фазу (в одном сообщении, чтобы шли одновременно). Если фаз много (>8) — группируй по 2–3 близкие на агента. Дополнительно — один агент на план целиком (TL;DR, общая логика, конфликты между фазами).

Промт и точный список проверок — в references/agent-realist.md. Прочитай его перед запуском и подставь: путь к плану, номер и текст фазы, контекст-пакет.

Когда все под-агенты вернулись, примени находки автономно (см. «Как применять правки» ниже): перепроверь каждую → внеси в файл прошедшие → проверь целостность → собери сводку. Затем переходи к Этапу 2.

Этап 2. Агент №2 «Визионер» — лучший ли это план в мире (+ GitHub)

Цель — доказать, что план является лучшим решением проблемы из существующих, или найти решение лучше. Этому проходу нужен интернет (WebSearch/WebFetch).

Запусти агента (можно 1, можно 2–3 параллельно под углами: «как решают в индустрии», «продумали ли на 2–3 шага вперёд», «что упустили»). Обязательная часть прохода — поиск на GitHub: как похожую задачу решают в реальных репозиториях (reference-реализации, библиотеки, паттерны), с оценкой пригодности для нашего проекта (свежесть, поддержка, звёзды, лицензия, совпадение со стеком и рамками). Подходящее — применяем.

Промт — в references/agent-vizioner.md. Подставь путь к плану и контекст-пакет.

Когда агент вернулся, примени находки автономно так же, как в Этапе 1. Крупную структурную переработку применяй только если перепроверка подтвердила, что она сохраняет весь принятый объём и решения проекта; в сводке покажи её отдельно и заметно (бэкап позволит откатить).

Как применять правки (автономно, с самопроверкой)

Этот цикл одинаков для Этапа 1 и Этапа 2.

1. Собери находки под-агентов в один список, сними дубли (одну проблему могли назвать несколько агентов), критичное — выше.
2. Перепроверь каждую находку — адверсариально. Сам или отдельным агентом-скептиком, чья задача — опровергнуть правку. Применяй только то, что переживает все три вопроса:
   • Факт верен? Упомянутый файл/таблица/функция реально существует; номер миграции реально свободен; ссылка на источник реальна. Выдумки — в корзину.
   • Не ломает план? Не противоречит spec/ADR/другим фазам проекта; не выкидывает уже принятый объём; не нарушает жёсткие рамки проекта из discovery.
   • Это реально улучшение? А не вкусовщина, не «побольше текста», не переусложнение.
3. Внеси прошедшие правки прямо в файл плана (Edit/Write). Не показывай diff на согласование — применяй. Сохраняй стиль и форматирование плана.
4. Проверка целостности после правок: нумерация фаз не поехала; внутренние ссылки и ссылки на spec/research/связанные планы живы; TL;DR обновлён под изменения; статусы фаз [ ]/[x] на месте; итоговый блок согласован. Что поехало — почини.
5. Сводка пользователю — простым языком, нумерованным списком: что изменил и почему, плюс отдельным коротким списком — что предложено, но отклонено при перепроверке (и почему). Это информирование постфактум, не запрос разрешения.

Финал. Проверка готовности к исполнению

После двух проходов прогони план по чек-листу готовности — references/readiness-checklist.md. Это мерило «идеального плана». Пробелы (у фазы нет самодостаточного промта для исполнителя или способа проверки) — допиши сам, прошедшее перепроверку; неустранимое автоматически — вынеси пользователю коротким списком.

В конце дай краткое резюме простым языком: что поменялось, готов ли план к исполнению, что (если что-то) осталось за пользователем. Напомни, что бэкап *.bak-<дата> на месте — откат в один шаг.

Файлы скилла

• references/batch-triage.md — пакетный режим: дёшево рассортировать все планы, убрать мёртвые, отобрать живых на аудит.
• references/discovery.md — как определить конвенции любого проекта (что искать, чем заменять, fallback).
• references/agent-realist.md — промт и проверки для Агента №1 (по фазам).
• references/agent-vizioner.md — промт для Агента №2 (индустрия + GitHub + альтернативы).
• references/readiness-checklist.md — чек-лист «план готов к исполнению».