refactor(skill): плейбук возвращён к оптике тонкого мастера

- Зачем: - субагенты должны сохранять внимание мастера и помогать результату, а не обслуживать обязательный конвейер. - Что: - семиступенчатый процесс заменён эвристиками выбора исполнителя, проверяющего и независимого ревьюера. - права агентов отделены от канала результата, а полная полезная нагрузка выведена из контекста мастера. - добавлены авторитетные договоры промптов, полевые заметки и handoff следующей сессии. - Проверка: - git diff --cached --check. - свежий обзор через writing-great-skills, все принятые находки закрыты.
2026-07-12 23:50:37 +03:00
1 parent 7110a075ea
commit f9ea5b8c44
@@ -1,73 +1,39 @@
 # Полевые заметки

-Читай этот файл при развитии скилла и при первом прогоне в новой среде. После
-боевого прогона записывай только факты, которые меняют процесс. Когда урок
-поглощён `SKILL.md` или `roles.md`, сжимай запись до одной строки со ссылкой.
+Читай при развитии скилла и первом прогоне в новой среде. Храни здесь только
+факты, которые меняют выбор приёма, и живые предположения. Поглощённый урок
+сжимай до одной строки с указателем на действующий договор.

-## Перенесено из исходного плейбука
+## Наблюдения

- Разные семейства моделей находили почти непересекающиеся классы ошибок.
-  Это аргумент за внешний обзор, но не обязательная часть конвейера.
- Ревьюер без прав на запись хуже проверял гипотезы, когда тестам нужны кэши
-  и временные артефакты. Рабочая защита: точка отсчёта Git, явный мандат не
-  менять исходники и сверка дерева после ревью.
- Пустой вердикт сам по себе не доказывает работу ревьюера. Нужны покрытие,
-  выполненные команды или другие наблюдаемые доказательства.
- Настройки модели, унаследованные от интерактивной сессии, менялись между
-  запусками. Для управляемой стоимости модель и глубину надо закреплять.
- Критичный отчёт фонового агента мог потеряться после его завершения.
-  Надёжнее сообщение плюс файл с индексом.
- Ссылка на другой скилл в файле-задаче не проверена как надёжный способ его
-  включить. Ключевые требования надо дублировать текстом.
- Прямой запуск внешнего Codex зависел от версии песочницы, AppArmor и сети.
-  Нативный конвейер не должен зависеть от внешнего CLI.
+- 2026-07-10 — хост скрыл выбор роли и модели; стоимость осталась
+  незакреплённой. Исследователь нашёл блокирующий `.gitignore`, но без нужды
+  запустил полный набор тестов. Вывод поглощён в
+  [основную оптику](../SKILL.md) и [мандаты](roles.md).
+- 2026-07-10 — главной утечкой контекста была повторная передача отчётов и
+  промптов через мастера. Вывод поглощён в [правила обмена](../SKILL.md) и
+  [сборку промптов](prompt-templates.md).
+- 2026-07-12 — разные семейства ревьюеров пересеклись в двух темах примерно из
+  восьми и сохранили заметный независимый вклад. Вывод поглощён в
+  [основную оптику](../SKILL.md).
+- 2026-07-12 — самоприменение поймало сломанную сборку с необязательным
+  `notes.md` и показало, что язык обмена надо задавать явно. Вывод поглощён в
+  [сборку промптов](prompt-templates.md).
+- 2026-07-12 — тот же прогон выявил регрессии производного скилла: второй
+  ревьюер того же семейства не давал новой родословной; мастер вывел в свой
+  контекст 44 хэша, полный отчёт и почти весь diff; права ревьюера смешались с
+  каналом результата; семь буквальных этапов породили лишние проверки. Вывод
+  поглощён в [основную оптику](../SKILL.md).

 ## Проверить боем

 1. Выбирает ли текущий хост пользовательского агента по имени и показывает ли
-   фактически использованную модель после запуска новой сессии с TOML.
-2. Даёт ли набор быстрых ролей экономию без повторной работы сильной модели.
-3. Остаётся ли дерево неизменным после ревьюера с `workspace-write`.
+   фактически использованную модель после новой сессии с TOML.
+2. Даёт ли дешёвая роль экономию без повторной работы сильной модели.
+3. Остаётся ли дерево неизменным после ревьюера с `workspace-write` и явным
+   мандатом не менять исходники.
 4. Доступны ли ревьюеру поиск и документация при текущих сетевых разрешениях.
-5. Достаточно ли общего договора возврата, чтобы мастер не открывал сырые
-   журналы и полные отчёты.
-6. Где проходит практический порог между прямой работой и полным конвейером.
-
-## 2026-07-10 — пробный прогон этапов 1–2
-
- Мастер без истории исходного плейбука поднял исследователя и ревьюера,
-  свёл их вывод в самодостаточную постановку и не вынес сырые журналы в
-  итоговый контекст.
- Конкретный tool-backed хост скрыл из схемы `spawn_agent` поля `agent_type`,
-  `model`, `reasoning_effort` и `service_tier`. Это ограничение той сессии,
-  а не Codex в целом: актуальная нативная схема поддерживает все четыре поля.
-  Роли в прогоне были только мандатами в промпте; мастер верно отметил
-  стоимость той сессии как неуправляемую.
- Исследователь обнаружил блокирующее правило `.gitignore` для будущих TOML,
-  которое мастер без шумного обхода репозитория мог пропустить.
- Исследователь без необходимости запустил полный набор тестов. Ограничение
-  «карта команд, а не полный прогон» поглощено в `SKILL.md` и `roles.md`.
-
-## 2026-07-10 — проверка документации и исходного кода Codex
-
- Нативный `spawn_agent` принимает `agent_type`, `model`,
-  `reasoning_effort` и `service_tier`.
- Полный fork `all` наследует модель мастера и отклоняет роль, модель и
-  глубину. Плейбук выбирает `none` ради чистого контекста; ограниченный fork
-  числом технически совместим с переопределениями.
- Хост может намеренно скрыть эти поля из видимой схемы. В такой сессии
-  мастер не может гарантировать стоимость через нативный вызов.
- TOML-роли остаются правильным способом закрепить модель и глубину. После
-  их установки нужна новая сессия и проверка фактической схемы инструмента.
- `service_tier` не блокируется полным fork, но задаётся только по явному
-  запросу.
-
-## 2026-07-10 — ретро утечки контекста прародителя
-
- Главная утечка была не в работе агентов, а в повторной передаче одного
-  текста через мастера: отчёт, новый промпт, повторная проверка и tool-call.
- Нативный Codex не наследует буквально поведение Claude `SendMessage`, но
-  длинные аргументы `spawn_agent`, `send_message` и `followup_task` всё равно
-  остаются в истории мастера.
- Лечение поглощено в `SKILL.md` и `prompt-templates.md`: файловый канал,
-  один канонический промпт и ожидание только на критическом пути.
+5. Достаточно ли файлового канала, чтобы мастер не открывал полный отчёт и
+   сырые журналы.
+6. Когда отдельный проверяющий или вторая линия ревью окупаются лучше
+   объединения совместимой работы.
@@ -1,87 +1,88 @@
-# Скелеты нативных промптов
+# Сборка нативных промптов

-Читай только тот раздел, который нужен на текущем этапе. Полный текст
-задания и отчёта живёт в обменном временном каталоге; вызов агента содержит
-короткую обёртку с абсолютными путями.
+Открывай только раздел выбранного приёма. Это справочник готовых договоров,
+а не обязательная последовательность. Постоянный текст живёт в
+[prompts/](prompts/):

-## Общий договор результата
+- [result-contract.md](prompts/result-contract.md) — обычный результат;
+- [review-boilerplate.md](prompts/review-boilerplate.md) — слепое ревью;
+- [triage-header.md](prompts/triage-header.md) — закрытие находок;
+- [recheck-header.md](prompts/recheck-header.md) — узкая перепроверка;
+- [runtime-language.md](prompts/runtime-language.md) — язык временного обмена.

-Полный отчёт, независимо от канала:
+Текст договора меняй только в его авторитетном файле. Здесь остаются выбор и
+механика сборки.
+
+## Канал результата
+
+Канал выбери по [основной оптике](../SKILL.md). Здесь важна только механика:
+для файлового канала задай уникальный `REPORT`, для сообщения не создавай
+вторую копию результата.
+
+## Обычный исполнитель или исследователь
+
+Параметрический файл содержит только нужные конкретной задаче поля:

 ```text
-ИТОГ: завершено | есть вопросы | заблокировано
-ДОКАЗАТЕЛЬСТВА: изменённые файлы, команды и итоговые счётчики
-РЕШЕНИЯ: только вопросы, которые должен решить мастер или пользователь
-НАХОДКИ: SEVERITY файл:строка — суть — как проверить
-СЛЕДУЮЩИЙ ШАГ: одно конкретное действие или «нет»
+GOAL: one verifiable goal
+BOUNDARIES: allowed and forbidden work
+READ FIRST: paths to contracts and examples
+CHECKS: commands this agent should run
+REPORT: path, only when the result will be reused
 ```

-Пустые разделы пропускаются. Сырой вывод и ход рассуждений не включаются.
-При файловом канале этот договор заполняется в файле, а финальное сообщение
-содержит только `ИТОГ`, счётчики и `АРТЕФАКТ: абсолютный путь`. При
-`read-only` договор возвращается один раз сообщением без поля `АРТЕФАКТ`.
+Добавь общий результат и язык временного обмена:

-## Исполнитель
-
-Файл задачи должен содержать:
-
-```text
-ЦЕЛЬ: одна проверяемая цель
-КРИТЕРИИ: исчерпывающий список
-ГРАНИЦЫ: разрешённые и запрещённые изменения
-СНАЧАЛА ПРОЧИТАТЬ: пути к контрактам и образцам
-ПРОВЕРКИ: узкие команды разработки
-ОТЧЁТ: отдельный путь в обменном каталоге
+```bash
+cat "$D/params.md" "$P/result-contract.md" "$P/runtime-language.md" \
+    > "$D/prompt.md"
 ```

-Короткий вызов: прочитать файл задачи и выполнить буквально. Агент с записью
-в обменный каталог сохраняет полный отчёт по заданному пути и финальным
-сообщением возвращает состояние, счётчики и путь. `read-only`-агент
-возвращает короткий результат один раз сообщением. Коммит не делать.
+Самодостаточный файл задачи, критерии и подробное обязательное чтение добавляй
+только когда они действительно нужны выбранной работе.

-## Слепое ревью
+## Свежий ревьюер

-Один канонический файл на всех ревьюеров:
+Общая часть содержит задачу, изменённый объём и известные проверки. Фокус
+содержит только выбранный для этого ревью класс риска. Для одного ревьюера:

-```text
-АРТЕФАКТ: задача и изменённый объём
-ФОКУС: корректность, контракт, краевые случаи, честность тестов
-МАНДАТ: исследовать и проверять гипотезы, исходники не исправлять
-ФОРМАТ: severity, файл:строка, сценарий сбоя, доказательство, проверка
-ВЕРДИКТ: APPROVED | REVISE
+```bash
+cat "$D/review-common.md" "$D/review-focus.md" \
+    "$P/review-boilerplate.md" "$P/runtime-language.md" \
+    > "$D/review-prompt.md"
 ```

-Вызов каждого ревьюера добавляет только его фокус и канал результата:
-
- `workspace-write`: уникальный путь файла; финальное сообщение — вердикт,
-  счётчики по severity и путь; исходники не менять, Git сверить до и после;
- `read-only`: короткий индекс один раз финальным сообщением, без требования
-  записать файл.
+Если осознанно выбраны несколько линий, каждому ревьюеру дай отдельный файл
+фокуса и отдельный путь результата. Не создавай вторую линию только ради
+симметрии или свежего треда того же семейства.

 ## Закрытие находок

-Исполнителю передаются пути к исходным индексам ревью и такой короткий
-мандат:
+Передай исполнителю исходные индексы без пересказа. Обязательный
+`triage-params.md` задаёт путь полного отчёта и нужные проверки. `notes.md`
+добавляй только для новых решений мастера, которых у исполнителя ещё нет:

-```text
-По каждой находке: исправить, сузить или отклонить через контракт и проверку.
-Не менять соседний объём. Полный отчёт решений записать по указанному пути.
-Финальным сообщением вернуть счётчики, проверки и путь.
+```bash
+cat "$P/triage-header.md" "$D/triage-params.md" "$D/review-a.md" \
+    > "$D/fix-prompt.md"
+if [ -f "$D/review-b.md" ]; then
+  cat "$D/review-b.md" >> "$D/fix-prompt.md"
+fi
+if [ -f "$D/notes.md" ]; then
+  cat "$D/notes.md" >> "$D/fix-prompt.md"
+fi
+cat "$P/runtime-language.md" >> "$D/fix-prompt.md"
 ```

-Не переписывай находки в сообщение или новый файл: исходные индексы уже
-являются неизменяемым входом.
-
 ## Узкая перепроверка

-Прежнему ревьюеру передаются путь к его исходному индексу и путь к отчёту
-решений исполнителя:
+Используй прежний тред ревьюера. Параметры содержат пути к его исходному
+индексу и отчёту решений, а также проверку, если она нужна:

-```text
-Проверь только прежние находки и новые правки рядом с ними.
-По каждой: CLOSED | NOT_CLOSED | REJECTION_VALID | REJECTION_INVALID.
-Полный повторный обход не выполнять.
+```bash
+cat "$P/recheck-header.md" "$D/recheck-params.md" \
+    "$P/runtime-language.md" > "$D/recheck-prompt.md"
 ```

-Финальное сообщение: `ALL_CLOSED` или `ISSUES_REMAIN`, счётчики и путь к
-файлу перепроверки.
+Не запускай перепроверку автоматически: она нужна для принятых исправлений,
+спорного отклонения или дорогой ошибки, а не для закрытия ритуального этапа.
@@ -0,0 +1,14 @@
+# Narrow re-check
+
+Re-check only your original findings and the changes immediately adjacent to
+their resolution. Do not perform a full review.
+
+For every original finding report `CLOSED`, `NOT_CLOSED`, `REJECTION_VALID`,
+or `REJECTION_INVALID`, with concise evidence. If this narrow work exposes a
+new adjacent defect, report it in the normal findings format; the scope bound
+limits exploration, not honest reporting.
+
+Return the full re-check through the channel named by the caller. For a file
+channel, write it to the supplied path and return only
+`RECHECK: ALL_CLOSED | ISSUES_REMAIN`, counters, and `REPORT: <absolute path>`.
+For a message channel, return the concise finding statuses once.
@@ -0,0 +1,14 @@
+## Result contract
+
+Write the full result through the channel chosen by the caller:
+
+- `STATUS: complete | questions | blocked`
+- `EVIDENCE:` changed files, executed commands, and final counters
+- `DECISIONS:` only questions for the orchestrator or user
+- `FINDINGS:` severity, location, essence, and verification method
+- `NEXT:` one concrete action or `none`
+
+Omit empty sections. Do not include raw output or a reasoning narrative. For a
+file channel, put the full result in the named file and return only status,
+counters, and `REPORT: <absolute path>`. For a message channel, return one
+concise result without a report path.
@@ -0,0 +1,21 @@
+## Mandate
+
+- Review and test hypotheses; do not edit source files or persistent
+  environment state.
+- Use the working permissions needed for checks, caches, temporary artifacts,
+  documentation and primary-source research. The caller verifies Git before
+  and after the review.
+- Do not run `git add`, `git commit`, or commands that discard changes.
+- Report only the findings index and verdict through the channel named by the
+  caller.
+
+## Findings index
+
+For each finding:
+
+`SEVERITY(BLOCKER|MAJOR|MINOR|NIT) | file:line or task section | failure scenario | evidence | how to verify`
+
+If there are no findings, list the reviewed scope and every executed check or
+tested hypothesis with its outcome. A bare no-findings assertion is invalid.
+
+Final line: `VERDICT: APPROVED | APPROVED_WITH_MINORS | CHANGES_REQUIRED`
@@ -0,0 +1,4 @@
+## Runtime language
+
+Write every runtime prompt result, report, findings index, and exchange file in
+English. Do not infer the output language from the repository or conversation.
@@ -0,0 +1,15 @@
+# Triage blind-review findings
+
+The review indexes below are immutable input. Process every finding and change
+nothing outside their scope. For each finding, either:
+
+- fix it and name the contract or check that proves closure; or
+- reject it with evidence from the contract and a check, never a bare claim.
+
+Do not commit or stage changes. Propose accepted rejections and residual risks
+for the orchestrator to own and record as durable task decisions. The
+orchestrator cannot silently accept risk; authority must come from the user or
+already be explicit in the task.
+
+Write a full resolution report to the path supplied by the caller. Return only
+status, counters, executed checks, and that path in the final message.
@@ -1,7 +1,9 @@
 # Уровни и роли

 Читай этот файл только при настройке ролей или когда нужная роль недоступна.
-Сам конвейер описан в `SKILL.md`.
+[Основная оптика](../SKILL.md) описывает, когда отдельный агент вообще нужен.
+Этот файл — условные настройки мандата, а не список обязательных участников.
+Один агент может совмещать совместимую работу; не создавай тред на каждое имя.

 - [Возможности хоста](#возможности-хоста)
 - [Выбор уровня](#выбор-уровня)
@@ -28,7 +30,8 @@
  конфигурации агента.

 Если способ выбора роли не виден в доступном инструменте, считай стоимость
-неуправляемой и отметь это в итоговом отчёте.
+неуправляемой, отметь это в итоговом отчёте и не разделяй совместимую работу
+на дополнительные роли без явной пользы.

 Вызов TOML-роли:

@@ -86,7 +89,7 @@
 Конкретные названия моделей держи в конфигурации агентов, а не в `SKILL.md`.
 Так замена модельной линейки не меняет процесс.

-## Роли
+## Возможные мандаты

 ### `fast-worker`

@@ -128,13 +131,12 @@
 корректности, безопасности, контракта и тестов. Каждая находка содержит
 сценарий сбоя, доказательство, влияние и способ проверки.

-Для чистого чтения: `sandbox_mode = "read-only"`. Если ревью требует запуска
-инструментов, которые пишут кэш или артефакты, использовать
-`workspace-write`, запретить правки исходников мандатом и сверить Git до и
-после. Доступ к сети проверять отдельно: право записи не гарантирует поиск и
-доступ к документации. Непроверенную внешнюю механику отмечать как гипотезу.
-Для длинного или повторно используемого индекса нужен доступ на запись в
-обменный каталог; иначе вернуть короткий индекс один раз сообщением.
+Для полноценного ревью обычно нужен `sandbox_mode = "workspace-write"`: тесты,
+кэши, временные артефакты и исследование не следует урезать ради запрета
+правок. Исходники и постоянное окружение защищает явный мандат, Git сверяется
+до и после. Доступ к сети проверять отдельно: право записи не гарантирует
+поиск и документацию. Непроверенную внешнюю механику отмечать как гипотезу.
+Канал результата от песочницы не зависит.

 ### `verifier`

@@ -168,6 +170,8 @@ developer_instructions = """

 - Держи глубину `1`: субагенты не создают собственное дерево исполнителей.
 - Оставляй один слот мастеру.
- Параллельно запускай чтение, независимые исследования и слепые ревью.
+- Параллельно запускай только работу без конфликтующих входов, команд и
+  изменяемого состояния. Второй слепой обзор добавляй ради отдельной линии, а
+  не ради заполнения свободного слота.
 - Реализацию и починку одного рабочего дерева выполняй последовательно одним
  владельцем.