87 lines
5.8 KiB
Markdown
87 lines
5.8 KiB
Markdown
# BRD — ORCH-046: pass reviewer/tester findings text to developer (not just link)
|
||
|
||
Work Item ID: ORCH-046
|
||
Stage: analysis
|
||
Author: analyst
|
||
Date: 2026-06-06
|
||
|
||
## 1. Контекст и проблема
|
||
|
||
Оркестратор при заворотах задачи деву (откат на `development`) формирует
|
||
описание задачи (`task_desc`), которое попадает в `.task-dev.md` запускаемого
|
||
агента-разработчика. Сейчас в двух ветках отката этот текст содержит **только
|
||
ссылку на файл-артефакт**, без сути замечаний:
|
||
|
||
- **Reviewer → REQUEST_CHANGES** (`src/stage_engine.py`, ветка
|
||
`_handle_qg_failure_rollbacks`, ~стр. 419): `task_desc` =
|
||
`"…Fix findings in docs/work-items/<id>/12-review.md"`.
|
||
- **Tester → FAIL** (`check_tests_passed`, ~стр. 455): `task_desc` =
|
||
`"…Fix failures described in docs/work-items/<id>/13-test-report.md"`.
|
||
|
||
В результате developer-агент получает инструкцию «иди читай файл». Ключевые
|
||
претензии (P0/P1 у ревьюера, причина падения у тестера) часто проскакивают —
|
||
агент не открывает файл целиком или теряет фокус, повторяет ту же ошибку, и
|
||
задача снова заворачивается. Это «испорченный телефон»: расход циклов retry
|
||
(`MAX_DEVELOPER_RETRIES = 3`), деньги на токены, простой конвейера.
|
||
|
||
## 2. Бизнес-цель
|
||
|
||
Убрать «испорченный телефон» между reviewer/tester и developer при заворотах:
|
||
встраивать **дословный текст ключевых замечаний** прямо в `task_desc`, чтобы
|
||
developer-агент видел суть претензий сразу, а не только ссылку.
|
||
|
||
Это снижает число повторных заворотов и расход retry-бюджета на одну задачу.
|
||
|
||
## 3. Объём (вариант A — выбран Славой 06.06)
|
||
|
||
Минимальное, низкорисковое изменение **ядра** (`stage_engine`), которое:
|
||
|
||
1. Извлекает из `12-review.md` блок findings и выносит **must-fix (P0/P1)
|
||
дословно** в `task_desc` при reviewer REQUEST_CHANGES.
|
||
2. Извлекает из `13-test-report.md` причину FAIL (reason из гейта + релевантный
|
||
фрагмент тела отчёта) в `task_desc` при tester FAIL.
|
||
3. Во всех случаях **сохраняет ссылку на полный файл** как дополнительный
|
||
контекст («полный контекст — см. файл»).
|
||
4. Извлечение выполняется новым отдельным хелпером-парсером
|
||
(`src/review_parse.py`), который **никогда не бросает исключение**: при
|
||
отсутствующем/битом файле возвращает пустой результат, и вызывающий код
|
||
делает graceful fallback на прежнюю ссылку-строку.
|
||
|
||
## 4. Что НЕ входит в объём (out of scope)
|
||
|
||
- НЕ трогать гейты `check_*` (в т. ч. ORCH-45 `check_ci_green`,
|
||
ORCH-47 `_parse_tests_verdict`) — они в проде, поведение неизменно.
|
||
- НЕ трогать реестр `QG_CHECKS`.
|
||
- НЕ менять сигнатуры публичных функций (`advance_stage`, `_run_qg`,
|
||
`check_*`).
|
||
- НЕ менять webhook-пути.
|
||
- НЕ менять retry-счётчик (`_developer_retry_count`, `MAX_DEVELOPER_RETRIES`)
|
||
и rollback-логику (последовательность `update_task_stage` →
|
||
`notify_stage_change` → `plane_notify_stage` → enqueue) — поведение
|
||
идентично.
|
||
- НЕ менять формат Plane-комментариев (`build_status_comment`).
|
||
|
||
## 5. Заинтересованные стороны
|
||
|
||
- **Owner (Слава)** — заказчик, выбрал вариант A.
|
||
- **Developer-агенты** — потребители `task_desc`: получают суть замечаний.
|
||
- **Конвейер всех проектов** (self-hosting) — выигрывает за счёт меньшего
|
||
числа заворотов.
|
||
|
||
## 6. Ограничения и риски (self-hosting)
|
||
|
||
- Правка ядра `stage_engine` — компонент крутится в продакшене и обслуживает
|
||
все проекты из общего инстанса/БД/очереди. Любая регрессия в формировании
|
||
`task_desc` или (тем более) исключение в `advance_stage` останавливает
|
||
конвейер всех проектов → **парсер обязан быть полностью graceful**.
|
||
- Обязателен прогон `deploy-staging` (8501) перед прод-деплоем.
|
||
- Это правка ядра → требуется ADR (per-work-item).
|
||
|
||
## 7. Критерий успеха (бизнес)
|
||
|
||
- При заворотах в `.task-dev.md` есть дословный текст ключевых замечаний
|
||
(P0/P1 ревьюера; reason+фрагмент тестера) плюс ссылка на полный файл.
|
||
- Парсер устойчив к битым/отсутствующим артефактам (graceful fallback на
|
||
старую ссылку-строку).
|
||
- Существующие тесты зелёные; поведение retry/rollback не изменилось.
|