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: цена пропущенной находки — дефект в проде, и она не оставляет следа ни в отчёте, ни в границах покрытия.

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

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

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

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

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

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