av/dev-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

задачи: цель упразднена, у проекта появилась стадия

Browse Source 
Тип goal и индекс ROADMAP.md убраны: цель — зонтик над параллельными
направлениями, а у проекта на одного человека список работ линеен. Роадмап
при этом наполовину дублировал беклог, а «что уже умеет» отвечают спеки и
git log индекса. Секция «Готово» удалена, а не перенесена.

Вместо цели — ось «стадия проекта»: build (беклог это план стройки, порядок
строк значит зависимость, секция одна) и support (очередь правок, порядок
значит важность, секции — полки домена). Стадия объявляется ключом
[tasks] stage, меняется командой stage, без неё check отказывает: порядок
строк нечем прочитать.

Ушли теги goal:/decomposed, поле «Секция», раздел «Завершение», флаги
--goal и edit --section. Версия раскладки 2 → 3, перевод проекта расписан
записью журнала.
This commit is contained in:
av
2026-08-13 14:26:21 +03:00
parent 0627199a1a
commit 3849f084be
26 changed files with 1128 additions and 1485 deletions
Download Patch File Download Diff File Expand all files Collapse all files
av-dev/skills/task-track/references/adopt.md
+48 -42
View File
@@ -1,7 +1,7 @@
# Адаптация каталога задач
Проект, где задачи уже как-то ведутся, и из имеющегося материала **выводится**
заполненный каталог задач: цели, задачи, кладбище, индексы. Операция разовая —
заполненный каталог задач: задачи, кладбище, индекс. Операция разовая —
после неё проект живёт скиллами `task-track` и `task-groom`.
**Это часть приведения проекта к канону.** Раскладку `docs/` целиком ведёт скилл
@@ -12,12 +12,12 @@
Вход какой угодно: старая раскладка `av-dev-backlog` (индекс `README.md`,
кладбище `CLOSED.md`, приоритеты секциями, транслитные слаги, файлы рядом с
индексом), `TODO.md`, россыпь заметок, раздел «планы» в `README.md`, список
шагов роадмапа проекта.
шагов плана проекта.
## Три правила, из которых всё следует
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, как
разложилось по целям и **что не разложилось**, — и только после подтверждения
1. **Сперва карта, потом файлы.** Человеку показывается, что найдено, в каком
порядке разложилось и **что не разложилось**, — и только после подтверждения
пишется хоть один файл. Это то же правило, что у интейка находок ревью:
массовое заведение записей без подтверждения — самый дорогой отказ, потому
что разгребает его потом переоценка.
@@ -38,7 +38,7 @@
tk="$CLAUDE_PLUGIN_ROOT/skills/task-track/scripts/tasks.py"
python3 $tk adopt scan --from docs/backlog docs/plan.md TODO.md \
--target tasks --out tasks-adopt-plan.json # только чтение
--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 # запись
```
@@ -53,56 +53,60 @@ python3 $tk adopt apply --plan tasks-adopt-plan.json \
- **английские слаги.** Перевести `taj-brejk-pri-ravnoj-polnote` в
`tie-break-equal-completeness` может только тот, кто понимает смысл. `scan`
честно говорит: проверить надо **все** слаги, признаки транслита — эвристика;
- **цели.** Шаги роадмапа — готовые цели в **`Запланировано`** (очередь и
обоснование у них уже есть); тематические скопления задач — цели в
**`Направления`** («прочность слияния»,
«журнал и пересборка»). Предлагаешь ты, назначает человек;
- **стадия.** `--stage` называет, чем этот беклог будет: планом стройки или
очередью правок. Машине это не выводится — она видит список пунктов, а не то,
построено приложение или нет;
- **порядок.** Нумерованные шаги источника `scan` сохраняет по номерам, прочие
ставит следом. Дальше порядок — твоё суждение и подтверждение человека: на
стройке это зависимость, на доработке важность;
- **что вообще не задача.** Обоснование порядка шагов, абзац прозой, заголовок
раздела — это не пункты беклога, и они уходят в «не разложилось» с причиной.
## Порядок
1. **Осмотрись.** Где лежат задачи, роадмап, заметки. Каталог задач по канону —
всегда `tasks`. Секции беклога (`--sections`) — по умолчанию
`Ядро,Инфра`; если у проекта деление другое по существу, оно называется
здесь, а не подгоняется под умолчание, и становится **заголовками `##`
индекса** — их единственным домом. В `.av-dev.toml` секции не пишутся: там
версия формата и имена частей, а второй список секций разошёлся бы с
заголовками молча.
1. **Осмотрись и назови стадию.** Где лежат задачи, план, заметки; построено
приложение или строится. Каталог задач по канону — всегда `tasks`. Секции
беклога (`--sections`) — на стройке ровно одна (умолчание `План`), на
доработке сколько нужно (умолчание `Ядро,Инфра`); если у проекта деление
другое по существу, оно называется здесь, а не подгоняется под умолчание, и
становится **заголовками `##` индекса** — их единственным домом. В
`.av-dev.toml` секции не пишутся: там версия, стадия и имена частей, а второй
список секций разошёлся бы с заголовками молча.
2. **`adopt scan`** по всем источникам разом. Один прогон, одна карта: два
прохода дадут два несогласованных состояния.
3. **Заполни карту**: `slug` (английский), `section`, `goal` у каждой записи;
список `goals` — из шагов роадмапа и из тем. Закрытый шаг целью не
заводится. Пустой `goal` законен у `fix`, `chore` и `research` — они служат
работоспособности, а не направлению; у `feature` цель обязательна.
3. **Заполни карту**: `slug` (английский), `type` и `section` у каждой записи, и
**порядок `items`** — он уедет в индекс как есть. Пункт, помеченный
закрытым, не переносится вовсе.
4. **Покажи человеку карту** через `AskUserQuestion`, ≤3 вопроса за итерацию,
рекомендация первым вариантом. Показывается: сколько записей, предлагаемые
цели (порядок и темы) с обоснованием, спорные отнесения, список «не
разложилось». Массовые механические решения (слаги, порядок строк) не
выносятся — это механика.
рекомендация первым вариантом. Показывается: сколько записей, предлагаемый
порядок с обоснованием, спорные отнесения, список «не разложилось». Слаги не
выносятся — это механика; **порядок выносится всегда**, потому что механикой
он не является ни на одной стадии.
5. **`adopt apply`.** `--refs` перечисляет **всё**, где могут стоять ссылки на
слаги: документация, архив изменений, `CLAUDE.md`, `README.md`. Скрипт
посчитает и покажет, сколько ссылок поправлено и по каким слагам.
6. **`tasks.py check`** и доклад.
`apply` отказывается писать поверх живого каталога и проверяет карту целиком
**до** первой записи: неверная секция, дубль слага, цель, которой нет в карте —
всё это отказ до того, как на диске появился хотя бы один файл.
**до** первой записи: неверная секция, дубль слага, неназванный тип, две секции
при стадии `build` — всё это отказ до того, как на диске появился хотя бы один
файл.
## Переходное состояние — объявляется, а не заминается
Сразу после адаптации задачи в большинстве своём **не готовы к взятию**: у них
нет критериев приёмки, а у части может не быть цели. Это нормально, но обязано
быть названо, иначе следующий агент примет пустой беклог за поломку.
нет критериев приёмки. Это нормально, но обязано быть названо, иначе следующий
агент примет пустой беклог за поломку.
`apply` печатает состояние по факту: сколько задач без цели (это **ошибки**
`check`) и сколько не собрало разделы своего типа (для `check` это не ошибка, а
строка здоровья, но `ready` такую задачу не пропустит). Закрывается это
**порциями груминга** — скилл
`groom`, 5–8 задач за порцию: проставить цели, превратить «готово, когда» в
критерии с оракулами, вынуть вопросы из прозы в раздел «Вопросы». Там же
беклогу впервые назначается **порядок**: после адаптации его нет вовсе, а
очередь и есть то, ради чего каталог заводят.
`apply` печатает состояние по факту: сколько задач не собрало разделы своего типа
(для `check` это не ошибка, а строка здоровья, но `ready` такую задачу не
пропустит). Закрывается это **порциями груминга** — скилл `groom`, 5–8 задач за
порцию: превратить «готово, когда» в критерии с оракулами, вынуть вопросы из
прозы в раздел «Вопросы».
**Порядок строк проверяется глазами отдельно.** На стройке он выведен из
нумерации источника, и там, где её не было, он случаен. На доработке машина
важности не знает вовсе — очередь расставляется первым же грумингом.
Готовность к первой задаче — не «`check` зелёный», а «`ready` пропускает хотя бы
верхние строки очереди».
@@ -113,18 +117,20 @@ python3 $tk adopt apply --plan tasks-adopt-plan.json \
дело человека, удалять чужое молча нельзя. В доклад идёт готовая команда.
- **Не переписывает подписи ссылок.** `[docs/backlog](tasks/BACKLOG.md)` —
цель поправлена, текст остался; это правится глазами, и таких мест немного.
- **Не сочиняет критерии приёмки и не придумывает цели**, которых в материале
нет. Придуманная цель хуже отсутствующей: под неё заведут задачи.
- **Не сочиняет критерии приёмки** и не додумывает пользы, которой в материале
нет.
- **Не выводит стадию.** Список пунктов одинаково выглядит и планом стройки, и
очередью правок; отвечает `--stage`, а называет его человек.
- **Не трогает историю.** В коммитах старые слаги остаются, и это нормально.
## Доклад
- Источники и что в каждом распознано (раскладка, индекс, кладбище, секции).
- Сколько записей перенесено, сколько целей заведено (порядок / темы) и откуда
каждая выведена.
- Стадия и сколько записей перенесено; откуда взялся порядок (нумерация
источника или суждение).
- **Переименования**: сколько слагов, сколько ссылок поправлено и в скольких
файлах — числом, а не «поправлены ссылки».
- **Не разложилось**: поимённо, с причиной.
- Переходное состояние: сколько задач без цели, сколько без критериев, чем и за
сколько порций закрывается.
- Переходное состояние: сколько задач без критериев, чем и за сколько порций
закрывается.
- `tasks.py check` — результат строкой.
av-dev/skills/task-track/references/from-review.md
+8 -13
View File
@@ -50,17 +50,12 @@
заведённое и уже выкинутое. Нашлось среди живых — дописываем находку в
существующий файл. Нашлось в `REJECTED.md` — это сигнал: причина отказа могла
устареть, выноси пользователю, а не заводи молча заново.
4. **Разложи по целям — там, где цель нужна.** Большинство находок ревью это
`fix` и `chore`, и **цель им не требуется**: они служат работоспособности, а
не направлению. Придуманная им цель —
ровно то враньё, от которого спасает тип.
Цель обязательна у находки, которая оказалась **новой возможностью**
(`feature`): нашлось поведение, которого никто не заказывал, и его надо
либо заказать целью, либо убрать. Подходящей цели нет — заведи её
(`add --type goal --section Направления`) в том же проходе.
4. **Проставь типы.** Большинство находок ревью это `fix` и `chore`. Находка,
оказавшаяся **новой возможностью** (`feature`), — отдельный случай: нашлось
поведение, которого никто не заказывал, и решение тут не «завести задачу», а
«заказать или убрать». Выноси такую пользователю отдельно от прочих.
5. **Покажи карту до создания файлов.** Кластер → задача / сырьё / строка в
пакетный файл / уже заведено / отброшено, и под какую цель — пачкой через
пакетный файл / уже заведено / отброшено — пачкой через
`AskUserQuestion`. Это тот же барьер, что и «три кандидата» в интейке из
диалога: массовое заведение файлов без подтверждения — ровно тот отказ, ради
которого интейк из ревью и выделен. Дешёвая мелочь по явному согласию может
@@ -88,8 +83,8 @@
[скилле груминга](../../task-groom/SKILL.md#приоритет-как-его-расставляют), и
серьёзность попадает ровно в один из них.
- **тяжёлая находка со свидетельством о сломанном сейчас** → задача под ту цель,
которой она угрожает, и **первой строкой секции**: `move <слаг> --first
- **тяжёлая находка со свидетельством о сломанном сейчас** → задача
**первой строкой секции**: `move <слаг> --first
--reason «сломано сейчас: …»`. Это довод «что сломано сейчас» из перечня
груминга — единственный, который не требует сравнения с соседями по очереди,
потому что сломанное дорожает само. Позицию всё равно назначает человек, и
@@ -124,7 +119,7 @@
## Доклад
- Источник (какое ревью/аудит, сколько находок на входе).
- Свёрнуто в задачи: N кластеров из M находок, со слагами, целями и тегом партии.
- Свёрнуто в задачи: N кластеров из M находок, со слагами и тегом партии.
- Что не заведено и почему: починено инлайн, уже заведено, стало сырьём, ушло в
`REJECTED.md`.
- Поимённая сверка: находок на входе N, исход есть у N.
av-dev/skills/task-track/references/split.md
+29 -32
View File
@@ -8,14 +8,19 @@
Задачу можно дробить, только если части удовлетворяют **обоим** условиям:
1. **Мерджатся независимо.** Часть Б не требует, чтобы часть А была уже влита.
Есть порядок «сперва А, потом Б, иначе не собрать» → это не декомпозиция, а
план реализации: шаги остаются **внутри одного файла**.
1. **Каждая мерджится сама по себе.** Часть, после которой дерево не собирается
или поведение сломано до прихода соседней, — не часть, а половина.
2. **Каждая — самостоятельный шаг.** Часть, осмысленная только в комплекте с
другой, — не задача. Проверяй тестом «готова к взятию» (task-format): какую
строку «Завершения» цели двигает **именно эта часть** и какие у неё
собственные критерии приёмки. У операционных частей (`fix`, `chore`,
`research`) цели может не быть — тогда достаточно собственных критериев.
другой, — не задача. Проверяй тестом «готова к взятию» (task-format): свои
критерии приёмки у неё есть или нет.
**Порядок между частями законен на стройке и подозрителен на доработке**, и это
единственное, что стадия здесь меняет. Беклог стройки **весь** состоит из
упорядоченных зависимостью шагов: «сперва А, потом Б» — не повод не дробить, а
описание того, как этот список устроен, и части просто встают подряд. На
доработке правки независимы, и обнаруженный порядок «иначе не собрать» чаще
всего значит, что перед тобой не декомпозиция, а план реализации: шаги остаются
**внутри одного файла**.
Не проходит хотя бы одно — **не дроби**. Ложная декомпозиция плодит файлы,
которые нельзя взять поодиночке, и переоценка потом склеивает их обратно.
@@ -45,37 +50,29 @@
гигиена полей снимает. Шов пользуется меткой как **признаком**, что в задаче
две разнородные работы; решение о метке остаётся за конвейером.
**Цель наследуется.** Все части несут `goal:` родителя: декомпозиция не меняет
того, чему работа служит. Если у части цель другая — это признак, что дробили не
по той границе, либо что часть вообще из другой работы.
## Что делать с родителем
После разделения родитель **не остаётся** третьей висящей строкой:
- части полностью замещают его → `close <slug> --reason "разложена на a, b"`.
`REJECTED.md` здесь — не «выкинули», а именно тот след, что переживает запись:
через квартал вопрос «куда делась задача X» отвечается строкой со ссылками на
наследников, а не археологией git;
- родитель осмыслен как **возможность**, а не как шаг → это цель, и **строка
переезжает**: `edit <slug> --type goal --section <часть роадмапа>` снимает её с
`BACKLOG.md` и вставляет в `ROADMAP.md`. Файл в `items/` при этом не двигается —
он и есть запись. Части получают `--goal <слаг родителя>`, а закрывать родителя
нечем и незачем: он не выкинут, он стал целью.
части полностью замещают его → `close <slug> --reason "разложена на a, b"`.
`REJECTED.md` здесь — не «выкинули», а именно тот след, что переживает запись:
через квартал вопрос «куда делась задача X» отвечается строкой со ссылками на
наследников, а не археологией git.
**Промежуточного зонтика между целью и задачей нет.** Тип `epic` упразднён:
роль зонтика играет цель, а слишком крупный шаг дробится на шаги помельче под
той же целью. Если частям нужен общий заголовок — значит у них общая
возможность, и её надо назвать целью, а не заводить временный тип.
**Зонтика над частями нет никакого.** Тип `epic` упразднён, цель, игравшая его
роль после него, — тоже. Если частям нужен общий заголовок, у них общее место в
списке: они встают подряд, и соседство и есть тот ответ, ради которого заводили
зонтик.
## Когда декомпозиция случается посреди работы
Задача, которая **оказалась крупнее задачи**, распознаётся до того, как под неё
заведено предложение об изменении: иначе его придётся выбрасывать. Она выходит
из работы на декомпозицию, а её строка возвращается в беклог с причиной
(`move … --reason "крупнее задачи"`). Части заводятся сразу под той же целью, и
**место в очереди им назначает человек**: машина поставит их в конец секции, а
крупная задача редко распадается на что-то менее срочное, чем была сама.
(`move … --reason "крупнее задачи"`). **Место в списке частям назначает
человек**: машина поставит их в конец секции, а на стройке место наследуется от
родителя (`move --after`), да и на доработке крупная задача редко распадается на
что-то менее срочное, чем была сама.
## Мозговой штурм сырья
@@ -96,9 +93,9 @@ Applicative-штурм («перечисли задачи, следующие и
applicative.
2. **Вынеси формы пользователю** через `AskUserQuestion` с компромиссами. Рамку
выбирает он: это продуктовое решение, не механика.
3. **Назови цель.** Выбранная форма служит цели — существующей или новой. Идея,
для которой цель не находится, скорее всего уезжает в `REJECTED.md`, а не
заводится задачей.
3. **Назови пользу.** Выбранная форма отвечает на «что станет наблюдаемо иначе».
Идея, для которой такого ответа не находится, скорее всего уезжает в
`REJECTED.md`, а не заводится задачей.
4. **Только выбранную форму** дроби по тесту декомпозиции выше и проставь
критерии приёмки: без них наследники останутся идеями под другим именем.
@@ -109,8 +106,8 @@ Applicative-штурм («перечисли задачи, следующие и
## Доклад
- Идея/задача на входе, выбранная рамка (для штурма), задачи-наследники со
слагами, целями и секциями.
- Судьба родителя: удалён / стал целью / выкинут с причиной.
слагами, секциями и местом в списке.
- Судьба родителя: удалён / выкинут с причиной.
- `tasks.py check` после правок.
- Границы покрытия: какие постановки рассмотрены и какие сознательно отброшены —
чтобы штурм не пришлось повторять с нуля.
av-dev/skills/task-track/references/task-chore.md
+1 -5
View File
@@ -14,7 +14,6 @@
| Обязательные разделы | `Затрагивает`, `Критерии приёмки` |
| Допустимые сверх того | `Рамки`, `Вопросы` |
| Поле места | **Категория** — полка домена беклога |
| Цель (`goal:<слаг>`) | нет: цель — это возможность, а здесь её не появляется |
| Индекс | `BACKLOG.md` |
| Берётся в работу | да |
@@ -43,7 +42,7 @@
## Алгоритм
1. **Проверить, что поведение не меняется.** Меняется — это `feature` или `fix`,
и у неё другие требования (цель, воспроизведение).
и у последнего другие требования (воспроизведение).
2. **Назвать, что перестанет мешать** — одной фразой, адресуясь разработчику.
«Прибраться в модуле X» — не ответ: непонятно, что изменится.
3. **Назвать границы** в `Затрагивает`. У обслуживания они часто не в коде:
@@ -55,9 +54,6 @@
5. **Проверить, что это не «заодно».** Обслуживание любит склеиваться в пачку
(«обновить зависимости и переписать сборку и убрать мёртвый код»). Не
мерджится порознь — это несколько задач ([split.md](split.md)).
6. **Цель не проставлять.** `chore` служит работоспособности, а не направлению.
Работа по сопровождению проекта при этом видна в роадмапе — секцией
`Сопровождение`, но целью не становится.
## Кто такую задачу решает
av-dev/skills/task-track/references/task-feature.md
+9 -15
View File
@@ -15,18 +15,13 @@
| Обязательные разделы | `Затрагивает`, `Критерии приёмки` |
| Допустимые сверх того | `Рамки`, `Вопросы` |
| Поле места | **Категория** — полка домена беклога |
| Цель (`goal:<слаг>`) | **обязательна** |
| Индекс | `BACKLOG.md` |
| Берётся в работу | да |
**Цель обязательна, и это единственный тип, у которого так.** Новая возможность
и есть содержание цели: подходящей нет — либо она заводится, либо перед тобой не
`feature`. `ready` без цели откажет.
## Алгоритм
1. **Найти цель или завести её.** Задача без цели, названная функцией, — самый
частый способ пронести в беклог работу, которой никто не заказывал.
1. **Проверить, что возможность и правда новая.** Поведение расходится с уже
заявленным — это `fix`, а не `feature`, и требования у него другие.
2. **Назвать границы** в разделе `Затрагивает`: эндпоинт или команда, таблица и
миграция, формат на диске, публичный тип пакета, внешний сервис. Названы
**границы, а не замысел**: «переписать хранилище на новый драйвер» — замысел,
@@ -35,13 +30,12 @@
3. **Написать критерии приёмки** — 2–5 проверяемых утверждений списком, у
каждого назван оракул. Не «работает корректно», а «повторный прогон даёт тот
же отпечаток — оракул: команда сверки».
4. **Сказать, какую строку «Завершения» цели задача двигает.** Одной строкой в
теле. Это защита от задачи «отрефакторить X»: она проваливается не потому,
что невидима снаружи, а потому, что не находит строки, к которой относится.
4. **Поставить её на место в списке.** На стройке место называет зависимость:
`move <слаг> --after <шаг, без которого нельзя>`. На доработке место в
очереди назначает груминг, и конец списка законен.
5. **Проверить, что задача одна.** Отвечается всё, но задача не делается одним
заходом и не мерджится целиком — это несколько задач под одной целью, дроби
сразу ([split.md](split.md)). Промежуточного зонтика между целью и задачей
нет.
заходом и не мерджится целиком — это несколько задач, дроби сразу
([split.md](split.md)) и ставь их в списке подряд.
6. **Реализация** — дело конвейера проекта, не этого скилла. Закрывается
`close <слаг> --implemented`: файл и строка удаляются, суть переезжает в
`openspec/specs/` и документацию.
@@ -49,8 +43,8 @@
## Что видит машина, а что человек
Схему типа судит `ready` на входе в работу: **наличие непустого** раздела
`Затрагивает`, **число** критериев (меньше двух — отказ, больше пяти —
замечание) и цель. Наличие оракула проверяется **эвристикой** — словом «оракул»
`Затрагивает` и **число** критериев (меньше двух — отказ, больше пяти —
замечание). Наличие оракула проверяется **эвристикой** — словом «оракул»
в пункте. `check` этого поимённо не говорит, а считает строкой здоровья
(`SKILL.md`, «Что механизировано, а что нет»).
av-dev/skills/task-track/references/task-fix.md
+1 -4
View File
@@ -16,7 +16,6 @@
| Обязательные разделы | **`Воспроизведение`**, `Затрагивает`, `Критерии приёмки` |
| Допустимые сверх того | `Рамки`, `Вопросы` |
| Поле места | **Категория** — полка домена беклога |
| Цель (`goal:<слаг>`) | необязательна |
| Индекс | `BACKLOG.md` |
| Берётся в работу | да |
@@ -54,9 +53,7 @@
почти всегда есть парный критерий: **прежнее поведение не сломалось**
(«ввод `а1` принимается по-прежнему»). Без него починка чинит одно и ломает
соседнее.
6. **Цель не выдумывать.** `fix` служит работоспособности, а не направлению.
Придуманная цель — то же враньё, от которого спасает тип.
7. **Записать дефект в журнал** `docs/review.md` с пометкой «проскочил / пойман
6. **Записать дефект в журнал** `docs/review.md` с пометкой «проскочил / пойман
ревью». Проскочившие — проверочный набор для калибровки конвейера; пойманные с
оракулом — лучшая опора для прохода ревью: проектные, воспроизводимые,
однажды оказавшиеся правдой.
av-dev/skills/task-track/references/task-format.md
+51 -116
View File
@@ -1,4 +1,4 @@
# Формат записей и индексов
# Формат записей и индекса
Заголовок, мета-блок и строку индекса ставит `tasks.py add` — руками их не
пишут. Этот файл описывает **общую форму** любой записи и то, что проверяет
@@ -9,7 +9,6 @@
| Тип | Файл | Одной строкой |
| --- | --- | --- |
| 🎯 `goal` | [task-goal.md](task-goal.md) | возможность приложения |
| ✨ `feature` | [task-feature.md](task-feature.md) | снаружи появляется то, чего не было |
| 🐞 `fix` | [task-fix.md](task-fix.md) | поведение расходится с заявленным |
| 🧹 `chore` | [task-chore.md](task-chore.md) | обслуживание, поведение не меняется |
@@ -25,7 +24,6 @@
- **Тип:** fix
- **Категория:** Ядро — вернулась из работы: остаток писал нерешённое в журнал
- **Зачем:** ввод «а1б2» ходит в a1 — игрок не видит, что ошибся, и винит игру
- **Теги:** goal:merge-robustness
Разбор хода читает первые два символа и молча выбрасывает остаток строки.
@@ -55,8 +53,8 @@
**эмодзи типа**, и она **производна**: её ставит `add` и чинит `check --fix`
по полю меты. Второго дома у типа нет — эмодзи это его отображение, как
строка индекса это отображение файла.
- **Форма заголовка — по типу.** Цель отвечает на «что приложение будет уметь»;
`feature`, `fix` и `chore` — на «что нужно сделать», глаголом в неопределённой
- **Форма заголовка — по типу.** `feature`, `fix` и `chore` отвечают на «что
нужно сделать», глаголом в неопределённой
форме, перед ним допускается «не»; `research` называет предмет разведки и
формы действия **не несёт намеренно**. Почему так — SKILL.md, «Как написана
задача». `check` считает заголовки не в форме действия и печатает число в
@@ -67,9 +65,8 @@
теги необязательны. Нераспознанные поля сохраняются: скрипт правит свои и не
трогает чужие.
- **Тип — первым полем.** Он решает, что у записи вообще может быть: какие
разделы обязательны, нужна ли цель, берётся ли она в работу, — и читается
раньше всего остального. Словарь **закрыт**: `goal` | `feature` | `fix` |
`chore` | `research`. Не подходит ни один — это сигнал, что в записи их два и
разделы обязательны и берётся ли она в работу, — и читается раньше всего
остального. Словарь **закрыт**: `feature` | `fix` | `chore` | `research`. Не подходит ни один — это сигнал, что в записи их два и
её надо разделить.
- **«Зачем» отвечает на «зачем нужна эта задача»** — состояние, остаток, боль.
Не пересказ задачи: пересказ уже есть по ссылке. Живёт здесь, а не только в
@@ -86,19 +83,16 @@
Тело — не план реализации и не спецификация: принятое и реализованное переезжает
в документацию проекта, а файл задачи удаляется.
### Поле места: «Категория» и «Секция»
### Поле места: «Категория»
Поле называет, **где числится строка**, и имя у него **зависит от типа**:
Поле называет **секцию беклога, в которой числится строка** — полку домена
(`Ядро`, `Инфра`, …), куда задачу положили и куда вернут, если она уйдёт в работу
и вернётся. **На стройке секция одна**, и поле называет её же: различать ей
нечего, но производность от заголовка индекса сохраняется и там.
| Тип | Поле | Значения | Что это |
| --- | --- | --- | --- |
| `goal` | **Секция** | `Запланировано`, `Направления`, `Сопровождение` | часть роадмапа: состояние очереди |
| прочие | **Категория** | секции беклога проекта (`Ядро`, `Инфра`, …) | полка домена, на которой задача лежит |
Разные имена потому, что это **разные вещи**. У задачи это полка: куда её
положили и куда вернут, если она уйдёт в работу и вернётся. У цели оно называет
не полку, а место в очереди работ. Одно имя на два смысла их и смешивало; `check` называет
несовпадение дрейфом, `check --fix` переименовывает.
Прежнее имя поля — **«Секция»**: так оно называлось у целей, указывая на часть
роадмапа. Разбор его по-прежнему принимает, `check` называет дрейфом, `check
--fix` переименовывает.
Имя самого места принадлежит **заголовку индекса** — файл на него лишь
ссылается, и принадлежность сверяется по нижнему регистру.
@@ -111,7 +105,8 @@
| --- | --- |
| префикс `[goal]` / `[idea]` в H1 | поле **Тип** + эмодзи в H1; `[idea]` → `research` |
| тег `kind:<род>` | поле **Тип** (род работы стал типом) |
| поле **Секция** у задачи | поле **Категория** |
| поле **Секция** | поле **Категория** |
| теги `goal:<слаг>` и `decomposed` | сняты: целей больше нет |
| поле **Хук** | поле **Зачем** |
| мета одной строкой через `·` | мета списком, поле на строку |
@@ -147,8 +142,8 @@
забыли назвать, она от отсутствующей не отличает. Раздела нет — отказ во взятии:
оценивать нечем.
**У `goal` и `research` раздела нет** — у первой границы называют её задачи, у
второй они становятся известны, когда из разведки родятся задачи.
**У `research` раздела нет** — её границы становятся известны, когда из разведки
родятся задачи.
### Критерии приёмки
@@ -166,8 +161,7 @@
что проверено больше проверенного, хуже, чем не проверять вовсе.
**У `research` критериев нет** — её приёмка это записанный ответ, и описывается
она разделами «Вопрос» и «Куда ляжет ответ». **У `goal` их заменяет
«Завершение».**
она разделами «Вопрос» и «Куда ляжет ответ».
**Критерии — пол, но расхождение с ними есть дефект критериев.** Если приёмщик
видит, что критерии закрыты, а суть задачи не достигнута, он **правит критерии и
@@ -210,44 +204,6 @@
на снятый тег при непустом разделе посоветует тег вернуть. Снять тег, не
опустошив раздел, — значит закольцевать себя между двумя советами.
## Файл цели
Форма та же, разделы и алгоритм — [task-goal.md](task-goal.md).
```markdown
# 🎯 Исход слияния не зависит от порядка доставки
- **Тип:** goal
- **Секция:** Направления
- **Теги:** decomposed
Ради чего: точки из разных доставок сходятся в один часовой объект, и сегодня
исход столкновения зависит от порядка доставки, а не от содержания.
## Завершение
- повторная доставка тех же точек в другом порядке даёт то же состояние;
- накопительная метрика за сутки не уменьшается после повторной доставки;
- в логе видно, какая из двух точек выиграла и почему.
```
- **Задачи цели здесь не перечисляются.** Перечень даёт
`tasks.py list --goal <слаг>`; хранимый список стал бы третьим индексом и
поехал бы на первой же закрытой задаче.
- **Тег `decomposed`** отличает «цель ещё не разобрана» от «все её задачи
закрыты» — два состояния, у которых снаружи один и тот же признак: задач нет.
Пометка именно **тегом**, а не строкой в теле: только так она проверяется.
`check` напоминает о нём у цели без задач замечанием — неразобранная цель
законна и зелёного прогона не ломает; `check --fix` сам ставит его цели, у
которой задачи есть, а цель с тегом и без задач — прямое приглашение закрыть.
- Цель живёт в `ROADMAP.md` и **никогда** — в `BACKLOG.md`.
- **Достигнутая цель не исчезает.** `close <слаг> --implemented` удаляет файл и
переносит строку в секцию `Готово` с датой:
`- 2026-08-04 \`merge-order\` — Исход слияния не зависит от порядка доставки. …`
Ссылки на файл в ней нет — файл удалён, а битая ссылка это ошибка `check`.
Поведение живёт в спеках проекта; роадмап отвечает, **когда и в каком порядке**
оно появилось.
## Слаг
Латиница и цифры, kebab-case, без ведущих, хвостовых и двойных дефисов
@@ -261,9 +217,9 @@
проходом по всем местам, где слаг упомянут, иначе останутся битые ссылки,
которых никто не проверяет.
## Индексы
## Индекс
Строка везде одной формы:
Строка одной формы:
```markdown
- [🐞 Заголовок дословно](items/slug.md) — зачем
@@ -276,52 +232,47 @@
| Файл | Что отвечает | Секции |
| --- | --- | --- |
| `ROADMAP.md` | что приложение уже умеет и чего ещё не умеет | канонические и в этом порядке: `Запланировано`, `Направления`, `Сопровождение`, `Готово` (англ. `Planned`, `Directions`, `Operations`, `Done`) |
| `BACKLOG.md` | что **можно взять** — только задачи, **в порядке очереди** | категории проекта (по умолчанию Ядро/Инфра) |
| `BACKLOG.md` | что **можно взять**, в значимом порядке | называет проект; на стройке ровно одна (умолчание `План`), на доработке сколько нужно (умолчание `Ядро`/`Инфра`) |
| `REJECTED.md` | что ушло без реализации и почему | — |
Секции — **единственные заголовки `##` в индексе**: любой другой `##` в
преамбуле проверка сочтёт секцией.
**Порядок строк внутри секции беклога значим: это очередь.** Первая строка — то,
что делают следующим; назначает порядок человек на груминге, и двигают его
`move --after` и `move --first`. Одно место из очереди изъято и **производно от
типа и заполненности**: **сырьё** (`research` без раздела «Вопрос») стоит в конце
своей секции, потому что его не берут, и между берущимся оно каждый раз требует
**Порядок строк внутри секции значим, и стадия решает, что он значит:** на
стройке зависимость, на доработке важность (SKILL.md, «Две стадии»). Назначает
его человек — раскладывая шаги или на груминге, — и двигают его `move --after`
и `move --first`. Одно место из очереди изъято и **производно от типа и
заполненности**: **сырьё** (`research` без раздела «Вопрос») стоит в конце своей
секции, потому что его не берут, и между берущимся оно каждый раз требует
открыть файл, чтобы это понять. Проверяет `check`, переставляет `check --fix`,
и человек этот порядок не назначает — иначе он был бы приоритетом, которого
здесь нет.
и человек этот порядок не назначает — иначе он был бы решением, которого здесь
нет.
**Секции «блокеры» среди них нет.** Блокер — состояние, а не полка: он живёт до
ответа человека, а следы остаются вопросами в файлах задач.
Постоянно пустая секция со старой семантикой «разбираются пачками» противоречила
бы правилу «эскалируем немедленно», поэтому `init` её не заводит, а `check`
говорит о ней в чужом беклоге. Переезжаешь с такой секцией — удали её. В секции
**`Запланировано`** очередь значима и обосновывается прозой; двигают строку
`move <slug> --section Запланировано --after <другой>`. В секции **`Готово`**
строки не той формы, что у прочих индексов: дата, слаг, заголовок — как в
`REJECTED.md`, и по той же причине (файла уже нет, ссылаться некуда).
говорит о ней в чужом беклоге. Переезжаешь с такой секцией — удали её.
**Секции роадмапа закреплены** — состав, полнота, единство языка и **порядок**
проверяются `check`; категории беклога проект называет сам. Почему так —
SKILL.md. Порядок закреплён потому, что `Готово` копится: стоя первым,
достигнутое отодвигает за экран то, ради чего роадмап открывают чаще всего.
**Имена секций проект выбирает сам, а количество ограничено стадией:** на
стройке секция одна, потому что порядок там зависимость, и разложенный по полкам
список перестаёт быть планом. Проверяет `check`; слить секции сам он не берётся —
в каком порядке пойдут строки слитых полок, знает только человек.
**Заголовок секции пишется с прописной и отбивается пустой строкой с обеих
сторон** — во всех индексах, включая категории беклога, имена которых выбирает
проект. Написание канонических секций и отбивку правит `check --fix`; он же
сводит написание места в мете файла с заголовком индекса.
сторон.** Отбивку правит `check --fix`; он же сводит написание места в мете файла
с заголовком индекса.
Индексы **производны**: расходятся с файлом — правим индексы (`check --fix`).
Индекс **производен**: расходится с файлом — правим индекс (`check --fix`).
Строку руками не пишут.
Отсюда же ответ на «а если оборвётся посередине». Мутация сперва проверяет всё
и складывает правки, и только потом пишет: сначала все временные файлы, потом
переименования подряд. Полной транзакции на несколько файлов файловая система не
даёт, но окно сжато до цепочки переименований, а **всё, что в нём может
разъехаться, — производное**: файлы целы, индексы восстанавливает `check --fix`.
разъехаться, — производное**: файлы целы, индекс восстанавливает `check --fix`.
Поэтому отказ на второй задаче из пяти не оставляет первую переписанной при
нетронутых индексах.
нетронутом индексе.
## `REJECTED.md`
@@ -346,27 +297,24 @@ SKILL.md. Порядок закреплён потому, что `Готово`
Разметка сверх типа. Тип полем, потому что он один и обязателен; теги — потому
что их много и `list --tag` уже умеет отбирать по ним порцию разбора.
- `goal:<слаг>` — цель, которой служит задача. Обязателен **у `feature`**:
новая возможность и есть содержание цели. У `fix`, `chore` и `research` его
может не быть — они служат работоспособности, а не направлению.
- `question` — в файле есть неразобранный раздел «Вопросы».
- `decomposed` — на цели: разложена на задачи (см. «Файл цели»).
Тега `kind:<род>` больше нет: род работы стал типом. Оставшийся в файле `check`
называет дрейфом, а `check --fix` снимает, перенеся значение в поле «Тип».
Тегов `kind:<род>`, `goal:<слаг>` и `decomposed` больше нет: род работы стал
типом, а цели упразднены. Оставшиеся в файле `check` называет дрейфом, а `check
--fix` снимает (значение `kind:` при этом переезжает в поле «Тип»).
Отбор — `list --tag a,b`: перечисленные через запятую теги требуются **все
сразу** (это И, не ИЛИ). Тег, которого нет ни у одной задачи, `list` называет
вслух: молчаливый ноль читается как «таких задач нет», а чаще это опечатка.
Свои теги проект заводит свободно (партия ревью `review-ГГГГ-ММ-ДД`, тема,
источник) — словарь не фиксирован. В индексы теги не выносим: индексы
производны, отбор делает `list --tag`, а не глаза.
источник) — словарь не фиксирован. В индекс теги не выносим: он
производен, отбор делает `list --tag`, а не глаза.
## Тест «готова к взятию»
Задача готова, если из файла отвечаются четыре вопроса. Первый и четвёртый —
общие, второй и третий у каждого типа свои и перечислены в его файле.
Задача готова, если из файла отвечаются три вопроса. Первый общий, второй и
третий у каждого типа свои и перечислены в его файле.
1. **Что станет наблюдаемо иначе**, когда она сделана — снаружи: пользователю,
владельцу сервиса или разработчику. «Отрефакторить X» — не ответ; «перестанет
@@ -379,26 +327,13 @@ SKILL.md. Порядок закреплён потому, что `Готово`
`chore` — `Затрагивает`.
3. **По чему видно, что закончено** — критерии приёмки с оракулами;
у `research` вместо них `Куда ляжет ответ`.
4. **Какую часть «Завершения» своей цели она двигает** — у задачи с целью.
Строкой: «двигает пункт 2 «Завершения» — накопительная метрика перестаёт
уменьшаться». Это и есть защита от задачи «отрефакторить X»: она проваливает
тест не потому, что невидима снаружи, а потому, что не находит строки, к
которой относится. Заодно видно обратное — достаточен ли набор задач для
цели: строка «Завершения», к которой не относится ни одна задача, это
незакрытая часть возможности.
**У задачи без цели** (`fix`, `chore`, `research`) вопрос не задаётся: они
служат работоспособности, а не направлению.
Не отвечается первый, второй или третий вопрос → это ещё не задача, а **сырьё**:
тип `research` без раздела «Вопрос», место — конец секции, работа над ним —
штурм. Не отвечается четвёртый у `feature` → либо цель есть и не проставлена,
либо это не новая возможность.
Не отвечается любой из трёх → это ещё не задача, а **сырьё**: тип `research` без
раздела «Вопрос», место — конец секции, работа над ним — штурм.
Отвечается всё, но задача не делается одним заходом и не мерджится целиком →
это **несколько задач под одной целью**, дроби сразу. Промежуточного зонтика
между целью и задачей нет: тип `[epic]` упразднён, потому что зонтиком стала
сама цель.
это **несколько задач**, дроби сразу и ставь их в списке подряд. Промежуточного
зонтика между планом и задачей нет: тип `[epic]` упразднён, и цель, ставшая
зонтиком после него, упразднена тоже.
Тест применяется при заведении и при переоценке. К старым задачам, которых
операция не касается, задним числом не применяется — беклог не переоформляют
av-dev/skills/task-track/references/task-goal.md
-93
View File
@@ -1,93 +0,0 @@
# 🎯 `goal` — возможность приложения
Цель отвечает на **«что приложение будет уметь»**. Не область работ и не имя
подсистемы: не «Работа со слиянием», а «Исход слияния не зависит от порядка
доставки». Свойство поведения — тоже возможность.
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
Здесь только то, что у этого типа своё.
## Схема
| | |
| --- | --- |
| Заголовок отвечает на | что приложение будет уметь |
| Обязательные разделы | `Завершение` |
| Допустимые сверх того | — |
| Поле места | **Секция** — часть роадмапа |
| Цель (`goal:<слаг>`) | запрещена: цель и есть цель |
| Индекс | `ROADMAP.md`, и никогда `BACKLOG.md` |
| Берётся в работу | нет — берутся её задачи |
Поле места у цели называется **«Секция»**, а не «Категория», и это не разнобой:
у задачи оно называет полку домена, на которой она лежит, а у цели
— часть роадмапа, то есть состояние очереди. Одно имя на два смысла их и
смешивало.
## «Завершение» — списком, а не абзацем
Это признаки того, что приложение **уже умеет**, и на строки этого раздела
ссылаются задачи цели: «двигает пункт 2 «Завершения» — накопительная метрика
перестаёт уменьшаться». Абзацем такая ссылка не берётся, поэтому список.
Отсюда же читается обратное и более полезное: **строка «Завершения», к которой
не относится ни одна задача, — незакрытая часть возможности**. Достаточность
набора задач видна из самой цели, а не из чьей-то памяти.
## Алгоритм
1. **Проверить, что это возможность, а не работа.** Работа, которой держат
проект, на вопрос «что приложение будет уметь» не отвечает; состав перечислен
[в словаре сопровождения](../../../shared/operations.md). Ей отведена секция
`Сопровождение` — там она видна в том же
экране и не читается как обещание продукта. Граница проходит по тому,
**кто наблюдает**:
«приложение сообщает о своём состоянии» — возможность, «дежурный видит
состояние на одном экране» — сопровождение.
2. **Выбрать секцию.** Очередь значима и обоснована прозой — `Запланировано`;
тянется долго и очереди не имеет — `Направления`; про то, чем держат проект,
— `Сопровождение`. В `Готово` кладёт сам `close`.
3. **Написать «Завершение»** — 2–5 наблюдаемых признаков списком. Пишутся до
декомпозиции: иначе задачи придумают себе цель задним числом.
4. **Разложить на задачи** и проставить им `goal:<слаг>`. Перечень задач в теле
цели **не хранится** — он был бы третьим индексом и поехал бы на первой же
закрытой задаче; выводит `tasks.py list --goal <слаг>`.
5. **Пометить `decomposed`.** Тег отличает «ещё не разобрана» от «все задачи
закрыты» — два состояния с одним внешним признаком. `check --fix` ставит его
сам цели, у которой задачи есть.
6. **Закрыть достигнутой** — `close <слаг> --implemented`, когда не осталось
открытых задач. Файл удаляется, строка с датой переезжает в `Готово`. Скрипт
откажет, если задачи ещё живы.
## Отменённая цель — сперва задачи, потом цель
Замысел бывает неверен, и цель отменяют, не достигнув. Порядок обратный
завершению и держится тем же запретом: цель, закрытая поверх живых задач,
оставила бы их сиротами, и `close` этого не даст.
1. **Разобрать её задачи поштучно.** Задача, теряющая смысл вместе с целью, —
`close <slug> --reason "<почему>"`; задача, переживающая цель, — `edit <slug>
--goal <другая>`. **Причина обязательна и пишется своя каждой:** «цель
отменена» это не причина, а пересказ команды, и в `REJECTED.md` от него нет
пользы через квартал.
2. **Закрыть саму цель** — `close <слаг> --reason "<почему замысел отменён>"`.
Файл удаляется, строка с причиной и датой уходит в `REJECTED.md`. В `Готово`
не попадает: `Готово` отвечает «что приложение умеет», а отменённая цель не
умеет ничего.
**Место этому — груминг, а не отдельный заход.** Отмена цели значит
разбор всех её задач, а разбор задач и есть шаг 3 груминга
(скилл `task-groom`, «что перестало быть важным»). Отменять на ходу,
между делом, — верный способ закрыть скопом то, что стоило перевесить.
## Что видит машина, а что человек
`check` считает цели, различает разобранные и пустые, ставит `decomposed`,
запрещает закрыть цель с живыми задачами и держит `Секцию` в согласии с
заголовком роадмапа. **Годность формулировки — не машине**: «возможность это или
область работ» решает [агент вычитки](../SKILL.md#вычитка-два-прохода-а-не-один).
Достигнутая цель **не исчезает**: «что приложение умеет» — половина вопроса, ради
которого роадмап открывают. Вторым домом поведения роадмап при этом не
становится: нормативное поведение живёт в `openspec/specs/`, роадмап отвечает,
**когда и в каком порядке** оно появилось.
av-dev/skills/task-track/references/task-research.md
-1
View File
@@ -14,7 +14,6 @@
| Обязательные разделы | `Вопрос`, `Куда ляжет ответ` |
| Допустимые сверх того | `Рамки`, `Вопросы` |
| Поле места | **Категория** — полка домена беклога |
| Цель (`goal:<слаг>`) | нет |
| Индекс | `BACKLOG.md` |
| Берётся в работу | да — **но только с заполненным «Вопросом»** |