refactor(skills): переработан плейбук координации Codex

- Зачем:
  - Актуализирована координация под Astra с сохранением замысла и бюджета контекста.
- Что:
  - Разделены роли Astra, Sol и Luna; выбор приемов оставлен координатору.
  - Сохранены независимое ревью, триаж и проверка соразмерности исправлений.
  - Обновлены нативные механики и необязательная линия Claude CLI.
- Проверка:
  - Проверены Markdown-ссылки, YAML и git diff --check; описано ограничение валидатора.
  - Пройден поведенческий сценарий с тремя тестами и независимое ревью Claude.
  - Перепроверены находки и фактическое продолжение фоновой сессии Claude.
This commit is contained in:
ddadmin committed 2026-09-06 09:38:57 -04:00
1 parent 65c802f8fc
commit 3a72ce906f
11 files changed
+538 -686

No files matched your search

@@ -1,155 +1,168 @@
# Ревью и триаж
Читай этот файл целиком после выбора независимого ревью постановки или
реализации. Режим и стоимость выбираются в [основной оптике](../SKILL.md);
здесь один авторитетный договор выполнения.
реализации. Это единственный подробный договор обзора, разбора находок и
перепроверки.
- [Независимость и фокус](#независимость-и-фокус)
- [Файловый маршрут](#файловый-маршрут)
- [Отчёт ревьюера](#отчёт-ревьюера)
- [Владелец триажа](#владелец-триажа)
- [Перепроверка и круги](#перепроверка-и-круги)
- [Что читает координатор](#что-читает-координатор)
- [Выбор обзора](#выбор-обзора)
- [Мандат и независимость](#мандат-и-независимость)
- [Отчет ревьюера](#отчет-ревьюера)
- [Разбор находок](#разбор-находок)
- [Перепроверка](#перепроверка)
- [Когда работа не сходится](#когда-работа-не-сходится)
- [Доказательства для координатора](#доказательства-для-координатора)
## Независимость и фокус
## Выбор обзора
Запускай ревьюера свежей сессией без истории исполнителя и других ревьюеров.
Повторную проверку точечных исправлений продолжает тот же ревьюер: его контекст
находок полезен и не отменяет независимость исходного обзора.
Подбирай ревью по неопределенности и цене ошибки. Нативный ревьюер, Claude и
свежая Astra - доступные линии. Обязательного набора нет. Отдельные основания:
свежий контекст ловит предположения автора, другое семейство моделей замечает
иные слепые зоны, Astra судит об устройстве и соразмерности. Одного обзора
достаточно, если он закрывает существенный риск. Две сфокусированные линии
оправданы, когда их независимый вклад стоит цены.
Для двойного ревью разделяй фокусы:
Для двух линий заранее раздели фокус, например:
- **по задаче** — соответствие постановке, критериям, границам и ожидаемому
результату;
- **по коду** — корректность, межмодульные инварианты, регрессии, безопасность
и честность тестов.
- соответствие задаче, границам и наблюдаемому результату;
- корректность, межмодульные инварианты, регрессии и честность проверок.
Давай обоим общую постановку и изменённый объём, но отдельный файл фокуса и
отдельный путь отчёта. Они не знают о второй линии до завершения исходных
обзоров. Разные семейства моделей предпочтительны; две доступные линии одного
семейства всё равно полезны на сложной задаче, если их фокусы различаются.
Перед первым обзором каждой линии зафиксируй проверяемую версию артефакта.
Одна линия делает один общий обзор этой версии. Не запускай новый общий обзор
той же линии без изменения версии или нового основания; точечные исправления
проверяются узко.
Ревьюер — наблюдатель с нужными инструментами. Он может читать код, запускать
тесты, проверять гипотезы, создавать временные кэши и писать назначенный файл
отчёта. Исходники, постоянное окружение и Git он не меняет. Координатор
сверяет состояние дерева до и после.
## Мандат и независимость
## Файловый маршрут
Исходный обзор запускается в свежем контексте без истории исполнителя и других
ревьюеров. Ревьюер получает постановку, точные границы версии, свой фокус,
доступные проверки и уникальный путь отчета. Он самостоятельно сверяет факты,
а утверждения других агентов считает гипотезами до подтверждения.
Назначь каждому участнику уникальные файлы в каталоге задачи внутри
`$SCRATCH`. Временные промпты и отчёты веди на английском.
Ревьюеру разрешены чтение, тесты, доступная сеть, документация и временные
файлы, нужные для проверки. Его мандат запрещает менять исходники, Git,
службы, данные и другое постоянное состояние. Результат обзора - назначенный
отчет; временные кэши и выводы инструментов допустимы.
Координатор остается владельцем общего дерева и стенда и при необходимости
сверяет их состояние до и после обзора.
Полный отчет пишет сам ревьюер в место, доступное владельцу триажа. Координатор
не пересказывает и не восстанавливает доказательства по краткой сводке. Если
общий файл недоступен, используй доступный канал и точно назови ограничение
передачи: где остался полный отчет и какие доказательства не переживут сессию.
Готовые английские блоки мандата и языка лежат в
[шаблоне ревьюера](prompts/review-boilerplate.md) и
[правиле обмена](prompts/runtime-language.md).
## Отчет ревьюера
Ревью возвращает проверяемые утверждения. Каждая находка получает
устойчивый идентификатор с уникальным префиксом линии. Сохраняй идентификатор
во всех следующих разборах и перепроверках. Полная запись содержит:
```text
reviewer -> detailed report file -> triage owner
|
+-> short summary -> coordinator
PREFIX-N | location | violated criterion | failure scenario | evidence |
minimal verification
```
Ревьюер сам пишет полный отчёт в назначенный файл. Координатор не принимает
полный отчёт сообщением и не переписывает его перед передачей. Владелец
триажа читает исходные отчёты напрямую и пишет подробные резолюции в следующий
файл.
Существенный риск безопасно отложенного решения можно записать как
неблокирующее соображение без идентификатора, тяжести и влияния на вердикт.
Если проект или линия уже задает шкалу, добавь в запись тяжесть и считай ее.
Замечание о стиле без проверяемого ущерба остается соображением и не требует
исправления.
`CHANGES_REQUESTED` означает, что версия содержит хотя бы один дефект, который
нужно исправить на ее собственном уровне. `APPROVED` означает отсутствие
такого дефекта.
Если общий каталог недоступен, верни через контекст компактный индекс без
нарратива. Координатор сразу сообщает партнёру, какой агент не получил доступ,
к какому пути, какой запасной канал использован и что нужно проверить после
задачи. Сбой канала ухудшает экономию контекста, но не отменяет ревью.
Даже при нуле находок отчет называет просмотренный объем, проверенные гипотезы,
запущенные команды и их результаты. Голый вердикт без свидетельств не
засчитывается. Сообщение координатору может содержать только вердикт, доступные
счетчики, по одной строке на идентификатор и на каждое существенное
неблокирующее соображение, а также путь к подробному отчету.
## Отчёт ревьюера
## Разбор находок
Каждая находка получает устойчивый идентификатор с уникальным префиксом
линии: `SPEC-A-N` и `SPEC-B-N` для постановки, `TASK-N` для соответствия
реализации задаче и `CODE-N` для качества кода. Полный файл содержит:
Каждую находку сначала проверяют на трех осях: фактическая верность,
применимость сценария к этому проекту и соразмерность исправления. Предложение
ревьюера - один из вариантов. Исполнитель может закрыть дефект более подходящим
путем. Аргументированное отклонение имеет тот же статус, что и подтвержденное
исправление; квота отклонений не нужна.
- идентификатор, тяжесть и `файл:строка` либо раздел постановки;
- нарушенный критерий;
- сценарий сбоя и доказательство;
- минимальный способ проверки.
Находки о постановке разбирает координатор. Он сохраняет цель и границы,
проверяет технические утверждения доступным способом и выносит владельцу
продуктовый выбор или существенный риск.
Неблокирующее соображение не получает идентификатор и тяжесть, не входит в
счётчики и не меняет вердикт. Так сохраняй только существенный риск от
отложенного решения, не проектируя реализацию за следующего владельца.
`CHANGES_REQUESTED` означает, что хотя бы одна находка требует исправить
документ на его собственном уровне. `APPROVED` означает отсутствие такого
дефекта, а не отсутствие всех будущих вопросов.
Находки реализации разбирает исполнитель с контекстом кода. Он получает
подробные отчеты напрямую. Координатор добавляет только решения уровня задачи,
совпадения или противоречия линий. Каждый идентификатор получает один исход:
В сообщение координатору верни только:
- `FIXED` - дефект подтвержден и исправлен; названы способ и проверка;
- `REJECTED` - утверждение не подтвердилось, неприменимо к проекту или не
описывает дефект по действующему договору; приведены контракт и доказательство;
- `OUT_OF_SCOPE` - решение меняет согласованные границы;
- `NEEDS_DECISION` - требуется выбор цели, устройства или остаточного риска.
- `VERDICT: APPROVED | CHANGES_REQUESTED`;
- счётчики по тяжести;
- по одной строке на находку: идентификатор, область, суть и тяжесть;
- по одной строке на существенное неблокирующее соображение, если оно есть;
- абсолютный путь к полному отчёту.
`OUT_OF_SCOPE` и `NEEDS_DECISION` поднимаются координатору с вариантами,
последствиями, стоимостью и рекомендацией исполнителя. Координатор не заменяет
этот разбор молчаливым решением. Подробный файл резолюций сохраняет связь
между исходной находкой, ее исходом и проверкой.
При отсутствии находок полный файл перечисляет просмотренный объём и
выполненные проверки. Голая строка `APPROVED` без подтверждения работы не
засчитывается.
Отклонение предложенного способа починки само по себе не закрывает
подтвержденный применимый дефект. Такой дефект получает соразмерное
`FIXED`, либо решение владельца через `OUT_OF_SCOPE` или
`NEEDS_DECISION`.
## Владелец триажа
## Перепроверка
**Постановка.** Координатор принимает или отклоняет каждую находку, потому что
цель, границы и критерии — его решения. Открытое техническое исследование он
может отдать deep-reasoner, но сам читает верхнеуровневые документы и итоговую
постановку. Продуктовый выбор и принятие риска выносит партнёру.
Точечные исправления и отклонения проверяет тот же ревьюер в продолжении
исходного контекста. Он читает собственный отчет, резолюции и измененную
версию, затем проверяет исходные идентификаторы и только соседние изменения.
Для каждого `FIXED` или `REJECTED` он возвращает `CLOSED`, `NOT_CLOSED`,
`REJECTION_VALID` или `REJECTION_INVALID` с кратким доказательством.
`OUT_OF_SCOPE` и `NEEDS_DECISION` переносятся в индекс без изменения:
ревьюер их не пересматривает и не включает в свой вердикт. Они остаются
открытыми до решения владельца.
**Реализация.** Пофиндинговый триаж делает исполнитель, у которого есть
контекст кода. Координатор передаёт актуальные подробные отчёты выбранных линий
без изменений и добавляет отдельную короткую шапку: совпадения, противоречия и
возможный выход за границы. Он не сливает и не удаляет «дубликаты».
Для `FIXED` ревьюер отдельно оценивает соразмерность починки:
`PROPORTIONATE` либо `OVERREACH` с объяснением лишнего охвата. Для
`REJECTED` он судит по аргументу и проверке; совпадение со вкусом не требуется.
Узкая область не требует скрывать замеченный рядом новый дефект: такой дефект
получает новый устойчивый идентификатор и возвращается владельцу триажа.
Для каждого идентификатора исполнитель возвращает один статус:
Выбранная линия ревью закрывается после начального `APPROVED` без открытых
вопросов либо после успешных нужных перепроверок и разрешения владельцем всех
вынесенных вопросов. Полномочный владелец также может явно записать принятие
оставшегося риска. Вердикт одной линии не закрывает открытые идентификаторы
другой.
- `FIXED` — исправлено и названо доказательство;
- `REJECTED` — отклонено через контракт и проверку;
- `OUT_OF_SCOPE` — требует отдельного решения о границах;
- `NEEDS_DECISION` — технического решения недостаточно.
Изменения шире прежней версии, слабый исходный отчет или новая независимая
неопределенность могут оправдать свежий общий обзор. Сам номер круга такого
основания не создает.
Подробности остаются в файле триажа. Координатор получает по одной компактной
строке `ID | status | essence` на находку, счётчики, вопросы уровня задачи и
путь. Риск и выход за границы решает координатор; техническую истинность
находки — исполнитель и ревьюер.
## Когда работа не сходится
## Перепроверка и круги
Сигналы несходимости: тот же спор повторяется без новых доказательств,
исправления разрастаются дальше исходного риска, новые общие обзоры мало что
добавляют или стороны проверяют разные версии и контракты. Координатор сначала
останавливает петлю и устанавливает общий предмет спора. Затем он может
уточнить постановку, сузить проверку, сменить исполнителя или ревьюера,
повысить доступную модель или глубину, разделить задачу либо принять риск в
пределах полномочий.
Один круг — назначенные обзоры, триаж его владельца и узкая перепроверка.
Исходный ревьюер читает свой отчёт и файл резолюций, проверяет только свои
находки и соседние изменения. Выбранное независимое ревью закрывается
`APPROVED` либо явным принятием риска полномочным координатором или партнёром.
Координатор получает по одной компактной строке со статусом каждого исходного
или нового идентификатора; подробности остаются в файле перепроверки.
Если идентификатор не закрыт либо появился рядом с исправлением, актуальный
отчёт перепроверки напрямую идёт владельцу следующего триажа. Координатор не
восстанавливает доказательства из компактной сводки.
Третий круг - практическое напоминание явно объяснить пользователю или
полномочному владельцу, почему работа не сходится, сколько стоит продолжение и
какой подход меняется. Пятый круг - напоминание не начинать еще один повтор
без явного решения. Это ориентиры наблюдения; обязательных этапов и
автоматических запросов разрешения здесь нет.
Повторно поднятое аргументированно отклонённое замечание пометь как спор и
отправь на отдельную узкую проверку усиленного уровня. Полный новый обзор
нужен, когда реализация широко изменилась, исходный отчёт слаб или требуется
новая независимая линия.
## Доказательства для координатора
Третий круг — точка вмешательства: сообщи партнёру, почему процесс не сходится,
какова стоимость и что меняешь. Координатор может уточнить постановку,
повысить модель или effort, заменить исполнителя свежим сильным агентом,
разделить задачу, назначить усиленный гейт либо принять риск в пределах
мандата.
Координатор обычно получает вердикт, счетчики, компактные строки находок и
пути. Он раскрывает подробный отчет, когда находка меняет границы или риск,
линии противоречат друг другу, возник спор, сводка не дает основания для
решения либо это нужно для собственной приемки. Для спорного утверждения он
читает соответствующее доказательство. Весь diff или журнал нужен лишь когда
узкого фрагмента недостаточно.
Пятый круг не начинай автоматически. Сначала прими явное решение и объясни его
партнёру; если полномочий недостаточно, остановись и запроси решение. Это
предохранитель от дорогой вложенной петли, а не запрет координатору управлять
работой.
## Что читает координатор
Краткие строки находок нужны координатору для сравнения линий. Подробный файл
открывай, когда находка меняет границы или риск, ревьюеры противоречат друг
другу, возник спор, сводка непонятна либо без деталей нельзя выбрать следующий
шаг.
Для обычной починки координатор видит переход:
```text
CHANGES_REQUESTED -> triaged -> rechecked -> APPROVED
```
Полный diff, доказательства и журналы читают назначенные агенты. Координатор
углубляется в них по правилам приёмки основной оптики, когда это нужно для его
собственного решения.
Так защита контекста остается ступенчатой: подробности доходят до владельца
триажа напрямую, а Astra читает ровно тот уровень, который нужен для
самостоятельного решения.