dev-skills/decisions/36-review-topics-project-docs.md

# 36. Темы ревью: документ проекта стал направлением проверки (2026-08-06)

Замечено при сверке документов канона с составом ступеней: **три документа
остались без читателя ниже `wide`** — `security.md`, `database.md` и `adr/`.
Проект поддерживал их, а на 90% задач их не открывал никто. Причина оказалась не
в переезде проходов, а в том, как описан состав прогона.

**Р148. Тема первична, проход вторичен, и это правило 0 конвейера.** Список тем
нигде не был записан: он существовал побочным продуктом списка проходов. Проход
уезжал в верхнюю ступень — и тема уезжала с ним **беззвучно**: отчёт честно
говорил «`ops` не запускался» и не говорил «эксплуатацию не смотрел никто», а
нужно второе. Теперь прогон описывается таблицей «тема → дом → глубина → кто
закрывает», и таблица есть в каждом отчёте.

**Р149. Тема есть документ, и список тем открытый.** Всё, что проект кладёт в
`docs/`, становится темой ревью; запретить нельзя, разрешения не надо. Не темы
ровно две: `docs/tasks/` и `docs/review.*` (настройка самого конвейера — слой
над темами). Отсюда главное следствие: **`docs/` перестал быть документацией и
стал конфигурацией конвейера.** Проект настраивает проверку тем, что пишет о
себе, а не отдельным файлом настроек, который разошёлся бы с документами.

Ядро — шесть тем: `requirements`, `autotests`, `conventions`, `architecture`,
`security`, `operations`. Их дома канон обещает. Всё сверх — темы проекта, и их
разбирает `basics`: именных проходов конечное число, а тем столько, сколько
заведёт проект, поэтому приёмник обязателен.

**Р150. Тема живёт файлом или каталогом, на выбор проекта.** `docs/security.md`
и `docs/security/` — одно и то же. Прежде форма была задана поимённо
(`conventions`, `research`, `adr` — каталоги, остальные — файлы), и обосновать
это было нечем; заодно в TODO висел открытый вопрос «а если `architecture.md`
разрастётся». Теперь ответ механический: разросся — стал каталогом с
`README.md`, и это не смена версии канона. Обе формы сразу — ошибка, и `docs.py`
её ловит: два дома для одного факта расходятся молча.

**Р151. Ступень выбирает разметчик, а не автор.** Заведён `review-scope`
(`sonnet`), стадия 0, до гейта: находит документы, выводит темы, назначает
глубины, выбирает ступень с обоснованием. Довод сильнее, чем синхронизация
документов: **до сих пор профиль называл тот же оркестратор, который написал
код** — то есть в точке выбора глубины проверки разведённости с автором не было
вовсе, и решала она под давлением «я почти закончил». Вызывающий пайплайн
профиль больше не передаёт.

Право у разметчика симметричное — поднять и понизить, — но обоснование
обязательно всегда, а не только при отступлении от умолчания.

**Р152. Разметчик передаёт адреса, а не пересказ.** Проект однажды уже держал
файл-посредник между документами и проходами (`review-brief.md`) и убрал его:
второй дом расходится с первым и выглядит актуальным. Пересказ в задании — тот
же посредник, живущий один прогон. Исключение одно: **отсутствие дома** — этого
проход сам дёшево не выяснит.

`sonnet` ему хватает потому, что вывод устроен как **список**: каждый файл в
`docs/` обязан попасть в план темой или строкой «не тема, потому что», и план
сверяется с `ls docs/` за секунду. Выбор ступени — суждение, но у него три
независимых корректора: отрицательный тест `quick`, правило «спорный случай
вниз» и сигнал `basics` о заниженной ступени.

**Р153. `quick` и `standard` совпали составом и разошлись глубиной.** Требование
«нижние ступени закрывают все темы, просто не так глубоко» иначе не выполняется:
темы одни и те же, а различать ступени больше нечем. Глубин три и они про способ
доказательства, а не про старательность: **сверка** (открыть дом, открыть дифф,
сравнить), **разбор** (построить сценарий рассуждением), **доказательство**
(прогнать, померить, построить путь). Третья есть только в `wide` — она одна и
требует машины.

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

**Р154. `review-code` переписан: технический разбор плюс конвенции.** Обнаружено
по ходу: **никто не читал код как код.** `specs` сверял с требованиями, `basics`
— с отказами окружения, `architecture` — с устройством, а `code` был проходом
только по прозаическим конвенциям и прямо объявлял, что дефекты рантайма и
логики не его. «Здесь ошибка в логике» не говорил никто, и это была самая
крупная дыра конвейера — крупнее любой недосмотренной темы.

Теперь у прохода две половины: девять классов технического дефекта
(необработанная ветка отказа, пустое и нулевое, граница диапазона, перепутанный
операнд, неосвобождённый ресурс, изменение под итерацией, неверно применённый
интерфейс библиотеки, недостижимая ветка, «сделано соседнее») и прежняя сверка с
конвенциями. Модель поднята до `opus` по признаку [темы
35](35-model-revision.md): цена **пропущенной** находки — дефект в проде, и она
не оставляет следа ни в отчёте, ни в границах покрытия.

**Р155. Вопросы проекта переадресованы темам.** В `docs/review.*` было «Вопросы
к проходам» в форме `ops: <вопрос>` — и когда `ops` уехал в `wide`, вопрос
перестал задаваться молча. Стало «Вопросы по темам». Туда же «Недоступно
проверке» — по темам, обоими подразделами.

## Что из этого следует

**С137. Состав, описанный исполнителями, теряет предмет при перестановке
исполнителей.** Список проходов отвечает «кто работал», а нужен ответ «что
проверено». Первое выглядит полным ровно тогда, когда второе неверно.

**С138. Открытый список нуждается в приёмнике, иначе он обещание.** Разрешить
проекту завести свою тему и не назначить, кто её разбирает, — то же, что не
разрешать.

**С139. Регулятор глубины проверки нельзя оставлять в руках автора.** Не потому
что он злонамерен, а потому что давление «я почти закончил» действует всегда и в
одну сторону.

**С140. Дыру в покрытии находят не там, где ищут находки.** Три осиротевших
документа нашлись сверкой канона с составом ступеней, а отсутствие технического
ревью кода — сверкой оптик проходов между собой. Ни то ни другое не всплыло бы
на прогоне: прогон честно сообщал, что все запущенные проходы отработали.