dev-skills/av-dev-code/skills/review/references/promote.md

Промоут: находка → конвенция → правило → удаление

Механизм храповика. Без него конвейер выдаёт одни и те же находки бесконечно, а конвенции не растут — то есть внимание тратится повторно на уже решённое.

Роли уровней:

• generative-проходы — механизм открытия неявного (дорого, шумно, но только они достают то, чего нет в списках);
• конвенции — дешёвая регрессионная сетка на уже открытое;
• правила линтера — то же с детерминированным оракулом и нулевой ценой внимания.

flowchart TD
    f["находка ревью"]
    cond{"принята и не специфична<br/>для одного места?"}
    no["промоуту не подлежит:<br/>место одно — комментарий в коде;<br/>вкусовщина — вон на триаже;<br/>нужен рантайм — в журнал ревью"]
    conv["конвенция:<br/>проверяемое свойство + какой проход нашёл"]
    rule["правило линтера, запретитель,<br/>тест-сканер или анализатор"]
    clean["шаг 3: формулировка удалена из конвенций,<br/>строка — в перечень механизированного"]

    f --> cond
    cond -->|нет| no
    cond -->|да| conv
    conv --> rule
    rule --> clean
    rule -->|"ложных чаще, чем ловит (~треть)"| conv

Ребро назад — обратное движение (внизу): правило, дающее ложные срабатывания чаще, чем ловит, снимается в прозу. Ребро rule → clean обязательное: без него первые два шага не окупаются, а именно его и пропускают.

Схема — сводка: условия каждого шага в его разделе, и при расхождении прав текст.

Шаг 1. Находка → конвенция

Условия: находка принята при ревью (не отвергнута, не понижена в гипотезу) и не специфична для одного места.

• Формулируется как проверяемое свойство, а не как совет: «уровень доменного отказа выбирает единственный логирующий чекпоинт», а не «внимательнее с уровнями логов».
• Записывается источник — какой проход нашёл. Это единственные данные для калибровки: проход, чьи находки регулярно доезжают до конвенции, оправдан; проход, чьи находки не доезжают никогда, — кандидат на drop (см. calibration.md).
• Место записи — конвенции проекта, файл или нужный файл каталога (путь — в каталог docs/conventions/). Если тема относится к поведению системы, а не к тому, как мы пишем код, — это не конвенция, а требование: заводится дельта-спека обычным путём.

Промоут идёт тем же путём, что change → spec: правка попадает в тот же коммит, что и исправление кода, с пометкой в сообщении — история промоутов остаётся видна в git log по файлу конвенций.

Шаг 2. Конвенция → правило

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

1. готовое правило существующего линтера — включить в конфиг;
2. запрет идентификатора или импорта правилом-«запретителем» с собственным паттерном;
3. правило с настройкой формы — когда важно не имя, а конструкция;
4. тест-сканер исходников — когда правило про структуру проекта или про схему: направление зависимостей, форма миграций, матчинг ошибки по тексту, бизнес-логика в транспорте;
5. собственный анализатор — последний рубеж, заводим только если 1–4 не выражают правило.

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

Шаг 3. Удаление из конвенций и из промптов

Шаг, который пропускают чаще всего, и единственный, ради которого затевались первые два.

Как только правило работает:

• из файла конвенций убирается формулировка правила; остаётся, если нужно, одна строка «проверяется линтером <имя>» — но только там, где без неё раздел теряет связность;
• правило переезжает в перечень механизированного в доме конвенций (docs/conventions/README.md у каталога, отдельный раздел docs/conventions.md у файла) — со ссылкой на место механизации: конфиг линтера, собственный анализатор, тест-сканер исходников. Не названное место означает, что проход будет добросовестно проверять уже проверенное;
• из контекста инструмента спек убирается дубль, если он там был.

Charter'ы проходов при этом не правятся: они общие и живут в плагине, а предмет проверки приходит из документов проекта. Именно поэтому шаг 3 дешевле, чем был: вычеркнуть строку в одном файле проекта, а не в девяти промптах.

Практический критерий: в прозаических конвенциях остаётся только то, что принципиально не выражается правилом. Файл конвенций на несколько сотен строк размазывает внимание модели по тривиальному — она добросовестно проверит именование полей лога и не дойдёт до формы решения. Каждая строка конвенций, которую можно было бы проверить машиной, оплачивается дефектом, который не поймали где-то ещё.

Обратное движение

Правило, которое даёт ложные срабатывания чаще, чем ловит (порядка трети от общего числа), снимается и возвращается в прозу — или удаляется совсем, если свойство перестало быть важным. Снятие фиксируется там же, где включалось, с одной строкой «почему».

Что промоуту не подлежит

• Находка, специфичная для одного места (её лечит комментарий в коде).
• Вкусовщина: не меняет поведения, не влияет на стоимость следующего изменения, не нарушает записанного. Такое выбрасывается на триаже и не хранится.
• Свойство, требующее знания рантайма (профиль нагрузки, история инцидентов) — его нельзя проверить ни промптом, ни линтером; место такому — в журнале ревью как «признано неавтоматизируемым» (см. review-journal.md).