слияние: три плагина стали одним av-dev, скиллы получили префиксы

Каталоги, агенты и общие дома переехали в av-dev/; скиллы названы по прежнему
плагину — doc-*, task-*, code-*, с двумя смысловыми именами вместо тавтологии:
doc-sync вместо docs, task-track вместо tasks. Манифесты сведены к двум
плагинам. Пространства имён вызовов и пути внутри дерева переписаны машинно;
проза, которая называет прежние плагины отдельными, идёт следующим шагом.
This commit is contained in:
av
2026-08-13 10:10:51 +03:00
parent 142659bfd1
commit de12a4d8a3
68 changed files with 222 additions and 248 deletions
+247
View File
@@ -0,0 +1,247 @@
---
name: task-groom
description: "Груминг беклога — интерактивный разбор, отвечающий на два вопроса: что сейчас самое важное и что перестало быть важным. Ответ записывается порядком строк в беклоге: первая строка — то, что делают следующим. Разбирает накопившиеся вопросы, переоценивает задачи порциями по 5–8 (сделано попутно, отменено решением, слилось с соседней, подешевело, разрослось, стало сырьём), закрывает отжившее с причиной и расставляет очередь. Использовать, когда просят разобрать беклог, расставить приоритеты, решить «что делать дальше», провести груминг или переоценку, а также когда вернулись к проекту после перерыва и надо понять, где остановились. Формат и содержимое записей — скилл tasks; выполнение задачи — конвейер проекта."
---
# Груминг: что важно, что перестало
Скилл отвечает на **два вопроса**, и всё, что не служит им, — не его работа:
1. **Что сейчас самое важное?**
2. **Что перестало быть важным?**
Ответ на оба **записывается порядком строк в беклоге**: первая строка секции —
то, что делают следующим; то, что перестало быть важным, из беклога уходит с
причиной. Приоритет — свойство очереди, а не задачи, и живёт он в индексе
(правило 4 скилла `tasks`). Груминг — единственное место, где очередь
назначается человеком.
**Скилл интерактивный.** Он не «приводит беклог в порядок» сам: суждение о
важности принадлежит человеку, и весь ход — это подготовленные развилки с
рекомендацией. Что решается фактом (сделано, отменено, дублируется), решается
без вопросов и показывается списком.
Форматом и содержимым записей владеет скилл `tasks` — груминг зовёт его
операции, а не правит файлы руками. Выполнением задачи — конвейер проекта.
## Три правила, из которых всё следует
1. **Порядок назначает человек, машина его не выводит.** Ни давность, ни тип, ни
число задач под целью приоритетом не являются. Единственное место в очереди,
назначенное не человеком, — конец секции у сырья, и оно из очереди изъято
(`tasks`, правило 4).
2. **Порция важнее охвата.** Тридцать задач за заход — это усталость и
штамповка: последние десять получат «оставить» не потому, что живы, а потому,
что разбор затянулся. Лучше две честные порции, чем один полный проход.
3. **Причина уезжает в запись.** Всё, что решено здесь, оставляет след:
`--reason` у закрытия и переноса, ответ в теле задачи, строка в докладе.
Решение, оставшееся в переписке, будет принято заново через месяц.
## Когда груминг созрел
**Зовёт человек.** Скилл сам себя не назначает, но обязан **напоминать**, и
признак наблюдаемый, а не календарный:
- в беклоге появились записи, которых человек ещё не видел (заведены интейком по
ходу работы, урожаем ревью, разбором находок);
- на верхних строках очереди есть задача с открытым вопросом — очередь
показывает то, что взять нельзя;
- `tasks.py check` печатает «готово к взятию: 0 из N» — брать сегодня нечего.
Порога в неделях нет намеренно: счётчик простоя пришлось бы вести руками, а
решает всё равно человек. Признак — **очередь перестала быть твоей**: взялся
перечитывать, почему эти задачи стоят в таком порядке, — пора.
## Вопрос, блокер, необратимое
| | Что это | Когда спрашиваем | Что останавливает |
| --- | --- | --- | --- |
| **Вопрос** | решение человека | на груминге, пачкой | взятие задачи в работу |
| **Блокер** | работа не может продолжаться ни одной задачей | немедленно | всё |
Право на **необратимое** — третье и отдельное: что именно необратимо, называет
`CLAUDE.md` проекта, и спрашивается оно всегда, независимо от того, когда был
последний груминг.
**Блокер определяется исходом, а не одновременностью.** Встали разом или
задачи выпадали по одной — если продолжать нечем, это блокер, и человек
спрашивается немедленно, а не ждёт ближайшего груминга.
**Отличать вопрос от застревания.** Правило про остаток принадлежит управлению
задачами: оно решает, **сделана задача или вышла**, а это исход планирования, не
исполнения. **Ниже канонический текст; конвейер проекта на него ссылается, а не
пересказывает** — два экземпляра одного правила разъезжаются, и разъезжаются
незаметно, потому что расхождение видно только на редком входе.
> Есть остаток, который доводится без ответа, — задача продолжается, вопрос
> записывается в файл. Остатка нет — задача возвращается в беклог.
С двумя оговорками, без которых тест ошибается:
> **Остаток, который материализует нерешённое** — записывает в хранилище,
> журнал, витрину **или наружу** состояние, зависящее от неотвеченного вопроса,
> — **не остаток**. Решение поднимается до начала записи: откатить запись
> дороже, чем подождать ответ, а иногда невозможно. «Наружу» — часть правила, а
> не пример: выкладка, публикация и отправка данных третьей стороне не
> откатываются тем более.
> **Пол для остатка:** остаток, из которого пропала польза, названная в «зачем», —
> это не сделанная задача, а вернувшаяся в беклог.
## Ход груминга
Четыре шага, и порядок — зависимость, а не список.
```mermaid
flowchart TD
check["tasks.py check (+ --fix)<br/>результат — строкой в доклад"]
s1["1. Осмотреться<br/>что накопилось, чего человек ещё не видел"]
s2["2. Разобрать вопросы<br/>пачкой, не больше трёх за раз"]
s3["3. Что перестало быть важным<br/>порциями по 58"]
s4["4. Что важно сейчас<br/>расставить порядок строк"]
check --> s1 --> s2 --> s3 --> s4
s2 -->|"неотвеченный вопрос → судим о важности вслепую"| s4
s3 -->|"без переоценки очередь строится из протухшего"| s4
```
Схема — **сводка**: процедура каждого шага в
[references/portions.md](references/portions.md), и при расхождении прав текст.
**1. Осмотреться.** `tasks.py check` (при дрейфе — `--fix`), затем показать
человеку текущую очередь: верхние строки каждой секции и что появилось с
прошлого раза. Это половина ответа на «что важно»: очередь, которую не видели,
обсуждать бессмысленно.
**2. Разобрать вопросы.** Вопрос — решение человека, и разбирается он **пачкой**,
а не по одному, как только возник: по одному это дёрганье, пачкой это груминг.
Вопрос на верхних строках очереди разбирается **вне очереди порции**: иначе
правило «задача с открытым вопросом в работу не берётся» создаёт стимул вопрос
не записывать, лишь бы не вычеркнуть задачу из ближайшей работы.
**3. Что перестало быть важным.** Порциями по 5–8. Сперва то, что решается
фактом и не требует ничьего суждения (сделано попутно, отменено решением,
дублируется, симптомы одного дефекта), затем то, что решает человек (жива ли,
та ли цель, задача ли это ещё).
**4. Что важно сейчас.** Расстановка порядка — `move --after <слаг>` и
`move --first`. Разбирается **не весь беклог, а верх очереди**: первые три-пять
строк каждой секции. Ниже пятой строки порядок всё равно перестаёт что-либо
значить — до них дойдут после следующего груминга, и очередь к тому времени
будет другой.
## Приоритет: как его расставляют
**Вопрос ставится сравнением, а не оценкой.** «Насколько важна эта задача» не
имеет проверяемого ответа; «что из этих двух делают раньше» — имеет. Поэтому
очередь строится попарно и сверху: что первое, что после него.
Доводы, которые принимаются:
- **что сломано сейчас** — работоспособность обгоняет развитие, и это не правило
вкуса: сломанное дорожает само;
- **что разблокирует остальное** — задача, после которой можно взять три другие,
стоит раньше любой из трёх;
- **что дешевеет от того, что сделано** — работа рядом с только что тронутым
кодом стоит меньше, чем та же работа через квартал;
- **что дорожает от ожидания** — данные копятся, миграция усложняется, внешний
срок приближается;
- **цель, которую человек назвал следующей.**
Довод **записывается причиной** (`move --after <слаг> --reason …`). Порядок без
причины — это порядок, который на следующем груминге назначат заново с нуля.
**Цель и приоритет — независимые оси.** Очередь может идти поперёк целей, и это
законно: задачи одной цели не обязаны стоять подряд. Но если под целью годами
ничего не поднимается наверх — это разговор про цель, а не про очередь, и он
идёт на шаге 3.
## Документы устаревают тем же ходом работы
Груминг судит **задачи**, а не документы, и агентов канона не зовёт: они
принадлежат плагину `av-dev-docs`, и когда их звать — решает он.
Но повод назвать это здесь есть: беклог и документы протухают от одного и того
же — от сделанной работы. Пришёл на груминг и видишь, что с прошлого раза сделан
десяток задач, — скажи строкой, что документы стоит сверить
(`av-dev:doc-healthcheck`), и иди дальше. Плагина в проекте нет — сверять нечем,
и это тоже строка.
## Интерактив
- Вопросы — через `AskUserQuestion`, **не больше трёх за раз**. Порция в 58
задач обычно даёт больше трёх суждений: веди несколько итераций по ≤3, а не по
одному вопросу на задачу и не одним перегруженным запросом.
- К каждому варианту — **предварительное суждение, рекомендация первым
вариантом**: «предлагаю выкинуть, потому что …». Возразить дешевле, чем судить
с нуля.
- Всё, что решается фактом, решай сам и показывай списком в докладе.
- **Останавливайся на границе порции**, даже если «ещё чуть-чуть осталось».
Между порциями — промежуточный доклад.
Примеры итераций, отбор порции, храповик на залежавшихся —
[references/portions.md](references/portions.md).
## Стимулы, которые процесс создаёт
Правило, которое можно обойти в свою пользу, будет обойдено.
**Приёмщик и исполнитель совпадают, и это надо назвать вслух.** Задачу закрывает
тот же агент, который её и сделал. Груминг приёмкой не занимается — отдельного
ритуала у неё нет, — и настоящих опор остаётся две:
- **независимый отчёт ревью** — артефакт, написанный не исполнителем; при
конвейере `av-dev-code` это отчёт триажа в
`openspec/changes/archive/<id>/review/` (до архивации — `changes/<id>/review/`);
- **`reopen <слаг> --reason`** — закрытие не окончательно. Заметил на груминге,
что закрытая задача сделана не тем, чем обещала, — возвращай, это штатная
операция, а не скандал. Индексы под git: `git log -p` по беклогу показывает,
что и когда закрыто, потому что закрытие коммитится отдельным коммитом учёта.
Известные обходы:
- **Не записать вопрос** на задаче, которую хочется поднять наверх очереди.
Защита: вопросы верхних строк разбираются вне очереди порции, шагом 2.
- **Оставить всё как есть.** Груминг, на котором ничего не сдвинулось и ничего
не закрылось, — это не «беклог в порядке», а не проведённый груминг. Защита:
задача из верхних строк, которую и этот заход оставляет без изменений, **либо
двигается, либо получает записанную причину**, почему её держат.
- **Расставить порядок молча**, без доводов: тогда через месяц он неотличим от
случайного. Защита: причина у каждого движения и строка доклада.
- **Разобрать много и мелко** вместо немногого и важного: тридцать полей гигиены
вместо трёх решений о важности. Защита: гигиена — работа скилла `tasks` и
побочный продукт здесь; доклад называет **решения**, а не правки.
## Слоты проекта
Груминг не знает ни языка, ни сборки, ни CI. Проект дописывает в `CLAUDE.md`:
1. **Что считается сломанным** — какая красная проверка обгоняет развитие.
Не названо — спрашиваем человека, а не решаем сами.
2. **Необратимое** — что спрашивается всегда (тот же слот, что у скилла `tasks`;
дом один).
3. **Ориентир по размеру порции**, если он замерялся. Умолчание — 5–8 задач, и
это **ориентир, а не закон**.
Числа проекта (сколько задач приходит за месяц, каков прирост беклога) — предмет
наблюдения человека, а не константы этого скилла.
## Доклад
- Что просмотрено: N из M, сколько порций, по какому признаку отобраны.
- Вопросы: разобрано N, из них отвечено без человека N, снято тегов N.
- **Что перестало быть важным**: удалено как реализованное (со ссылками), ушло
без реализации (с причинами), понижено до сырья, слито, сменило тип или цель.
- **Что важно сейчас**: верх очереди по каждой секции — слаги в порядке, и по
каждому движению довод одной строкой.
- **Границы покрытия**: сколько задач не трогали и какие именно секции, теги или
цели остались — иначе доклад читается как «беклог разобран».
- `tasks.py check` после правок — результат строкой.
## Чего этот скилл не делает
Не пишет код и не выполняет задачи. Не заводит и не переоформляет записи сам по
себе — формат и содержимое ведёт `tasks` (груминг зовёт его операции). Не решает
за человека, что важно: он готовит развилки и рекомендует. Не принимает
закрытые задачи отдельным ритуалом — `reopen` есть, момента у него нет. Не судит
документы проекта — это плагин `av-dev-docs`.
@@ -0,0 +1,163 @@
# Порции, разбор и расстановка
Процедура шагов 2–4 груминга. Рамка и правила — [SKILL.md](../SKILL.md).
Начинается всё с `tasks.py check``check --fix`, если дрейф накопился) —
результат идёт строкой в доклад.
## Шаг 2. Разбор вопросов
`tasks.py list --questions` — всё, что накопилось. Порядок по каждому вопросу:
1. **Проверь, не отвечен ли он уже** — решением, документом, соседним
изменением, самим ходом сделанной с тех пор работы. Отвеченный вопрос не
выносится человеку: это самая частая находка и она не требует ничьего
решения.
2. **Сформулируй развилку** с вариантами и последствием каждого, рекомендация —
первым вариантом.
3. **Вынеси пачкой** через `AskUserQuestion`, не больше трёх за раз.
4. **Запиши ответ в тело задачи, опустоши раздел «Вопросы»**, сними тег
(`edit <slug> --rm-tag question`), **перепиши «зачем»**: «Решено: …» на вопрос
«почему это лежит в беклоге» уже не отвечает. Опустошение раздела — не
уборка, а условие взятия: правило и причина в скилле `tasks`,
[references/task-format.md](../../tasks/references/task-format.md).
**Вопросы на верхних строках очереди разбираются вне очереди порции** — здесь
же, даже если сама задача в порцию переоценки не попала. Иначе правило «задача с
открытым вопросом в работу не берётся» создаёт стимул вопрос не записывать, лишь
бы не вычеркнуть задачу из ближайшей работы.
## Шаг 3. Что перестало быть важным
Цель — выкинуть то, что перестало быть задачей, и вернуть остальному честное
состояние. Не «пересмотреть всё», а «пересмотреть порцию до конца».
### Порция и правило остановки
- **5–8 задач за порцию.** Размер обоснован усталостью, а не пропускной
способностью, и менять его не надо — **надо брать несколько порций**.
- **Отбор порций по порядку:**
1. **свежее** — заведённое с прошлого груминга: оно ещё не проходило ни одной
проверки на нужность. Свежесть меряется git'ом, как и залежалость, — датой
появления файла в истории;
2. дальше **по залежалости**`list --stale`;
3. по потребности — одна секция целиком, один тег (партия ревью), одна цель
(`--goal`), список от человека.
- **Останавливайся на границе порции**, даже если «ещё чуть-чуть осталось».
Между порциями — промежуточный доклад.
### Что делать с каждой задачей
Сперва то, что не требует ничьего решения:
1. **Проверь, не сделано ли уже.** Задача, реализованная попутно в соседнем
изменении, — самая частая находка. Смотри код, документацию, историю коммитов
по ключевым словам. Удаление «как реализованной» деструктивно и без следа
`REJECTED.md` реализованные не пишутся), поэтому порог улики жёсткий:
`close <slug> --implemented` только имея **конкретный коммит или строку
документа**, закрывающие задачу, и ссылка идёт в доклад. Есть лишь косвенные
признаки — не удаляй сам, вынеси в пачку вопросов. Сделана частично → задача
сжимается до остатка: тело правишь редактором, заголовок и «зачем» — через
`edit`.
2. **Проверь, не отменена ли решением.** Документ, ADR или архивное изменение
мог закрыть вопрос иначе — тогда `close <slug> --reason "<ссылка на
решение>"`. Задача закрывается не только коммитом.
3. **Проверь пересечения.** Две задачи об одном — содержимое в одну, вторую
`close <slug> --reason "слита с <другой-слаг>"`. Смотри **шире порции**:
интейк дедуплицирует новое против существующего, но никогда не пересматривает
уже лежащее, и две задачи с одной причиной могут лежать рядом месяцами.
4. **Пере-кластеризуй по общей причине.** Несколько задач, оказавшихся симптомами
одного дефекта, сливаются в одну — это находка, которую интейк дать не мог.
5. **Гигиена полей** — протухшее «зачем», вопрос в прозе, снятый ответ, свойство
репозитория в рамках, предписание процесса в теле, тип, разошедшийся с
задачей, границы вместо реализации в разделе «Затрагивает». Список и правила —
в скилле `tasks`. **Груминг — то самое место, где беклог добирает тип и
разделы его схемы:** требовать их на входе значило бы выгонять в заметки то,
что должно лежать задачей, а к взятию в работу они уже обязательны (`ready`).
Блок здоровья `check` печатает, сколько записей готово к взятию, — по этому
числу и видно, добрал ли груминг.
Гигиена — **побочный продукт, а не предмет**. Тридцать полей вместо трёх
решений о важности означают, что груминг не состоялся.
Затем — то, что решает человек:
6. **Жива ли она вообще.** Контекст мог измениться: ушла зависимость, отпал
сценарий, обошли иначе. Здесь и звучит вопрос, выкидывать ли.
7. **Та ли цель — и нужна ли она вообще.** `feature`, которой не находится цель,
— кандидат на выход: новая возможность вне цели это возможность, которой никто
не заказывал. Операционной задаче (`fix`, `chore`, `research`) цель не нужна,
и выдумывать её здесь не надо.
**Отменяется и сама цель** — когда замысел оказался неверен, а не когда
задача выбрала не ту. Тогда порция расширяется до всех задач этой цели: каждую
либо закрыть своей причиной, либо перевесить на другую цель, и только потом
закрыть цель. Порядок и почему он такой —
[task-goal.md](../../tasks/references/task-goal.md#отменённая-цель--сперва-задачи-потом-цель).
8. **Задача ли это по-прежнему.** Не проходит `ready` по существу, а не по
недописанным разделам → `edit <slug> --type research` и опустошённый раздел
«Вопрос», то есть сырьё; дальше штурм. Разрослась → это несколько задач под
той же целью, дальше декомпозиция.
9. **Не подешевела ли она.** Сделанная с прошлого раза работа меняет цену
**других** задач: рядом с только что тронутым кодом та же работа стоит меньше.
Это довод и на шаге 4 — задача, внезапно подешевевшая, поднимается в очереди
не потому, что стала важнее, а потому, что окно открыто.
### Храповик на залежавшихся
Сильно залежавшаяся задача — сигнал сама по себе: её либо ни разу не собирались
делать, либо нечем взять. Измеряй наблюдаемым — датой последней правки из git
(`list --stale` ставит такие первыми); счётчик «сколько грумингов пережила»
нигде не хранится.
Задача из верхних строк `--stale`, которую и этот заход оставляет без изменений,
**либо двигается (меняет цель, поднимается в очереди, уходит с причиной), либо
остаётся с явно записанной причиной**, почему её держим (`move <slug> --reason
…` — без `--section` секция берётся текущая). Молчаливое «оставить как есть» на
давно неподвижной задаче — это решение не принимать решение; запись причины
превращает его в осознанное и не даёт тому же вопросу всплыть на следующем
груминге.
## Шаг 4. Что важно сейчас — расстановка
Разбирается **верх очереди**, а не весь беклог: первые три-пять строк каждой
секции. Ниже пятой строки порядок всё равно перестаёт что-либо значить.
1. **Покажи текущий верх**`list --index backlog`, по секциям, в том порядке,
в каком строки лежат. Плюс состояние проекта из роадмапа: секция `Готово`
отвечает на «где мы», `Запланировано` — на «куда шли».
2. **Спрашивай сравнением, а не оценкой.** «Что из этих двух делают раньше»
имеет проверяемый ответ, «насколько важна эта задача» — нет. Веди попарно и
сверху: что первое, что после него.
3. **Двигай командой, с причиной**`move <slug> --after <другой> --reason …`
или `move <slug> --first --reason …`. Довод берётся из перечня в
[SKILL.md](../SKILL.md#приоритет-как-его-расставляют): сломано сейчас,
разблокирует остальное, дешевеет от сделанного, дорожает от ожидания,
названная цель.
4. **Проверь верх на готовность**`tasks.py ready <слаг> …` по первым строкам.
Задача, стоящая первой и не проходящая `ready`, — это очередь, которая врёт:
взять её нельзя. Либо дописывается здесь же, либо уступает место.
Пример одной итерации:
> **Верх секции «Игра», сейчас в таком порядке:**
> `board-render-once` · `draw-before-full-board` · `move-parse-strict`
>
> 1. Что делаем первым?
> - `draw-before-full-board` *(рекомендую)* — ничья объявляется на неполном
> поле: игра врёт о результате, это сломано сейчас
> - `board-render-once` — печать поля дублируется; мешает всякой правке
> отрисовки, то есть разблокирует остальное
> - оставить как есть
> 2. `move-parse-strict` — третьей или выше?
> - Оставить третьей *(рекомендую)* — ошибка ввода видна игроку сразу
> - Поднять второй: тот же разбор трогает `board-render-once`, окно открыто
Каждый вариант несёт причину — ту самую, что уедет в `--reason`.
## Что делать, если разбирать нечего
Беклог пуст или в нём три задачи и все живые — груминг кончается за минуту, и
это законный исход. Скажи строкой: очередь такая-то, сдвигать нечего. Придумывать
работу, чтобы груминг «состоялся», — ровно тот ритуал без выгоды, от которого
процесс избавлялся.