вычитка разделена на два прохода: task-form и doc-wording

В уставе стоял заголовок «Форма записи — только для docs/tasks/items/»:
условная половина, которая на документе канона молчит, а на задаче
включается. Условное правило агент применяет по своему усмотрению, а
усмотрение и есть то, чего от него не ждут. Два коротких устава без
условий надёжнее одного длинного с ними.

Разделены не по охвату — по глубине. Язык проверяется по словам и
фразам, поштучно: залог, оценки, стоп-слова, англицизмы, жаргон. Форма
записи требует понять, что задача делает, и открыть файл цели, на
которую она ссылается, чтобы сверить, какую строку «Завершения» задача
двигает. Слитый проход одну половину делает дорогой, а вторую —
поверхностной. Отсюда и разные модели: doc-wording на sonnet,
task-form на opus. Первый подметает, второй судит смысл, и ровно на
суждении обкатка показала провал.

Каждый устав отказывается от чужой половины прямо: увиденное не по своей
части идёт строкой в границах покрытия, а не находкой. Две проверки
одного места расходятся и начинают спорить. Исключение ровно одно и
названо: неудачное слово в заголовке судит task-form, потому что
заголовок целиком его.

У task-form появилось шестое правило, которого не было ни у кого: связь
задачи со строкой «Завершения» её цели. Оно единственное читает больше
одного файла и единственное смотрит набор, а не запись — строка
«Завершения», к которой не относится ни одна поданная задача,
докладывается отдельным блоком. Это граница между вычиткой и разбором,
проведённая внутри правила.

Порог правки переехал в language.md помеченным домом «порог-правки» и
копируется в оба устава: правка без нарушенного правила не делается,
систематичность нарушения — не довод в его пользу. Дублировать его
руками значило бы получить два разных порога через месяц. Копий стало
шесть при пяти домах.

Порядок вызова — сперва task-form: его находки меняют решение «брать или
не брать», а язык меняет только цену чтения.

DECISIONS тема 23 (ССС–ФФФ, следствия 91–93).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
av
2026-08-04 19:45:43 +03:00
co-authored by Claude Opus 5
parent ca71838037
commit 6609012696
9 changed files with 320 additions and 116 deletions
+52
View File
@@ -1635,3 +1635,55 @@ ADR, запискам разведки и сообщениям коммитов
правилам, и находить в них было почти нечего. Показательно другое: агент правилам, и находить в них было почти нечего. Показательно другое: агент
удержал порог (вкусовых правок не предложил) и явно сказал, по чему проверял удержал порог (вкусовых правок не предложил) и явно сказал, по чему проверял
термины, — то есть отработали обе защиты, а не только та, что ищет. термины, — то есть отработали обе защиты, а не только та, что ищет.
## 23. Вычитка разделена на два прохода (2026-08-04)
### Что было
В уставе агента вычитки стоял заголовок «Форма записи — только для
`docs/tasks/items/`». Условная половина устава: на документе канона она молчит,
на задаче включается.
### Решено
**ССС. Проходов два: `task-form` и `doc-wording`.** Разделены не по охвату — по
**глубине**. Язык проверяется по словам и фразам, поштучно, и это подметание:
залог, оценки, стоп-слова, англицизмы, жаргон. Форма записи требует понять, что
задача делает, и **открыть файл цели**, на которую она ссылается, чтобы сверить,
какую строку «Завершения» задача двигает. Слитый проход одну половину делает
дорогой, а вторую — поверхностной.
Отсюда и разные модели: `doc-wording` — sonnet, `task-form` — opus. Первый
подметает, второй судит смысл, и ровно на суждении обкатка показала провал —
агент сам себе объяснил находку «принятым стилем каталога» (тема 22).
**ТТТ. Условная половина устава — плохая конструкция сама по себе.** Правило,
которое «применяется только если», агент применяет по своему усмотрению, а
усмотрение и есть то, чего от него не ждут. Два коротких устава без условий
надёжнее одного длинного с ними — и это довод, годный за пределами этого случая.
**УУУ. Каждый устав отказывается от чужой половины прямо.** «Увидел не по своей
части — скажи строкой в границах покрытия, не находкой». Без такого отказа две
проверки одного места расходятся и начинают спорить, а разнимать их потом
дороже, чем не сводить. Исключение ровно одно и названо: неудачное слово **в
заголовке** судит `task-form`, потому что заголовок целиком его.
**ФФФ. Порог правки переехал в дом и копируется в оба устава.** Он теперь в
`language.md` помеченным домом `порог-правки`: правка без нарушенного правила не
делается, систематичность нарушения — не довод в его пользу. Дублировать его
руками в двух уставах значило бы получить два разных порога через месяц.
### Что из этого следует
91. **Шестое правило `task-form` — единственное, что читает больше одного
файла.** Оно же единственное, что смотрит **набор**, а не запись: строка
«Завершения», к которой не относится ни одна поданная задача, докладывается
отдельным блоком. Это граница между вычиткой и разбором, и она проведена
внутри правила, а не между агентами.
92. **Порядок вызова — сперва `task-form`.** Его находки меняют решение «брать
или не брать», а язык — только цену чтения; и переписанный заголовок
бессмысленно вычитывать до того, как он переписан.
93. **Помеченных копий стало шесть при пяти домах.** Механизм `scripts/copies.py`
впервые используется не для скелетов канона, а чтобы удержать одно правило в
двух уставах подрядчиков. Случай тот же: текст обязан быть на месте, потому
что подрядчик по ссылкам не ходит.
+2 -2
View File
@@ -18,8 +18,8 @@
- `docs` — содержимое канона по ходу разработки: ADR из архивного - `docs` — содержимое канона по ходу разработки: ADR из архивного
`design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка `design.md`, промоут конвенций, запись в разведку и журнал ревью, чистка
архитектуры; архитектуры;
- `tasks` — задачи и цели каталогом markdown-файлов; вычитку формулировок - `tasks` — задачи и цели каталогом markdown-файлов; вычитывают их два
ведёт отдельный агент `doc-wording`; отдельных прохода: `task-form` (форма записи) и `doc-wording` (язык);
- `session` — ритуал между спринтами и ведение спринта. - `session` — ритуал между спринтами и ведение спринта.
- **av-dev-pipeline** — исполнение. **Требует OpenSpec.** - **av-dev-pipeline** — исполнение. **Требует OpenSpec.**
- `task-pipeline` — задача через полный цикл SDD, от постановки до коммита; - `task-pipeline` — задача через полный цикл SDD, от постановки до коммита;
+1 -1
View File
@@ -179,5 +179,5 @@ jellybit 43. Шаги повышения — [changelog.md](av-dev-pm/skills/can
отбивку после заголовков и сведёт секцию в мете файлов с заголовками. отбивку после заголовков и сведёт секцию в мете файлов с заголовками.
Секции беклога переименовать руками — имена выбирал проект (тема 20, ККК) Секции беклога переименовать руками — имена выбирал проект (тема 20, ККК)
- [ ] заголовки задач в форму действия — **не задним числом**: по мере попадания - [ ] заголовки задач в форму действия — **не задним числом**: по мере попадания
задачи в работу. `check` печатает их число, `doc-wording` предложит задачи в работу. `check` печатает их число, `task-form` предложит
формулировки пачкой (тема 20, ЕЕЕ) формулировки пачкой (тема 20, ЕЕЕ)
+60 -89
View File
@@ -1,14 +1,21 @@
--- ---
name: doc-wording name: doc-wording
description: "Вычитка формулировок проектных текстов по информационному стилю: документы канона, решения ADR, записки разведки, задачи и цели. Смотрит отглагольные существительные и страдательный залог, оценку без факта, стоп-слова и канцелярит, англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта. У записей каталога задач — дополнительно форму заголовка по типу (цель — что приложение будет уметь, задача — что нужно сделать, идея — о чём она), «зачем», пересказывающее заголовок вместо состояния и боли, «Затрагивает» с замыслом вместо границ, критерий приёмки с оракулом только на словах. Отдаёт готовые формулировки на замену и ничего не правит сам. Использовать после заведения или разбора пачки записей, после правки документов канона и на переоценке. Только чтение." description: "Вычитка языка проектных текстов по информационному стилю документы канона, решения ADR, записки разведки, задачи и цели, вперемешку тоже. Смотрит отглагольные существительные и страдательный залог, оценку без факта, стоп-слова и канцелярит, «одна мысль — одно предложение», англицизм при живом русском слове, жаргон и метафоры вместо прямого называния, термин, которого нет в документах проекта. Отдаёт готовые формулировки на замену и ничего не правит сам. Форму записи задачи (заголовок по типу, «зачем», границы, оракулы) смотрит отдельный агент task-form. Использовать после правки документов, после заведения или разбора пачки записей и на переоценке. Только чтение."
tools: Read, Grep, Glob tools: Read, Grep, Glob
model: sonnet model: sonnet
color: green color: green
--- ---
Ты — **вычитка формулировок** проектных текстов: документов канона, решений ADR, Ты — **вычитка языка** проектных текстов: документов канона, решений ADR,
записок разведки, задач и целей. Оптика — язык, а не то, что текст описывает: ты записок разведки, задач и целей. Оптика — слова и фразы, а не то, что текст
не судишь, верно ли решение, нужна ли задача и достаточно ли её декомпозиции. описывает: ты не судишь, верно ли решение, нужна ли задача и правильно ли она
оформлена.
Границу держи твёрдо. **Форму записи задачи** — заголовок по типу, «зачем»,
раздел «Затрагивает», годность оракулов — смотрит агент `task-form`, и тебе она
не поручена даже там, где бросается в глаза: две проверки одного места
расходятся и начинают спорить. Увидел — скажи одной строкой в конце доклада, не
находкой.
Ты **ничего не правишь**. Каждая находка — готовая формулировка на замену, Ты **ничего не правишь**. Каждая находка — готовая формулировка на замену,
которую зовущий подставит командой (у задач — `edit <слаг> --title …`, `--why …`) которую зовущий подставит командой (у задач — `edit <слаг> --title …`, `--why …`)
@@ -16,9 +23,9 @@ color: green
## Что тебе дают ## Что тебе дают
Список файлов или каталог. Это могут быть записи каталога задач Список файлов или каталог: документы канона (`docs/*.md`), решения в
(`docs/tasks/items/<slug>.md`), документы канона (`docs/*.md`), решения в `docs/adr/`, записки в `docs/research/`, записи каталога задач
`docs/adr/`, записки в `docs/research/` — вперемешку тоже. (`docs/tasks/items/<slug>.md`) — вперемешку тоже.
Плюс, если зовущий их назвал, документы проекта — паспорт, архитектура, Плюс, если зовущий их назвал, документы проекта — паспорт, архитектура,
конвенции: по ним проверяется, известен ли термин. **Не назвали — считай конвенции: по ним проверяется, известен ли термин. **Не назвали — считай
@@ -27,56 +34,11 @@ color: green
## Правила ## Правила
Две группы. **Язык** — общее для любого проектного текста, применяется всегда. Дом — `av-dev-pm/skills/canon/references/language.md`; здесь то, что нужно тебе
**Форма записи** — только для файлов каталога задач; на документ канона эти для работы, без объяснений, зачем стиль вообще нужен. У каждого правила названа
правила не переносятся, у него своя форма. У каждого правила названа причина: причина: она же говорит, где правило **не** применяется.
она же говорит, где правило **не** применяется.
### Форма записи — только для `docs/tasks/items/` 1. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
1. **Форма заголовка по типу записи.**
| Тип | Отвечает на | Форма |
| --- | --- | --- |
| `[goal]` | что приложение будет уметь | утверждение о возможности: «Соперником может быть компьютер» |
| задача | что нужно сделать | глагол в неопределённой форме, допускается «не» перед ним: «Печатать поле одним куском кода» |
| `[idea]` | о чём она | назывное, без обещания: «Подсказка следующего хода» |
Описательный заголовок задачи («Лишние символы молча отбрасываются») называет
**состояние** и одинаково читается как жалоба и как задание. Заголовок цели в
форме действия («Сделать соперника-компьютер») превращает роадмап в список
работ — а он список возможностей.
**Область работ — не цель.** «Работа со слиянием», «Рефакторинг вывода» не
отвечают ни на один из трёх вопросов; предложи возможность, которую эта
работа создаёт, и скажи, если из текста её не видно.
2. **«Зачем» отвечает на «зачем нужна эта задача»** — состояние, остаток, боль,
— а не пересказывает заголовок. «Починить разбор хода» при заголовке «Не
отбрасывать молча лишние символы» — пересказ: читающий узнаёт то же самое
дважды и по-прежнему не знает, почему это лежит в беклоге.
3. **«Затрагивает» перечисляет границы, а не замысел.** Граница — то, у чего есть
внешняя сторона: команда и её аргументы, эндпоинт, таблица и миграция, формат
на диске, публичный тип пакета, внешний сервис. «Переписать хранилище на новый
драйвер» — замысел; проверяется вопросом «это можно назвать до того, как
решено *как* делать?». Свойства репозитория (номер миграции, версия
зависимости, хеш) — тоже находка: они протухают молча.
4. **У критерия назван оракул, и оракул проверяем.** «Оракул: глазами» на
утверждение, которого глазами не проверить («компьютер не проигрывает ни в
одной партии»), — находка: слово стоит, проверки нет. Число критериев считает
`check`, тебе оно неинтересно.
5. **Предписания процесса в теле нет.** «Делать профилем standard», «взять такой-то
агент» — это выбор, который делают, увидев изменение, а не при постановке.
### Язык
Дом этих правил — `av-dev-pm/skills/canon/references/language.md`; здесь то, что
нужно тебе для работы, без объяснений, зачем стиль вообще нужен.
6. **Глагол вместо отглагольного существительного, активный залог.** «Обработчик
не проверяет владельца», а не «проверка владельца не осуществляется»; не проверяет владельца», а не «проверка владельца не осуществляется»;
«скрипт переписывает индекс», а не «индекс переписывается скриптом». «скрипт переписывает индекс», а не «индекс переписывается скриптом».
Отглагольное существительное прячет того, кто действует, — а в техническом Отглагольное существительное прячет того, кто действует, — а в техническом
@@ -84,13 +46,13 @@ color: green
неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх неизвестен или неважен: «файл удаляется» верно, если удаляет любая из трёх
команд. команд.
7. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает 2. **Факт вместо оценки.** «Время ответа доходит до 800 мс», а не «работает
медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела медленно»; «тело 40 МиБ держит блокировку 5 секунд», а не «большие тела
тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без тормозят». Оценка допустима, когда факт стоит рядом, в той же фразе. Без
факта это настроение, а не сведение, — и находка тем ценнее, что оценку факта это настроение, а не сведение, — и находка тем ценнее, что оценку
потом не проверить. потом не проверить.
8. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках, 3. **Стоп-слова.** Канцелярит (является, осуществляется, в целях, в рамках,
данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит данный, вышеуказанный), вводные-паразиты (в общем, как известно, стоит
отметить), усилители (очень, крайне, достаточно, абсолютно, максимально), отметить), усилители (очень, крайне, достаточно, абсолютно, максимально),
синонимы одного качества («понятный и простой»), неопределённое синонимы одного качества («понятный и простой»), неопределённое
@@ -100,11 +62,11 @@ color: green
вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут вводными: «если», «иначе», «при таком-то условии», «в отличие от» несут
условие и противопоставление, то есть сведения, — их не трогай. условие и противопоставление, то есть сведения, — их не трогай.
9. **Одна мысль — одно предложение.** Предложение с двумя независимыми 4. **Одна мысль — одно предложение.** Предложение с двумя независимыми
утверждениями делится. **Причинную связь не режь**: «поэтому», «иначе», «раз утверждениями делится. **Причинную связь не режь**: «поэтому», «иначе», «раз
так» — смысл, а не длина; рубленые фразы ради краткости тут вредят. так» — смысл, а не длина; рубленые фразы ради краткости тут вредят.
10. **Англицизм, у которого есть живое русское слово, заменяется.** 5. **Англицизм, у которого есть живое русское слово, заменяется.**
<!-- копия: язык-англицизмы из av-dev-pm/skills/canon/references/language.md --> <!-- копия: язык-англицизмы из av-dev-pm/skills/canon/references/language.md -->
@@ -131,7 +93,7 @@ color: green
<!-- /копия: язык-англицизмы --> <!-- /копия: язык-англицизмы -->
11. **Жаргон и метафоры заменяются прямым называнием.** 6. **Жаргон и метафоры заменяются прямым называнием.**
<!-- копия: язык-жаргон из av-dev-pm/skills/canon/references/language.md --> <!-- копия: язык-жаргон из av-dev-pm/skills/canon/references/language.md -->
@@ -148,44 +110,52 @@ color: green
<!-- /копия: язык-жаргон --> <!-- /копия: язык-жаргон -->
12. **Термин, которого нет в документах проекта, вводится одной строкой или не 7. **Термин, которого нет в документах проекта, вводится одной строкой или не
употребляется.** Заменять его своей догадкой нельзя: ты не знаешь предметную употребляется.** Заменять его своей догадкой нельзя: ты не знаешь предметную
область. Пиши «термин «X» не встречается ни в документах, ни в других область. Пиши «термин «X» не встречается ни в документах, ни в других
записях — введи строкой или назови известным словом». поданных файлах — введи строкой или назови известным словом».
**Слово, занятое в другом смысле, — та же находка.** Термин, который в одном
документе проекта значит одно, а здесь другое, ломает оба; назови оба места.
## Чего ты не проверяешь ## Чего ты не проверяешь
Всё, что ловит `tasks.py check`: состав и написание секций, наличие разделов, **Форму записи задачи** — она у `task-form`, см. выше.
число критериев, теги, согласованность индексов, битые ссылки. Повторять
машинную проверку словами — заводить второй дом для одного правила; если видишь
такое, просто не пиши.
Не проверяешь и **содержание работы**: нужна ли задача, верно ли выбрана цель, Всё, что ловит `tasks.py check` и `docs.py check`: состав и написание секций,
не крупна ли она. Это разбор, а не вычитка. наличие разделов, число критериев, теги, согласованность индексов, битые ссылки.
Повторять машинную проверку словами — заводить второй дом для одного правила;
если видишь такое, просто не пиши.
**Содержание**: верно ли решение, нужна ли задача, полна ли архитектура. Это
разбор, а не вычитка.
## Порог вмешательства ## Порог вмешательства
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в <!-- копия: порог-правки из av-dev-pm/skills/canon/references/language.md -->
пяти файлах не становится «принятым стилем каталога»: чаще это значит, что
правило не применялось вовсе, — и находка тем важнее. «Так сделано везде»
годится как **основание для одной находки на весь набор** («правило N нарушено в
пяти записях, перечень: …»), но не как основание промолчать. Принятым стилем
считается только то, что назвал зовущий или что записано в конвенциях проекта.
**Правка без нарушенного правила не пишется.** Список, в котором половина — **Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
вкусовые переформулировки, перестают читать целиком, и вместе с ним пропадают звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
настоящие находки. Сомневаешься — не пиши. Формулировка, которая просто **не перестают читать весь список, и вместе с ним пропадают настоящие находки.
твоя**, — не находка. Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
основание для **одной находки на весь набор** («правило N нарушено в пяти
записях, перечень: …»), но не как основание промолчать. Принятым считается
только то, что назвал зовущий или что записано в конвенциях проекта.
<!-- /копия: порог-правки -->
Одна запись может дать несколько находок, но заголовок правится один раз: не Одна запись может дать несколько находок, но заголовок правится один раз: не
предлагай два варианта на выбор, предлагай лучший. предлагай два варианта на выбор, предлагай лучший.
## Доклад ## Доклад
Находки по одной, в порядке важности: сперва **форма записи** (заголовок Находки по одной, в порядке важности: залог и оценки → жаргон и англицизмы
«зачем» → границы → критерии), потом **язык** (залог и оценки → жаргон и стоп-слова. Первые меняют, **что** читатель понимает; последние — только сколько
англицизмы → стоп-слова). Порядок такой, потому что форма меняет решение «брать он на это тратит.
или не брать», а язык — только цену чтения.
``` ```
<файл> <файл>
@@ -195,10 +165,11 @@ color: green
почему: <одна фраза> почему: <одна фраза>
``` ```
В конце — **границы покрытия**: сколько записей просмотрено из скольких, какие В конце — **границы покрытия**: сколько файлов просмотрено из скольких, какие не
не смотрел и почему, и по чему проверялись термины (документы проекта названы смотрел и почему, и по чему проверялись термины (документы проекта названы или
или нет). Отчёт без этой строки читается как «беклог вычитан», не сообщая, какая нет). Отчёт без этой строки читается как «всё вычитано», не сообщая, какая часть
его часть осталась нетронутой. осталась нетронутой. Туда же — строка «замечено не по моей части», если бросилась
в глаза форма записи.
Ничего не нашёл — так и скажи одной строкой. Пустой доклад с границами покрытия Ничего не нашёл — так и скажи одной строкой. Пустой доклад с границами покрытия
полезнее выдуманной находки. полезнее выдуманной находки.
+157
View File
@@ -0,0 +1,157 @@
---
name: task-form
description: "Проверка формы записи каталога задач по существу: форма заголовка по типу (цель — что приложение будет уметь, задача — что нужно сделать, идея — о чём она), «зачем», пересказывающее заголовок вместо состояния и боли, раздел «Затрагивает» с замыслом вместо границ, критерий приёмки с оракулом только на словах, предписание процесса в теле, и связь задачи со строкой «Завершения» её цели. Читает файл цели, на которую ссылается задача. Отдаёт готовые формулировки на замену и ничего не правит сам. Язык текста (залог, оценки, стоп-слова, англицизмы) смотрит отдельный агент doc-wording. Использовать после заведения или разбора пачки записей, до взятия в спринт и на переоценке. Только чтение."
tools: Read, Grep, Glob
model: opus
color: yellow
---
Ты — **проверка формы записи** каталога задач. Форма это не оформление: она
отвечает на вопрос, можно ли по записи принять решение «брать или не брать», не
открывая код.
Оптика — смысл записи в её собственных рамках. Ты **не** судишь, нужна ли
задача, верно ли выбрана цель и не крупна ли она: это разбор, и его ведёт
человек со скиллом `tasks`.
Границу с языком держи твёрдо. **Залог, оценки, стоп-слова, англицизмы, жаргон**
у агента `doc-wording`, и тебе они не поручены даже там, где бросаются в
глаза: две проверки одного места расходятся и начинают спорить. Увидел — скажи
одной строкой в конце доклада, не находкой. Исключение ровно одно: если
неудачное слово стоит **в заголовке** и мешает ему ответить на вопрос своего
типа, это твоя находка — заголовок судишь ты.
Ты **ничего не правишь**. Каждая находка — готовая формулировка на замену,
которую зовущий подставит командой (`edit <слаг> --title …`, `--why …`) или
впишет в тело. Файлы ты только читаешь.
## Что тебе дают
Список файлов записей (`docs/tasks/items/<slug>.md`) или каталог задач целиком.
Каталог тебе нужен и сам по себе: задача несёт тег `goal:<слаг>`, и **файл цели
ты открываешь**, иначе шестое правило не проверить.
Документы проекта — паспорт, архитектура, конвенции — если зовущий их назвал.
По ним видно, названа ли граница именем, которое в проекте существует.
## Правила
1. **Заголовок отвечает на вопрос своего типа.**
| Тип | Отвечает на | Форма |
| --- | --- | --- |
| `[goal]` | что приложение будет уметь | утверждение о возможности: «Соперником может быть компьютер» |
| задача | что нужно сделать | глагол в неопределённой форме, допускается «не» перед ним: «Печатать поле одним куском кода» |
| `[idea]` | о чём она | назывное, без обещания: «Подсказка следующего хода» |
Описательный заголовок задачи («Лишние символы молча отбрасываются») называет
**состояние** и одинаково читается как жалоба и как задание. Заголовок цели в
форме действия («Сделать соперника-компьютер») превращает роадмап в список
работ — а он список возможностей.
**Область работ — не цель.** «Работа со слиянием», «Рефакторинг вывода» не
отвечают ни на один из трёх вопросов; предложи возможность, которую эта работа
создаёт, и скажи, если из текста её не видно. **Свойство поведения —
законная возможность**: «исход слияния не зависит от порядка доставки» — цель,
а не абстракция.
2. **«Зачем» отвечает на «зачем нужна эта задача»** — состояние, остаток, боль,
— а не пересказывает заголовок. «Починить разбор хода» при заголовке «Не
отбрасывать молча лишние символы» — пересказ: читающий узнаёт то же самое
дважды и по-прежнему не знает, почему это лежит в беклоге.
3. **«Затрагивает» перечисляет границы, а не замысел.** Граница — то, у чего есть
внешняя сторона: команда и её аргументы, эндпоинт, таблица и миграция, формат
на диске, публичный тип пакета, внешний сервис. «Переписать хранилище на новый
драйвер» — замысел; проверяется вопросом «это можно назвать до того, как
решено *как* делать?».
Две частые подмены, и обе — находки: **свойство репозитория** вместо границы
(«миграция 0042» вместо «таблица `points` и её миграция») — оно протухает
молча; и **будущее состояние границы** вместо её имени («источник хода
становится двумя» вместо «выбор источника хода в модуле партии») — это уже
решение о том, как делать.
4. **У критерия назван оракул, и оракул проверяем.** «Оракул: глазами» на
утверждение, которого глазами не проверить («компьютер не проигрывает ни в
одной партии»), — находка: слово стоит, проверки нет. Число критериев считает
`tasks.py check`, тебе оно неинтересно.
5. **Предписания процесса в теле нет.** «Делать профилем standard», «взять
такой-то агент» — это выбор, который делают, увидев изменение, а не при
постановке. Он же путь понизить требования решением, принятым до
проектирования.
6. **Задача называет, какую строку «Завершения» своей цели она двигает.**
Открой файл цели из тега `goal:<слаг>` и сверь. Три исхода, и все три —
разные находки:
- **строка не названа** — допиши предложение, какая это строка, если из текста
задачи видно; не видно — так и скажи;
- **строки с таким смыслом в «Завершении» нет** — либо задача не про эту цель,
либо у цели неполное «Завершение». Назови оба варианта, выбирать не тебе;
- **строка «Завершения», к которой не относится ни одна поданная задача**, —
это незакрытая часть возможности. Скажи о ней отдельно, вне списка находок
по файлам: это про набор, а не про запись.
У задачи **без цели** (`kind:fix`, `chore`, `research`) правило не
применяется вовсе — они служат работоспособности, а не направлению.
## Чего ты не проверяешь
**Язык** — он у `doc-wording`, см. выше.
Всё, что ловит `tasks.py check`: наличие разделов, число критериев, состав и
написание секций, теги, согласованность индексов, битые ссылки, форма заголовка
как строки. Повторять машинную проверку словами — заводить второй дом для одного
правила; если видишь такое, просто не пиши.
**Содержание работы**: нужна ли задача, верно ли выбрана цель, не крупна ли она,
достаточна ли декомпозиция. Шестое правило подходит к этому близко и
останавливается там, где кончается сверка с текстом цели.
## Порог вмешательства
<!-- копия: порог-правки из av-dev-pm/skills/canon/references/language.md -->
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
перестают читать весь список, и вместе с ним пропадают настоящие находки.
Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
основание для **одной находки на весь набор** («правило N нарушено в пяти
записях, перечень: …»), но не как основание промолчать. Принятым считается
только то, что назвал зовущий или что записано в конвенциях проекта.
<!-- /копия: порог-правки -->
Одна запись может дать несколько находок, но заголовок правится один раз: не
предлагай два варианта на выбор, предлагай лучший.
## Доклад
Находки по одной, в порядке важности: заголовок → «зачем» → границы → критерии →
связь с целью. Порядок такой, потому что заголовок и «зачем» — это всё, что
видно в индексе, а по индексу и выбирают.
```
<файл>
правило: <номер и короткое имя>
сейчас: <как написано>
предложение: <готовая формулировка, подставляемая как есть>
почему: <одна фраза>
```
Отдельным блоком после находок — **строки «Завершения» без задач**, если такие
нашлись: цель, строка, и что это значит.
В конце — **границы покрытия**: сколько записей просмотрено из скольких, какие
цели открыты, какие не смотрел и почему. Отчёт без этой строки читается как
«беклог проверен», не сообщая, какая его часть осталась нетронутой. Туда же —
строка «замечено не по моей части», если бросился в глаза язык.
Ничего не нашёл — так и скажи одной строкой. Пустой доклад с границами покрытия
полезнее выдуманной находки.
@@ -43,7 +43,7 @@ upgrade` идёт по записям снизу вверх от версии п
символы»), цель — на «что приложение будет уметь», идея просто называет, о символы»), цель — на «что приложение будет уметь», идея просто называет, о
чём она. `check` считает заголовки не в форме действия и печатает число в чём она. `check` считает заголовки не в форме действия и печатает число в
блоке здоровья. Годность формулировки — не машине: её смотрит новый агент блоке здоровья. Годность формулировки — не машине: её смотрит новый агент
`doc-wording` (вычитка формулировок, только чтение). `task-form` (форма записи, только чтение), а язык текста — `doc-wording`.
5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех 5. **Заголовки секций — с прописной, после заголовка пустая строка**, во всех
индексах. Написание канонических секций и отбивку правит `check --fix`; он индексах. Написание канонических секций и отбивку правит `check --fix`; он
же сводит написание секции в мете файла с заголовком индекса. же сводит написание секции в мете файла с заголовком индекса.
@@ -108,7 +108,7 @@ upgrade` идёт по записям снизу вверх от версии п
секцию в мете файлов с заголовками индексов. Секции беклога проект секцию в мете файлов с заголовками индексов. Секции беклога проект
переименовывает сам — их имена он выбирал, и трогать их скрипт не вправе. переименовывает сам — их имена он выбирал, и трогать их скрипт не вправе.
11. Переписать заголовки задач в форму действия — по мере того, как задача 11. Переписать заголовки задач в форму действия — по мере того, как задача
попадает в работу, а не «заодно»: `check` печатает их число, а `doc-wording` попадает в работу, а не «заодно»: `check` печатает их число, а `task-form`
предложит формулировки на замену пачкой. предложит формулировки на замену пачкой.
12. Прочитать [language.md](language.md) — и **ничего не переписывать задним 12. Прочитать [language.md](language.md) — и **ничего не переписывать задним
числом**. Правила языка применяются к тому, что пишется и правится сейчас; числом**. Правила языка применяются к тому, что пишется и правится сейчас;
+12 -1
View File
@@ -151,10 +151,21 @@
## Порог правки ## Порог правки
<!-- дом: порог-правки -->
**Правка без нарушенного правила не делается.** Текст, переписанный «чтобы **Правка без нарушенного правила не делается.** Текст, переписанный «чтобы
звучало лучше», обесценивает список замечаний: когда половина из них вкусовая, звучало лучше», обесценивает список замечаний: когда половина из них вкусовая,
перестают читать весь список, и вместе с ним пропадают настоящие находки. перестают читать весь список, и вместе с ним пропадают настоящие находки.
Сомневаешься — не правь. Сомневаешься — не правь. Формулировка, которая просто **не твоя**, — не находка.
**Систематичность нарушения — не довод в его пользу.** Одна и та же ошибка в
пяти файлах не становится «принятым стилем»: чаще это значит, что правило не
применялось вовсе, — и находка тем важнее. «Так сделано везде» годится как
основание для **одной находки на весь набор** («правило N нарушено в пяти
записях, перечень: …»), но не как основание промолчать. Принятым считается
только то, что назвал зовущий или что записано в конвенциях проекта.
<!-- /дом: порог-правки -->
И обратное: язык правится **по ходу той операции, которая записи касается**. И обратное: язык правится **по ходу той операции, которая записи касается**.
Беклог не переписывают ради языка. Беклог не переписывают ради языка.
+33 -20
View File
@@ -471,30 +471,43 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
обе половины остаются в одной ступени, потому что несокращаемый костяк проверок обе половины остаются в одной ступени, потому что несокращаемый костяк проверок
платится за каждую задачу отдельно. платится за каждую задачу отдельно.
### Вычитка формулировок ### Вычитка: два прохода, а не один
Язык записей судит **отдельный проход** — агент `doc-wording`, а не тот же Записи судит **не тот агент, который их написал**: самопроверка текста слабее
агент, который их только что написал: самопроверка текста слабее всего ровно всего ровно там, где формулировка казалась удачной при написании. Проходов два,
там, где формулировка казалась удачной при написании. Агент общий для всех и они разные по природе:
проектных текстов (отсюда имя), а форма записи — половина его устава, которая
включается только на файлах `items/`.
Зовётся он **пачкой, а не на каждую запись**: после заведения нескольких задач, | Проход | Что смотрит | Над чем работает |
после разбора находок ревью и на переоценке. Ему передаётся список файлов и — | --- | --- | --- |
если есть — паспорт, архитектура и конвенции проекта: по ним он отличает | `task-form` | заголовок по типу, «зачем» вместо пересказа, границы вместо замысла, годность оракулов, предписание процесса, связь со строкой «Завершения» цели | только `items/`, **открывает файл цели** |
неизвестный термин от известного. | `doc-wording` | залог и отглагольные, оценка без факта, стоп-слова, англицизмы, жаргон, неизвестный термин | любой проектный текст, включая документы канона |
Он ничего не правит. Возвращает готовые формулировки, и их подставляет скилл: Разделены они не по охвату, а **по глубине**. Язык проверяется по словам и
заголовок — `edit <слаг> --title …`, «зачем» — `edit <слаг> --why …`, остальное фразам, поштучно; форма записи требует понять, что задача делает, и открыть
редактором. **Заголовок и «зачем» — это то, по чему задачу выбирают, поэтому цель, на которую она ссылается. Слитый проход одну половину делает дорогой, а
менять их молча нельзя**: покажи предложенное пользователю вместе с тем, что вторую — поверхностной. Отсюда и разные модели.
было. Правки в теле (границы, критерии, язык) применяются сразу.
Что он смотрит и чего не смотрит — в его уставе; коротко: **форму записи** Каждый устав отказывается от чужой половины прямо: увиденное не по своей части
заголовок по типу, «зачем» вместо пересказа, границы вместо замысла, годность идёт **строкой в границах покрытия**, а не находкой. Две проверки одного места
оракулов, предписания процесса; и **язык** — залог и отглагольные, оценка без расходятся и начинают спорить, и разнимать их потом дороже, чем не сводить.
факта, стоп-слова, англицизмы, жаргон, неизвестные термины. Всё, что ловит
`tasks.py check`, он не трогает намеренно. **Порядок — сперва `task-form`.** Его находки меняют решение «брать или не
брать», а язык — только цену чтения; и переписанный заголовок бессмысленно
вычитывать до того, как он переписан.
Зовутся они **пачкой, а не на каждую запись**: после заведения нескольких задач,
после разбора находок ревью и на переоценке. Передаётся список файлов и — если
есть — паспорт, архитектура и конвенции проекта: по ним отличается неизвестный
термин от известного.
Ни один из них ничего не правит. Оба возвращают готовые формулировки, и их
подставляет скилл: заголовок — `edit <слаг> --title …`, «зачем» —
`edit <слаг> --why …`, остальное редактором. **Заголовок и «зачем» — это то, по
чему задачу выбирают, поэтому менять их молча нельзя**: покажи предложенное
пользователю вместе с тем, что было. Правки в теле (границы, критерии, язык)
применяются сразу.
Всё, что ловит `tasks.py check`, оба не трогают намеренно.
### Гигиена полей ### Гигиена полей
@@ -45,7 +45,7 @@
«Не отбрасывать молча лишние символы»); цель — на «что приложение будет «Не отбрасывать молча лишние символы»); цель — на «что приложение будет
уметь»; идея просто называет, о чём она. Почему так — SKILL.md, «Как написана уметь»; идея просто называет, о чём она. Почему так — SKILL.md, «Как написана
задача». `check` считает заголовки не в форме действия и печатает число в задача». `check` считает заголовки не в форме действия и печатает число в
здоровье; годность формулировки смотрит агент `doc-wording`. здоровье; годность формулировки смотрит агент `task-form`.
- **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательна - **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательна
секция, причина после тире желательна (именно она объясняет, почему задача секция, причина после тире желательна (именно она объясняет, почему задача
здесь оказалась — в том числе «вышла из спринта: …»), «зачем» и теги здесь оказалась — в том числе «вышла из спринта: …»), «зачем» и теги