av
e5dc0a1a39
Оба слова стояли в закрытом словаре правила 6 с оговоркой, и обе оговорки отвергали один русский вариант, а вывод из них делался про все. Отсюда общее требование к записи словаря: она обязана говорить, чем слово незаменимо, а не чем плох один из кандидатов. Латинизм, переживший проверку одним синонимом, — не имя вещи, а непроверенная привычка. Провенанс заменён двумя словами, потому что смысла было два, и это же его и держало: происхождение у числа (чем и при каких условиях получено) и откуда у вопроса и находки (кто нашёл, каким проходом, из какой записи журнала). Слово стояло и в скелете docs/review.md, уезжающем в репозитории проектов, поэтому раскладка повышена до версии 4 с записью журнала: правка формы вопроса и проход grep по docs/. Интейк заменён заведением с названным источником — «из диалога», «из ревью». Оговорка защищала слово от голого «заведения» и в этом была права, но в паре с источником двусмысленности нет, а скилл задач уже называет операцию так же. Раскладку это не двигает: слово жило только в прозе плагина. Образец стиля назван прямо и отдельным разделом: научно-популярная книга, не спецификация и не конспект для себя. Три умолчания — воды нет, сложных конструкций нет, англицизм исключение с причиной. Находок образец не порождает: он для того, кто пишет, а вычитка судит по правилам, иначе «звучит сложно» стало бы находкой и порог правки перестал бы работать. Журнал решений: темы 70 и 71, Р258–Р264 и С244–С249. Остальной словарь — триаж, дедуп, чек-лист, дифф, промпт, чекпоинт, синк — не пересматривался, и это сказано записью: пересмотр меняет язык всего корпуса и делается своей работой, а не попутно.
138 lines
12 KiB
Markdown
138 lines
12 KiB
Markdown
# Адаптация каталога задач
|
||
|
||
Проект, где задачи уже как-то ведутся, и из имеющегося материала **выводится**
|
||
заполненный каталог задач: задачи, кладбище, индекс. Операция разовая —
|
||
после неё проект живёт скиллами `task-track` и `task-groom`.
|
||
|
||
**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
|
||
`av-dev:canon`; он же зовёт этот сценарий на шаге «каталог задач», потому что
|
||
форматом задач владеет `task-track`, а не `canon`. Отдельно сценарий вызывается,
|
||
когда переводить надо **только** задачи.
|
||
|
||
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
|
||
кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с
|
||
индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список
|
||
шагов плана проекта.
|
||
|
||
## Три правила, из которых всё следует
|
||
|
||
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, в каком
|
||
порядке разложилось и **что не разложилось**, — и только после подтверждения
|
||
пишется хоть один файл. Это то же правило, что у заведения задач из ревью:
|
||
массовое заведение записей без подтверждения — самый дорогой отказ, потому
|
||
что разгребает его потом переоценка.
|
||
2. **Ничего не терять.** Исходный текст переезжает в тело, «зачем» и причина
|
||
сохраняются, кладбище переносится строка в строку. Переименование слага —
|
||
не правка, а **перенос ссылок**: он делается одним проходом вместе с
|
||
переименованием, иначе останутся битые ссылки, которых никто не проверяет.
|
||
3. **Что не классифицировалось — назвать поимённо.** Проглоченный пункт
|
||
выглядит как «всё перенеслось». Список «не разложилось» идёт в доклад
|
||
целиком, с причиной по каждому пункту.
|
||
|
||
## Форма: карта — суждение — запись
|
||
|
||
Механику несёт `tasks.py adopt`, суждение — ты. Разделено ровно по границе
|
||
«машина умеет / не умеет»:
|
||
|
||
```
|
||
tk="$CLAUDE_PLUGIN_ROOT/skills/task-track/scripts/tasks.py"
|
||
|
||
python3 $tk adopt scan --from docs/backlog docs/plan.md TODO.md \
|
||
--stage build --target tasks --out tasks-adopt-plan.json # только чтение
|
||
python3 $tk adopt apply --plan tasks-adopt-plan.json \
|
||
--refs docs openspec CLAUDE.md README.md # запись
|
||
```
|
||
|
||
`scan` ничего не пишет, кроме карты: он распознаёт раскладку, собирает записи,
|
||
поля «зачем», причины, кладбище, помечает похожее на транслит и на открытый вопрос в
|
||
прозе, и **называет поимённо** то, что не разложилось. `apply` пишет каталог
|
||
целиком одним проходом и чинит перекрёстные ссылки.
|
||
|
||
Между ними — твоя работа, которую машина не сделает:
|
||
|
||
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
|
||
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
|
||
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
|
||
- **стадия.** `--stage` называет, чем этот беклог будет: планом стройки или
|
||
очередью правок. Машине это не выводится — она видит список пунктов, а не то,
|
||
построено приложение или нет;
|
||
- **порядок.** Нумерованные шаги источника `scan` сохраняет по номерам, прочие
|
||
ставит следом. Дальше порядок — твоё суждение и подтверждение человека: на
|
||
стройке это зависимость, на доработке важность;
|
||
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
|
||
раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.
|
||
|
||
## Порядок
|
||
|
||
1. **Осмотрись и назови стадию.** Где лежат задачи, план, заметки; построено
|
||
приложение или строится. Каталог задач по канону — всегда `tasks`. Секции
|
||
беклога (`--sections`) — на стройке ровно одна (умолчание `План`), на
|
||
доработке сколько нужно (умолчание `Ядро,Инфра`); если у проекта деление
|
||
другое по существу, оно называется здесь, а не подгоняется под умолчание, и
|
||
становится **заголовками `##` индекса** — их единственным домом. В
|
||
`.av-dev.toml` секции не пишутся: там версия, стадия и имена частей, а второй
|
||
список секций разошёлся бы с заголовками молча.
|
||
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
|
||
прохода дадут два несогласованных состояния.
|
||
3. **Заполни карту**: `slug` (английский), `type` и `section` у каждой записи, и
|
||
**порядок `items`** — он уедет в индекс как есть. Пункт, помеченный
|
||
закрытым, не переносится вовсе.
|
||
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
|
||
рекомендация первым вариантом. Показывается: сколько записей, предлагаемый
|
||
порядок с обоснованием, спорные отнесения, список «не разложилось». Слаги не
|
||
выносятся — это механика; **порядок выносится всегда**, потому что механикой
|
||
он не является ни на одной стадии.
|
||
5. **`adopt apply`.** `--refs` перечисляет **всё**, где могут стоять ссылки на
|
||
слаги: документация, архив изменений, `CLAUDE.md`, `README.md`. Скрипт
|
||
посчитает и покажет, сколько ссылок поправлено и по каким слагам.
|
||
6. **`tasks.py check`** и доклад.
|
||
|
||
`apply` отказывается писать поверх живого каталога и проверяет карту целиком
|
||
**до** первой записи: неверная секция, дубль слага, неназванный тип, две секции
|
||
при стадии `build` — всё это отказ до того, как на диске появился хотя бы один
|
||
файл.
|
||
|
||
## Переходное состояние — объявляется, а не заминается
|
||
|
||
Сразу после адаптации задачи в большинстве своём **не готовы к взятию**: у них
|
||
нет критериев приёмки. Это нормально, но обязано быть названо, иначе следующий
|
||
агент примет пустой беклог за поломку.
|
||
|
||
`apply` печатает состояние по факту: сколько задач не собрало разделы своего типа
|
||
(для `check` это не ошибка, а строка здоровья, но `ready` такую задачу не
|
||
пропустит). Закрывается это **порциями по 5–8 задач**: превратить «готово,
|
||
когда» в критерии с оракулами, вынуть вопросы из прозы в раздел «Вопросы». На
|
||
доработке это груминг (скилл `av-dev:task-groom`), на стройке — гигиена полей
|
||
этого скилла: груминга там нет.
|
||
|
||
**Порядок строк проверяется глазами отдельно.** На стройке он выведен из
|
||
нумерации источника, и там, где её не было, он случаен. На доработке машина
|
||
важности не знает вовсе — очередь расставляется первым же грумингом.
|
||
|
||
Готовность к первой задаче — не «`check` зелёный», а «`ready` пропускает хотя бы
|
||
верхние строки очереди».
|
||
|
||
## Чего адаптация не делает
|
||
|
||
- **Не удаляет источники.** Старый каталог остаётся на месте: сверить и убрать —
|
||
дело человека, удалять чужое молча нельзя. В доклад идёт готовая команда.
|
||
- **Не переписывает подписи ссылок.** `[docs/backlog](tasks/BACKLOG.md)` —
|
||
цель поправлена, текст остался; это правится глазами, и таких мест немного.
|
||
- **Не сочиняет критерии приёмки** и не додумывает пользы, которой в материале
|
||
нет.
|
||
- **Не выводит стадию.** Список пунктов одинаково выглядит и планом стройки, и
|
||
очередью правок; отвечает `--stage`, а называет его человек.
|
||
- **Не трогает историю.** В коммитах старые слаги остаются, и это нормально.
|
||
|
||
## Доклад
|
||
|
||
- Источники и что в каждом распознано (раскладка, индекс, кладбище, секции).
|
||
- Стадия и сколько записей перенесено; откуда взялся порядок (нумерация
|
||
источника или суждение).
|
||
- **Переименования**: сколько слагов, сколько ссылок поправлено и в скольких
|
||
файлах — числом, а не «поправлены ссылки».
|
||
- **Не разложилось**: поимённо, с причиной.
|
||
- Переходное состояние: сколько задач без критериев, чем и за сколько порций
|
||
закрывается.
|
||
- `tasks.py check` — результат строкой.
|