orchestrator/docs/work-items/ORCH-077/01-brd.md

# 01 — BRD (бизнес-требования): ORCH-077 — ORCH-52d: оптимизация 6 системных промптов по Anthropic

Work Item: **ORCH-077** · Repo: **orchestrator** (self-hosting) · Стадия: analysis

## 1. Бизнес-контекст и проблема

Эпик **ORCH-52** строит сквозной контракт документации конвейера тремя слоями:

- **52b (ORCH-075)** — описательный стандарт документов: `docs/_standards/PIPELINE_DOCS.md`
  (карта «стадия → агент → документ → гейт → machine-key») + копируемые скелеты в
  `docs/_templates/`.
- **52c (ORCH-076)** — машинный контракт: единый `src/frontmatter.py` (reader + writer +
  валидатор `validate_schema`/`REQUIRED_FIELDS`) и спека `docs/_standards/HANDOFF_PROTOCOL.md`
  с **обязательной frontmatter-схемой** (`work_item`, `stage`, `author_agent`, `status`,
  `created_at`, `model_used`).
- **52d (эта задача, ORCH-077)** — слой промптов: замыкающее звено.

**Боль 1 (разрыв цепочки 52b→52c→52d).** 52c заложила writer и валидатор обязательной схемы,
но работает в режиме **обратной совместимости** (`frontmatter_validation_strict=False`,
warning-only) — агенты **физически не проставляют** эти поля в своих выходных документах. Пока
6 системных промптов не научены эмитить схему, петля 52 не замкнута: writer есть, валидатор
есть, а данных на входе нет.

**Боль 2 (форма промптов).** 6 системных промптов агентов (`.openclaw/agents/*.md`) написаны
в свободной разнородной форме (часть по-русски, deployer — по-английски), без единой структуры.
Это снижает предсказуемость поведения агентов прода и затрудняет сопровождение. Канон Anthropic
по построению системных промптов (XML-разметка секций, few-shot с эталонами, явное место для
рассуждения, позитивные примеры рядом с запретами, литеральный scope) даёт измеримо более
стабильный выход.

**Установленные факты (проверено в репозитории):**

- Промпты в `.openclaw/agents/`: `analyst.md`, `architect.md`, `developer.md`, `reviewer.md`,
  `tester.md`, `deployer.md` — все 6 в объёме.
- Модель/эффорт каждого агента резолвятся ТОЛЬКО из config (`resolve_agent_model` /
  `resolve_agent_effort`, ORCH-41); frontmatter `model:` удалён как мёртвый (ORCH-074, тест
  `tests/test_agent_frontmatter_no_model.py`). Все 6 ролей сейчас на `claude-opus-4-8`.
- Обязательная схема: `src/frontmatter.py::REQUIRED_FIELDS =
  ("work_item", "stage", "author_agent", "status", "created_at", "model_used")`.
- Machine-verdict ключи (регистрозависимы, читаются гейтами ТОЛЬКО из frontmatter):
  `verdict:` (12-review.md), `result:`/`verdict:`/`status:` (13-test-report.md),
  `staging_status:` (15-staging-log.md), `deploy_status:` (14-deploy-log.md),
  `security_status:` (17-security-report.md).

## 2. Объём (scope)

### В объёме

- Переписать **все 6** промптов `.openclaw/agents/*.md` в едином каноне Anthropic с
  XML-структурой секций: `<context>` / `<task>` / `<deliverables>` / `<constraints>` /
  `<output_format>` (допустимы дополнительные семантические секции, напр. `<thinking>`-подсказка).
- Добавить в каждый промпт **явную инструкцию эмитить обязательную frontmatter-схему 52c**
  (`work_item` / `stage` / `author_agent` / `status` / `created_at` / `model_used`) в тех
  выходных документах, которые роль авторствует, с конкретными для роли значениями
  (`author_agent` = роль, `stage` = стадия роли, `model_used` = резолв ORCH-41).
- Few-shot: ссылки на скелеты 52b (`docs/_templates/`) и эталонные work item (ORCH-073 / ORCH-088)
  как примеры заполнения; позитивные примеры рядом с запретами («делай Y вместо X»).
- Явное место для рассуждения (CoT/thinking) там, где это уместно для роли.
- Чёткие success-criteria артефакта стадии (что считается готовым выходом).
- Обновить документацию: `CLAUDE.md`, `docs/architecture/README.md`, ADR (per-work-item +
  при необходимости сквозной), `CHANGELOG.md`.

### Вне объёма

- **Любая правка кода**: `src/config.py`, `src/agents/launcher.py`, `resolve_agent_model` /
  `resolve_agent_effort`, `src/frontmatter.py` (сделана в 52c), `src/stages.py`,
  `src/qg/checks.py`, `src/stage_engine.py`.
- **Включение жёсткой валидации** схемы (`frontmatter_validation_strict`) — остаётся `False`
  (warning-only). 52d учит промпты эмитить схему добровольно; enforcement не включается.
- Изменение состава/семантики Quality Gates, `STAGE_TRANSITIONS`, набора machine-verdict ключей.
- Model-routing / смена моделей ролей (вне эпика).
- Изменение `tools:`-блока (разрешённые инструменты) в frontmatter промптов.

## 3. Заинтересованные стороны

- **Заказчик / Owner (Слава)** — принимает результат; ручной BRD-гейт.
- **Потребитель прямой** — 6 агентов прода, которые исполняют эти промпты на КАЖДОЙ задаче ВСЕХ
  проектов (orchestrator + enduro-trails) из общего инстанса.
- **Косвенно затронуты** — все будущие work item (качество артефактов конвейера) и петля 52
  (наполнение frontmatter-схемы реальными данными).

## 4. Бизнес-требования (BR)

- **BR-1** — Все 6 промптов (`.openclaw/agents/*.md`) переписаны единым XML-стилем секций
  (`<context>` / `<task>` / `<deliverables>` / `<constraints>` / `<output_format>`).
- **BR-2** — Каждый промпт **явно инструктирует** агента проставлять обязательную
  frontmatter-схему 52c (все 6 полей) в выходных документах, которые роль авторствует, с
  конкретными для роли значениями.
- **BR-3** — Few-shot: каждый промпт ссылается на скелеты 52b (`docs/_templates/`) и эталоны
  (ORCH-073 / ORCH-088); запреты сопровождаются позитивным примером («делай Y вместо X»).
- **BR-4 (АНТИ-РЕГРЕСС, критично для self-hosting)** — НИ ОДНА функциональная инструкция
  старого промпта не потеряна: гейты, machine-verdict ключи и их регистр, маркеры `ORCH-NNN`,
  правила `CLAUDE.md`, ролевые запреты, идемпотентный merge-guard, canonical staging-команда
  (`docker exec`), self-hosting-запреты. Агенты продолжают проходить свои гейты.
- **BR-5** — Код НЕ изменён: правятся только `.openclaw/agents/*.md` + документация;
  `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` нетронуты.
- **BR-6** — Проведена A/B-проверка минимум на одной репрезентативной стадии (старый vs новый
  промпт): новый промпт НЕ хуже по числу циклов `REQUEST_CHANGES` / качеству артефакта.
- **BR-7** — Документация (`CLAUDE.md` / `README` / ADR / `CHANGELOG`) обновлена в том же PR.

## 5. Нефункциональные требования (NFR)

- **NFR-1 (обратная совместимость гейтов)** — Новые промпты эмитят схему **аддитивно**: рядом с
  существующими machine-verdict ключами, не меняя их имени/регистра/позиции. Гейты читают вердикты
  ровно как раньше (схема при `strict=False` в вердикте не участвует).
- **NFR-2 (безопасность прода)** — Промпт = поведение агента прода для ВСЕХ проектов. Рефактор
  формы не должен ослабить ни одну рабочую инструкцию (особенно self-hosting-запреты deployer'а:
  «не рестартить 8500 изнутри», merge-guard).
- **NFR-3 (валидность frontmatter промпта)** — YAML-frontmatter каждого `.openclaw/agents/*.md`
  остаётся валидным YAML, сохраняет `name`/`description`, НЕ возвращает удалённый `model:`
  (тест `test_agent_frontmatter_no_model.py` остаётся зелёным).
- **NFR-4 (читабельность/сопровождаемость)** — Единый канон облегчает будущие правки; объём
  каждого промпта остаётся соразмерным (без раздувания «воды»).
- **NFR-5 (обратимость)** — Изменение чисто текстовое; откат = git revert PR, без миграций
  состояния/БД.

## 6. Допущения и ограничения

- **Допущение 1** — `model_used` для всех 6 ролей сейчас = `claude-opus-4-8` (README §«Модель и
  эффорт по ролям»); промпт инструктирует ставить именно эту модель как резолв ORCH-41. Если
  model-routing включат позже — значение пересматривается, но это вне ORCH-077.
- **Допущение 2** — `created_at` агент берёт как текущую дату (`YYYY-MM-DD`); источник —
  доступный агенту способ (напр. `date +%F` через Bash там, где Bash в `tools:`).
- **Ограничение 1** — `tools:`-блок и разрешённые пути записи каждого промпта НЕ расширяются:
  агент эмитит схему только в те документы, которые и так авторствует.
- **Ограничение 2** — Developer не авторствует номерного handoff-вердикт-документа (его выход —
  код + PR, гейт `check_ci_green`); для него инструкция схемы применяется к when-applicable
  докам (`07`/`08`/`10`), если он их трогает, а основной акцент — на сохранении dev-инструкций.
- **Ограничение 3** — `frontmatter_validation_strict` остаётся `False`; ORCH-077 НЕ включает
  hard-fail (это была бы правка config = вне scope).

## 7. Критерии успеха

Резюме: 6 промптов переписаны по канону Anthropic, эмитят схему 52c, не потеряли ни одной
функциональной инструкции, код не тронут, документация обновлена, A/B подтверждает «не хуже».
Детальные PASS/FAIL — `03-acceptance-criteria.md`.

## 8. Риски

Краткий перечень (детали — `10-tech-risks.md`, заполняет архитектор):

- **R-1 (регресс поведения агента)** — при рефакторе формы потерять рабочую инструкцию →
  агент ломает выход для ВСЕХ проектов. Митигация: построчная карта «старая инструкция → где в
  новом промпте» (AC-4), A/B-прогон.
- **R-2 (ложный гейт-провал)** — случайно изменить регистр/имя machine-verdict ключа или
  сместить его так, что парсер не найдёт. Митигация: явный инвентарь ключей, структурные тесты.
- **R-3 (некорректный `model_used`)** — захардкодить неверную модель. Митигация: ссылка на
  резолв ORCH-41 и таблицу README.
- **R-4 (раздувание промпта)** — XML-канон + few-shot увеличат объём и «утопят» ключевые
  запреты. Митигация: ссылки на эталоны вместо инлайна, контроль объёма.