канон 4: тип записи стал единственной осью и задаёт схему

Осей было две — тип записи (goal/idea/task) и род работы (kind:<род>
тегом), — и ортогональность у них была фальшивой: из двенадцати клеток
произведения законны шесть. У цели род запрещён, у задачи обязателен, у
идеи пуст и на практике не ставится. Плюс «алгоритм работы над записью
такого типа» крепится не к task, а к fix и research, то есть к роду:
ось, к которой пишется алгоритм, и была настоящим типом. Схлопнуто в
одну ось из пяти значений: goal | feature | fix | chore | research.

Тип idea упразднён отдельно и по другой причине: он значил не род
работы, а незаполненность, а состояние типом быть не может — оно
меняется по мере того, как запись дописывают, а тип меняют командой.
Теперь состояние выводится из заполненности: research без раздела
«Вопрос» это сырьё. В спринт не берётся, как и прежняя идея, лежит в
конце категории, отбирается list --raw.

Дом типа — поле меты «Тип» первой строкой, эмодзи в H1 производна.
Прежнее «отдельного поля типа нет: два места для одного факта
разъезжаются» отменено собственным аргументом: он был против префикса
плюс поля, а при переносе дома место остаётся одно. Эмодзи стоит в H1,
а не в строке индекса, чтобы инвариант «заголовок в индексе дословно»
остался нетронутым.

Поле места названо по типу: «Секция» у цели (часть роадмапа, состояние
очереди), «Категория» у задачи (полка домена, куда её вернёт sprint
drop). Одинаковое переименование закрепило бы конфляцию; какое поле
обязательно, решает тип — то самое, ради чего затевалась правка.

Два новых обязательных раздела выросли из правил, которые были записаны
и которые нечем было проверить. «Не воспроизводится — это research, а не
fix» стояло в каноне: теперь есть раздел «Воспроизведение». Приёмка
разведки — «записанный ответ, а не изменённый код» — тоже стояла, но
sprint take требовал от research два-пять критериев с оракулами, и они
писались ради проверки; вместо них «Вопрос» и «Куда ляжет ответ».

Сортировка «по важности» из заметок не взята: она требует, чтобы кто-то
важность поддерживал, а это приоритет, от которого отказалось правило 4.
Взято только «сырьё в конец категории» — этот порядок выводится из типа
и заполненности, а не назначается человеком, и потому проверяется
машиной.

TYPE_SCHEMA кормит и body_template, и schema_verdict: иначе add кладёт
то, на чём sprint take потом откажет. check --fix мигрирует за один
проход — kind:/[goal]/[idea] в поле «Тип», эмодзи в заголовок, «Секция»
→ «Категория», сырьё в конец. Тип, которого неоткуда взять, не
угадывается: feature от chore машина не отличает, такие записи уходят в
НЕОДНОЗНАЧНО поимённо.

Попутно закрыт класс отказов в --fix: шагов, правящих мету, стало пять,
и второй, перечитавший файл с диска, стирал правку первого. Общий
stage() поверх отложенных правок; до этого корректность держалась на том,
что шагов было мало.

Устав на тип отдельным файлом — references/task-<тип>.md, пять штук:
схема, алгоритм, что видит машина и что человек. Агент task-form получил
правило «тип сходится с тем, что в записи написано» с проверяемыми
расхождениями.

Обкатано на демо-наборе из 13 записей: миграция за один проход, второй
прогон даёт ноль починок; fix без «Воспроизведения» и сырьё в спринт не
идут, годная feature берётся.

DECISIONS тема 27 (ААББ–ЛЛММ, следствия 101–104).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
av
2026-08-05 10:00:05 +03:00
co-authored by Claude Opus 5
parent 069205ac69
commit 228b6c7eee
18 changed files with 1521 additions and 511 deletions
@@ -23,8 +23,11 @@
- **Находка со свидетельством**, отложенная к исполнению → **задача**.
Свидетельство и последствие переносим в тело — это её «почему», то самое, что
переживает запись.
- **Находка без свидетельства / низкой уверенности** → **идея** (`[idea]`), а не
задача. Её судьба — штурм, где либо найдётся подтверждение, либо она уедет в
- **Находка без свидетельства / низкой уверенности** → **сырьё**: `research`, у
которого раздел «Вопрос» и есть недостающее свидетельство («при каких условиях
это воспроизводится»). Не `fix`: без `Воспроизведения` его в спринт не
возьмут, и правильно — чинить нечего, пока непонятно, что ломается. Судьба
сырья — штурм, где либо найдётся подтверждение, либо оно уедет в
`REJECTED.md`.
- **Уже починено по ходу ревью** → **ничего**. Починенное не заводим.
- **Развилка, решённая при ревью** → ничего; решённая «потом» → задача с
@@ -44,13 +47,13 @@
4. **Разложи по целям — там, где цель нужна.** Большинство находок ревью это
`fix` и `chore`, и **цель им не требуется**: они служат работоспособности, а
не направлению, и в спринт входят помимо его цели. Придуманная им цель —
ровно то враньё, от которого спасает род работы.
ровно то враньё, от которого спасает тип.
Цель обязательна у находки, которая оказалась **новой возможностью**
(`kind:feature`): нашлось поведение, которого никто не заказывал, и его надо
(`feature`): нашлось поведение, которого никто не заказывал, и его надо
либо заказать целью, либо убрать. Подходящей цели нет — заведи её
(`add --type goal --section Направления`) в том же проходе.
5. **Покажи карту до создания файлов.** Кластер → задача / идея / строка в
5. **Покажи карту до создания файлов.** Кластер → задача / сырьё / строка в
пакетный файл / уже заведено / отброшено, и под какую цель — пачкой через
`AskUserQuestion`. Это тот же барьер, что и «три кандидата» в интейке из
диалога: массовое заведение файлов без подтверждения — ровно тот отказ, ради
@@ -60,11 +63,12 @@
6. **Заводи утверждённое** через `tasks.py add`, с тремя добавками:
- **тег партии** — `--tag review-ГГГГ-ММ-ДД` (или `audit-<тема>`), чтобы весь
заход разбора поднимался одной командой `list --tag …`;
- **род работы** — `--kind`. У находок ревью он **не по умолчанию `fix`**:
починкой считается расхождение с заявленным поведением, а находка «этого
свойства никто не заказывал» — это `feature`, находка «не знаем, как
поведёт себя драйвер» — `research`. Род, розданный оптом, врёт ровно там,
где по нему потом отбирают;
- **тип** — `--type`, и он **не по умолчанию `fix`**: починкой считается
расхождение с заявленным поведением, а находка «этого свойства никто не
заказывал» — это `feature`, находка «не знаем, как поведёт себя драйвер» —
`research`. Тип, розданный оптом, врёт ровно там, где по нему потом
отбирают, **и требует не тех разделов**: каждому `fix` придётся заполнить
`Воспроизведение`, а у находки без свидетельства его нет;
- **провенанс в теле** — кто нашёл, каким проходом, с каким свидетельством.
Без него через месяц не отличить проверенную находку от догадки.
7. `tasks.py check`.
+10 -5
View File
@@ -57,10 +57,10 @@
через квартал вопрос «куда делась задача X» отвечается строкой со ссылками на
наследников, а не археологией git;
- родитель осмыслен как **возможность**, а не как шаг → это цель. Тип на месте
не меняется (цель живёт в другом индексе): заводится `[goal]` в `ROADMAP.md`,
не меняется (цель живёт в другом индексе): заводится `--type goal` в `ROADMAP.md`,
части получают `--goal <новый слаг>`, родитель закрывается с причиной-ссылкой.
**Промежуточного зонтика между целью и задачей нет.** Тип `[epic]` упразднён:
**Промежуточного зонтика между целью и задачей нет.** Тип `epic` упразднён:
роль зонтика играет цель, а слишком крупный шаг дробится на шаги помельче под
той же целью. Если частям нужен общий заголовок — значит у них общая
возможность, и её надо назвать целью, а не заводить временный тип.
@@ -73,10 +73,15 @@
спринт продолжается остальными. Части заводятся сразу под той же целью, но в
текущий набор **не добавляются** — набор заморожен.
## Мозговой штурм идеи
## Мозговой штурм сырья
Идея (`[idea]`) не проходит тест «готова к взятию»: неясно, что именно делаем.
Штурм проясняет — и это **generative-операция, а не applicative**.
Сырьё — запись типа `research`, у которой раздел «Вопрос» пуст: она не проходит
тест «готова к взятию», потому что неясно, что именно делаем. Штурм проясняет —
и это **generative-операция, а не applicative**.
Исход штурма и есть заполненный «Вопрос» (тогда разведку можно брать в спринт)
или набор задач с типами, которые из ответа следуют. Третий законный исход —
`close --reason`.
Applicative-штурм («перечисли задачи, следующие из идеи») выдаёт очевидное:
перечисляется то, что уже видно в формулировке. Ценное — на уровень выше.
@@ -0,0 +1,60 @@
# 🧹 `chore` — обслуживание, наблюдаемое поведение не меняется
Зависимости, сборка, перенос, чистка, оснастка. Отвечает на **«что нужно
сделать»**, глаголом в неопределённой форме.
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
Здесь только то, что у этого типа своё.
## Схема
| | |
| --- | --- |
| Заголовок отвечает на | что нужно сделать |
| Обязательные разделы | `Затрагивает`, `Критерии приёмки` |
| Допустимые сверх того | `Рамки`, `Вопросы` |
| Поле места | **Категория** — полка домена беклога |
| Цель (`goal:<слаг>`) | нет: цель — это возможность, а здесь её не появляется |
| Индекс | `BACKLOG.md``SPRINT.md` |
| Берётся в спринт | да |
## Адресат — разработчик, и это законно
Тест готовности спрашивает «что станет наблюдаемо иначе». У `chore` ответ
адресован **разработчику**, а не пользователю: «перестанет собираться два раза»,
«уедет последний вызов устаревшего API», «проверки гоняются одной командой».
Это ответ, а не отговорка.
**У `chore` тест готовности слабее честно, а не молча.** Пока типа не было,
такие задачи либо не заводились вовсе, либо формулировались как выдуманная
пользовательская польза — и то и другое хуже, чем сказать прямо, для кого работа.
Отсюда же граница: если после задачи меняется то, что видит пользователь, — это
не `chore`. Тип, оставшийся от первой формулировки, врёт ровно там, где по нему
отбирают.
## Алгоритм
1. **Проверить, что поведение не меняется.** Меняется — это `feature` или `fix`,
и у неё другие требования (цель, воспроизведение).
2. **Назвать, что перестанет мешать** — одной фразой, адресуясь разработчику.
«Прибраться в модуле X» ответом не является: непонятно, что изменится.
3. **Назвать границы** в `Затрагивает`. У обслуживания они часто не в коде:
конфиг и его образцы, версия зависимости, команда сборки, файл CI. Границей
считается то, у чего есть внешняя сторона и цена изменения.
4. **Написать критерии приёмки** — 2–5 утверждений с оракулами. У `chore`
оракул обычно самый дешёвый из всех типов: команда, которая раньше падала
или требовала трёх шагов, теперь отрабатывает одним.
5. **Проверить, что это не «заодно».** Обслуживание любит склеиваться в пачку
(«обновить зависимости и переписать сборку и убрать мёртвый код»). Не
мерджится порознь — это несколько задач ([split.md](split.md)).
6. **Цель не проставлять.** `chore` служит работоспособности, а не направлению,
и в набор спринта входит помимо его цели. Работа по сопровождению проекта
при этом видна в роадмапе — секцией `Сопровождение`, но целью не становится.
## Что видит машина, а что человек
`check` и `sprint take` смотрят на **наличие непустого** `Затрагивает` и на
**число** критериев — ровно то же, что у `feature`. Разница между типами здесь не
в строгости проверки, а в том, **кому адресован ответ** на «что станет
наблюдаемо иначе», — и это судит человек.
@@ -0,0 +1,63 @@
# ✨ `feature` — снаружи появляется то, чего не было
Задача, после которой наблюдаемое поведение меняется в сторону новой
возможности. Отвечает на **«что нужно сделать»** и пишется глаголом в
неопределённой форме.
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
Здесь только то, что у этого типа своё.
## Схема
| | |
| --- | --- |
| Заголовок отвечает на | что нужно сделать («Печатать поле одним куском кода») |
| Обязательные разделы | `Затрагивает`, `Критерии приёмки` |
| Допустимые сверх того | `Рамки`, `Вопросы` |
| Поле места | **Категория** — полка домена беклога |
| Цель (`goal:<слаг>`) | **обязательна** |
| Индекс | `BACKLOG.md``SPRINT.md` |
| Берётся в спринт | да |
**Цель обязательна, и это единственный тип, у которого так.** Новая возможность
и есть содержание цели: подходящей нет — либо она заводится, либо перед тобой не
`feature`. `sprint take` без цели откажет.
## Алгоритм
1. **Найти цель или завести её.** Задача без цели, названная функцией, — самый
частый способ пронести в беклог работу, которой никто не заказывал.
2. **Назвать границы** в разделе `Затрагивает`: эндпоинт или команда, таблица и
миграция, формат на диске, публичный тип пакета, внешний сервис. Названы
**границы, а не замысел**: «переписать хранилище на новый драйвер» — замысел,
`таблица points и её миграция` — граница. Проверяется вопросом «это можно
назвать до того, как решено *как* делать?».
3. **Написать критерии приёмки** — 2–5 проверяемых утверждений списком, у
каждого назван оракул. Не «работает корректно», а «повторный прогон даёт тот
же отпечаток — оракул: команда сверки».
4. **Сказать, какую строку «Завершения» цели задача двигает.** Одной строкой в
теле. Это защита от задачи «отрефакторить X»: она проваливается не потому,
что невидима снаружи, а потому, что не находит строки, к которой относится.
5. **Проверить, что задача одна.** Отвечается всё, но задача не делается одним
заходом и не мерджится целиком — это несколько задач под одной целью, дроби
сразу ([split.md](split.md)). Промежуточного зонтика между целью и задачей
нет.
6. **Реализация** — дело пайплайна проекта, не этого скилла. Закрывается
`close <слаг> --implemented`: файл и строка удаляются, суть переезжает в
`openspec/specs/` и документацию.
## Что видит машина, а что человек
`check` и `sprint take` смотрят на **наличие непустого** раздела `Затрагивает`,
на **число** критериев (меньше двух — отказ, больше пяти — замечание) и на цель.
Наличие оракула проверяется **эвристикой** — словом «оракул» в пункте.
Полнота перечня границ машине не видна: границу, которую забыли назвать, она от
отсутствующей не отличает. Настоящий оракул от слова «оракул» тоже не отличает.
Поэтому в докладе это называется как есть: «проверено число пунктов и наличие
границ, годность оракулов и полнота границ — глазами».
**Критерии — пол, но расхождение с ними есть дефект критериев.** Видишь, что
критерии закрыты, а суть задачи не достигнута — **правь критерии и возвращай
задачу**, а не держи невидимое сверх-требование: иначе исполнитель никогда не
знает, закончил ли, и мотивирован занижать критерии заранее.
@@ -0,0 +1,70 @@
# 🐞 `fix` — поведение расходится с заявленным
Задача о расхождении между тем, что система делает, и тем, что про неё заявлено
— в спеке, в инварианте `CLAUDE.md`, в критериях закрытой задачи. Отвечает на
**«что нужно сделать»**, глаголом в неопределённой форме, перед ним допускается
«не»: «Не отбрасывать молча лишние символы в ходе».
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
Здесь только то, что у этого типа своё.
## Схема
| | |
| --- | --- |
| Заголовок отвечает на | что нужно сделать |
| Обязательные разделы | **`Воспроизведение`**, `Затрагивает`, `Критерии приёмки` |
| Допустимые сверх того | `Рамки`, `Вопросы` |
| Поле места | **Категория** — полка домена беклога |
| Цель (`goal:<слаг>`) | необязательна |
| Индекс | `BACKLOG.md``SPRINT.md` |
| Берётся в спринт | да |
## `Воспроизведение` — раздел, которого нет у других типов
**Не воспроизводится — это `research`, а не `fix`.** Правило было записано и
раньше, но проверять его было нечем, и «починки» без единого шага повторения
уходили в спринт наравне с остальными. Раздел делает правило проверяемым: он
называет, **что сделать, чтобы расхождение проявилось, и что при этом видно
вместо ожидаемого**.
Пишется двумя частями, обе обязательны по смыслу:
- **шаги или вход** — команда, запрос, файл, последовательность действий;
- **что видно и что ожидалось** — «ввод `а1б2` ходит в `a1`, а должен быть
отвергнут с ошибкой».
Это не критерии приёмки и не дублирует их: воспроизведение описывает **сегодня**,
критерии — **завтра**. Пропущенное воспроизведение чаще всего означает одно из
двух: расхождение приняли на слово, или его вообще нет, а есть недовольство
поведением — и тогда это `feature`, а не `fix`.
## Алгоритм
1. **Воспроизвести.** Не удаётся — это `research`: заведи вопрос «при каких
условиях проявляется» и не притворяйся, что чинить есть что.
2. **Найти, чему поведение противоречит.** Спека, инвариант, критерий закрытой
задачи. Не противоречит ничему — это `feature`: поведение никогда и не было
заявлено, а тип, оставшийся от первой формулировки, врёт ровно там, где по
нему отбирают.
3. **Записать воспроизведение** — шаги и наблюдаемое против ожидаемого.
4. **Назвать границы** в `Затрагивает`: починка часто трогает больше, чем
кажется по объёму текста, и оценка систематически занижена именно здесь.
5. **Написать критерии приёмки** — 2–5 утверждений с оракулами. У починки
почти всегда есть парный критерий: **прежнее поведение не сломалось**
(«ввод `а1` принимается по-прежнему»). Без него починка чинит одно и ломает
соседнее.
6. **Цель не выдумывать.** `fix` служит работоспособности, а не направлению, и в
набор спринта входит помимо его цели. Придуманная цель — то же враньё, от
которого спасает тип.
7. **Записать дефект в журнал** `docs/review.md` с пометкой «проскочил / пойман
ревью». Проскочившие — эвал-сет для калибровки конвейера; пойманные с
оракулом — лучшая опора для прохода ревью: проектные, воспроизводимые,
однажды оказавшиеся правдой.
## Что видит машина, а что человек
`check` и `sprint take` смотрят на **наличие непустого** `Воспроизведения` и
`Затрагивает` и на **число** критериев. Годность воспроизведения — человеку:
шаги, по которым ничего не воспроизводится, машина от годных не отличает, и
делать вид, что проверено больше проверенного, хуже, чем не проверять вовсе.
+143 -85
View File
@@ -1,78 +1,125 @@
# Формат задач, целей и индексов
# Формат записей и индексов
Заголовок, мета-блок и строку индекса ставит `tasks.py add` — руками их не
пишут. Этот файл описывает, что именно скрипт создаёт и что проверяет `check`;
тело задачи (одну фразу, критерии, рамки, контекст) дописывает агент.
пишут. Этот файл описывает **общую форму** любой записи и то, что проверяет
`check`; тело дописывает агент.
## Файл задачи
Чем разделы тела отличаются от типа к типу, какой алгоритм у каждого типа и что
у него обязательно — **отдельным файлом на тип**:
| Тип | Файл | Одной строкой |
| --- | --- | --- |
| 🎯 `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) | обслуживание, поведение не меняется |
| 🔬 `research` | [task-research.md](task-research.md) | исход — знание, а не изменение |
## Файл записи
`items/<slug>.md`:
```markdown
# Тай-брейк при равной полноте
# 🐞 Не отбрасывать молча лишние символы в ходе
- **Секция:** Ядро — вышла из спринта: остаток писал нерешённое в журнал
- **Зачем:** порядок канонических форм берёт меньшее в 96% случаев — для накопительных это систематический недосчёт
- **Теги:** goal:merge-robustness, kind:fix, sprint:2026-08-03
- **Тип:** fix
- **Категория:** Ядро — вышла из спринта: остаток писал нерешённое в журнал
- **Зачем:** ввод «а1б2» ходит в a1 — игрок не видит, что ошибся, и винит игру
- **Теги:** goal:merge-robustness, sprint:2026-08-03
При столкновении точек выигрывает более полная, но при равной полноте побеждает
последняя доставка — а она систематически беднее первой.
Разбор хода читает первые два символа и молча выбрасывает остаток строки.
## Воспроизведение
Ввести `а1б2` в свой ход: программа ходит в `a1` и ничего не сообщает.
Ожидалось — отказ с ошибкой разбора.
## Затрагивает
Таблица `points` и её миграция; правило слияния в приёме доставки; формат
отпечатка состояния на диске. Публичного контракта не трогает.
Разбор строки хода; текст ошибки в выводе партии. Формат сохранения партии
не трогается.
## Критерии приёмки
- повторный прогон свёртки даёт тот же отпечаток состояния — оракул: команда сверки
- накопительная метрика за сутки не уменьшается после повторной доставки — оракул: тест
- в логе видно, какая из двух точек выиграла и почему — оракул: глазами по логу прогона
- ввод «а1б2» отвергается с ошибкой — оракул: тест разбора
- ввод «а1» принимается по-прежнему — оракул: тест разбора
## Рамки
Схема не трогается; данные только читаются; перезапуск сервиса допустим.
Схема не трогается; данные только читаются; перезапуск допустим.
Связано: решение о канонической форме содержимого.
```
- **Заголовок H1** — он же заголовок строки в индексе, дословно. Тип кодируется
префиксом `[goal]` / `[idea]`; обычная задача — без префикса.
Отдельного поля типа **нет**: два места для одного факта разъезжаются, а
префикс виден прямо в индексе, где и принимается решение «брать или не брать».
- **Форма заголовка — по типу записи.** Задача отвечает на «что нужно сделать»
и пишется глаголом в неопределённой форме («Печатать поле одним куском кода»,
«Не отбрасывать молча лишние символы»); цель — на «что приложение будет
уметь»; идея просто называет, о чём она. Почему так — SKILL.md, «Как написана
- **Заголовок H1** — он же заголовок строки в индексе, дословно. Начинается
**эмодзи типа**, и она **производна**: её ставит `add` и чинит `check --fix`
по полю меты. Второго дома у типа нет — эмодзи это его отображение, как
строка индекса это отображение файла.
- **Форма заголовка — по типу.** Цель отвечает на «что приложение будет уметь»;
`feature`, `fix` и `chore` — на «что нужно сделать», глаголом в неопределённой
форме, перед ним допускается «не»; `research` называет предмет разведки и
формы действия **не несёт намеренно**. Почему так — SKILL.md, «Как написана
задача». `check` считает заголовки не в форме действия и печатает число в
здоровье; годность формулировки смотрит агент `task-form`.
- **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательна
секция, причина после тире желательна (именно она объясняет, почему задача
здесь оказалась — в том числе «вышла из спринта: …»), «зачем» и теги
опциональны. Порядок свободный, поле в одну строку. Нераспознанные поля
сохраняются: скрипт правит свои и не трогает чужие.
- **Мета-блок** — список сразу после заголовка, **поле на строку**. Обязательны
**тип** и **место**, причина после тире желательна (именно она объясняет,
почему задача здесь оказалась — в том числе «вышла из спринта: …»), «зачем» и
теги опциональны. Нераспознанные поля сохраняются: скрипт правит свои и не
трогает чужие.
- **Тип — первым полем.** Он решает, что у записи вообще может быть: какие
разделы обязательны, нужна ли цель, берётся ли она в спринт, — и читается
раньше всего остального. Словарь **закрыт**: `goal` | `feature` | `fix` |
`chore` | `research`. Не подходит ни один — это сигнал, что в записи их два и
её надо разделить.
- **«Зачем» отвечает на «зачем нужна эта задача»** — состояние, остаток, боль.
Не пересказ задачи: пересказ уже есть по ссылке. Живёт здесь, а не только в
индексе: строка индекса его повторяет и производна от него, `check` сверяет,
`check --fix` восстанавливает пропавшую строку **вместе с ним**. Пока поле
лежало только в индексе, штатная починка дрейфа теряла его молча и
навсегда — а это единственное, по чему задачу выбирают, не открывая.
- **Тело** — одна фраза «что станет наблюдаемо иначе», затрагиваемые границы,
критерии приёмки, рамки, контекст, ссылки. Пишется на языке документации
проекта: предметно, без англицизмов, у которых есть русское слово, и без
терминов, которых нет ни в паспорте, ни в архитектуре, ни в конвенциях
(правило и его причина — в SKILL.md, раздел «Как написана задача»).
Мета **одной строкой через `·`** — прежняя форма. Она читается по-прежнему,
`check` называет её дрейфом, `check --fix` переписывает списком; поле `Хук`
при этом становится `Зачем`. Причина отказа от строки простая: с тремя полями
и длинным «зачем» строка уезжала за экран, а `·` приходилось запрещать в тексте
причины и самого «зачем».
- **Тело** — одна фраза «что станет наблюдаемо иначе», дальше разделы по схеме
типа. Пишется на языке документации проекта: предметно, без англицизмов, у
которых есть русское слово, и без терминов, которых нет ни в паспорте, ни в
архитектуре, ни в конвенциях (правило и его причина — в SKILL.md, раздел «Как
написана задача»).
Тело — не план реализации и не спецификация: принятое и реализованное переезжает
в документацию проекта, а файл задачи удаляется.
### Поле места: «Категория» и «Секция»
Поле называет, **где числится строка**, и имя у него **зависит от типа**:
| Тип | Поле | Значения | Что это |
| --- | --- | --- | --- |
| `goal` | **Секция** | `Запланировано`, `Направления`, `Сопровождение` | часть роадмапа: состояние очереди |
| прочие | **Категория** | секции беклога проекта (`Ядро`, `Инфра`, …) | полка домена, в которую задача вернётся из спринта |
Разные имена потому, что это **разные вещи**. У задачи поле переживает спринт:
`sprint drop` возвращает её именно туда. У цели оно называет не полку, а место в
очереди работ. Одно имя на два смысла и было конфляцией; `check` называет
несовпадение дрейфом, `check --fix` переименовывает.
Имя самого места принадлежит **заголовку индекса** — файл на него лишь
ссылается, и принадлежность сверяется по нижнему регистру.
### Прежние формы, которые читаются, но не пишутся
Всё это `check` называет дрейфом, а `check --fix` переписывает:
| Было | Стало |
| --- | --- |
| префикс `[goal]` / `[idea]` в H1 | поле **Тип** + эмодзи в H1; `[idea]``research` |
| тег `kind:<род>` | поле **Тип** (род работы стал типом) |
| поле **Секция** у задачи | поле **Категория** |
| поле **Хук** | поле **Зачем** |
| мета одной строкой через `·` | мета списком, поле на строку |
Единственное, чего `--fix` не делает сам, — **проставить тип записи, у которой
его неоткуда взять**: `feature` от `chore` машина не отличает, и подставленное
наугад значение врало бы ровно там, где по нему принимают решение. Такие записи
он называет поимённо пометкой `НЕОДНОЗНАЧНО`.
### Затрагивает
Перечень **границ**, которых изменение касается. Границей считается то, у чего
@@ -100,8 +147,8 @@
забыли назвать, она от отсутствующей не отличает. Раздела нет — отказ во взятии:
оценивать нечем.
**У идей раздела нет**как и критериев: границы становятся известны, когда идея
превращается в задачу.
**У `goal` и `research` раздела нет**у первой границы называют её задачи, у
второй они становятся известны, когда из разведки родятся задачи.
### Критерии приёмки
@@ -118,7 +165,9 @@
замечание: настоящий оракул от слова «оракул» машина не отличает, и делать вид,
что проверено больше проверенного, хуже, чем не проверять вовсе.
**У идей критериев нет — именно поэтому они идеи.**
**У `research` критериев нет** — её приёмка это записанный ответ, и описывается
она разделами «Вопрос» и «Куда ляжет ответ». **У `goal` их заменяет
«Завершение».**
**Критерии — пол, но расхождение с ними есть дефект критериев.** Если приёмщик
видит, что критерии закрыты, а суть задачи не достигнута, он **правит критерии и
@@ -129,16 +178,21 @@
### Рамки
Одна строка: чего касаться нельзя, что перезапускается, что считается
необратимым, трогается ли схема данных. **Свойства репозитория сюда не пишутся**
— номер последней миграции, версия зависимости, хеш: в лежалой задаче они
протухают молча и становятся ложной рамкой. Снимок берётся при постановке, а не
при заведении.
необратимым, трогается ли схема данных. Раздел **допустим у любого типа задачи и
ни у одного не обязателен**. **Свойства репозитория сюда не пишутся** — номер
последней миграции, версия зависимости, хеш: в лежалой задаче они протухают
молча и становятся ложной рамкой. Снимок берётся при постановке, а не при
заведении.
### Вопросы
Неразобранное решение человека живёт разделом `## Вопросы` **плюс тегом
`question`**. Раздел без тега или тег без раздела — дрейф, `check` о нём скажет.
Раздел `Вопросы` (о решении человека) и раздел `Вопрос` у `research` (предмет
разведки) — **разные вещи и разные слова**: первый блокирует взятие, второй его
разрешает.
**Судит факт, а не метка.** Отказ во взятии даёт **непустой раздел «Вопросы»**,
независимо от того, стоит ли тег: иначе забывший тег проходил бы, а поставивший
спотыкался — стимул ровно обратный записанному правилу. Тег производен: он нужен
@@ -158,13 +212,12 @@
## Файл цели
**Заголовок цели отвечает на «что приложение будет уметь».** Не область работ и
не имя подсистемы: не «Работа со слиянием», а «Исход слияния не зависит от
порядка доставки». Свойство поведения — тоже возможность.
Форма та же, разделы и алгоритм — [task-goal.md](task-goal.md).
```markdown
# [goal] Исход слияния не зависит от порядка доставки
# 🎯 Исход слияния не зависит от порядка доставки
- **Тип:** goal
- **Секция:** Направления
- **Теги:** decomposed
@@ -181,10 +234,6 @@
- **Задачи цели здесь не перечисляются.** Перечень даёт
`tasks.py list --goal <слаг>`; хранимый список стал бы третьим индексом и
поехал бы на первой же закрытой задаче.
- **Раздел «Завершение» — списком, а не абзацем.** Это признаки того, что
приложение уже умеет; **на строку «Завершения» ссылается задача**, объясняя,
какую часть возможности она двигает (см. тест готовности). Абзацем такая
ссылка не берётся, поэтому список.
- **Тег `decomposed`** отличает «цель ещё не разобрана» от «все её задачи
закрыты» — два состояния, у которых снаружи один и тот же признак: задач нет.
Пометка именно **тегом**, а не строкой в теле: только так она проверяется.
@@ -217,16 +266,18 @@
Строка везде одной формы:
```markdown
- [Заголовок дословно](items/slug.md) — зачем
- [🐞 Заголовок дословно](items/slug.md) — зачем
```
«Зачем» отвечает на «зачем нужна эта задача» одним предложением: состояние,
остаток, боль. Пересказ первого абзаца бесполезен — он уже есть по ссылке.
Эмодзи внутри квадратных скобок не украшение: заголовок копируется **дословно**,
и тип виден там, где решают «брать или не брать».
| Файл | Что отвечает | Секции |
| --- | --- | --- |
| `ROADMAP.md` | что приложение уже умеет и чего ещё не умеет | канонические и в этом порядке: `Запланировано`, `Направления`, `Сопровождение`, `Готово` (англ. `Planned`, `Directions`, `Operations`, `Done`) |
| `BACKLOG.md` | что **можно взять** — только задачи | секции проекта (по умолчанию Ядро/Инфра) |
| `BACKLOG.md` | что **можно взять** — только задачи | категории проекта (по умолчанию Ядро/Инфра) |
| `SPRINT.md` | какая цель и какой набор под неё | одна: «Набор» |
| `REJECTED.md` | что ушло без реализации и почему | — |
@@ -237,8 +288,15 @@
следующем `sprint start` и очищается на `sprint close`.
Секции — **единственные заголовки `##` в индексе**: любой другой `##` в
преамбуле проверка сочтёт секцией. Внутри секции беклога порядок значения не
имеет — порядка в беклоге нет вовсе.
преамбуле проверка сочтёт секцией.
**Порядка «по важности» внутри секции беклога нет** — «что делать дальше»
отвечает набор спринта. Единственный порядок, который есть, **производен от типа
и заполненности**: **сырьё** (`research` без раздела «Вопрос») стоит в конце
своей секции, потому что его не берут, и между берущимся оно каждый раз требует
открыть файл, чтобы это понять. Проверяет `check`, переставляет `check --fix`,
и человек этот порядок не назначает — иначе он был бы приоритетом, которого
здесь нет.
**Секции «блокеры» среди них нет.** Блокер — состояние, а не полка: он живёт до
ответа человека, а следы остаются вопросами в файлах задач распущенного спринта.
@@ -251,15 +309,14 @@
`REJECTED.md`, и по той же причине (файла уже нет, ссылаться некуда).
**Секции роадмапа закреплены** — состав, полнота, единство языка и **порядок**
проверяются `check`; секции беклога проект называет сам. Почему так — SKILL.md.
Порядок закреплён потому, что `Готово` копится: стоя первым, достигнутое
отодвигает за экран то, ради чего роадмап открывают чаще всего.
проверяются `check`; категории беклога проект называет сам. Почему так —
SKILL.md. Порядок закреплён потому, что `Готово` копится: стоя первым,
достигнутое отодвигает за экран то, ради чего роадмап открывают чаще всего.
**Заголовок секции пишется с прописной и отбивается пустой строкой с обеих
сторон** — во всех индексах, включая секции беклога, имена которых выбирает проект. Написание
канонических секций и отбивку правит `check --fix`; он же сводит написание
секции в мете файла с заголовком индекса — **имя секции принадлежит заголовку**,
файл на неё лишь ссылается, и принадлежность сверяется по нижнему регистру.
сторон** — во всех индексах, включая категории беклога, имена которых выбирает
проект. Написание канонических секций и отбивку правит `check --fix`; он же
сводит написание места в мете файла с заголовком индекса.
Индексы **производны**: расходятся с файлом — правим индексы (`check --fix`).
Строку руками не пишут.
@@ -295,19 +352,13 @@
## Теги
Единственный механизм разметки, потому что `list --tag` уже умеет отбирать по
ним порцию разбора. Отдельных полей меты под это не заводим.
Разметка сверх типа. Тип полем, потому что он один и обязателен; теги — потому
что их много и `list --tag` уже умеет отбирать по ним порцию разбора.
- `goal:<слаг>` — цель, которой служит задача. Обязателен **у `kind:feature`**:
- `goal:<слаг>` — цель, которой служит задача. Обязателен **у `feature`**:
новая возможность и есть содержание цели. У `fix`, `chore` и `research` его
может не быть — они служат работоспособности, а не направлению, и в набор
спринта входят помимо его цели.
- `kind:<род>` — род работы: `feature` | `fix` | `chore` | `research`. Словарь
**закрыт**, значение ровно одно. Обязателен у задачи (без него `sprint take`
откажет), у цели запрещён, у идеи необязателен. Ставится
`add --kind` / `edit --kind`; `--kind` заменяет прежнее значение, а не
добавляет второе. Смысл рода и почему он тегом, а не префиксом — в SKILL.md,
раздел «Род работы».
- `question` — в файле есть неразобранный раздел «Вопросы».
- `sprint:<слаг>` — задача заведена в этом спринте; по нему отбирается первая
порция разбора («урожай спринта»). **Ставится сам**: слаг спринта заводит
@@ -317,6 +368,9 @@
разбора — урожай прошедшего спринта».
- `decomposed` — на цели: разложена на задачи (см. «Файл цели»).
Тега `kind:<род>` больше нет: род работы стал типом. Оставшийся в файле `check`
называет дрейфом, а `check --fix` снимает, перенеся значение в поле «Тип».
Отбор — `list --tag a,b`: перечисленные через запятую теги требуются **все
сразу** (это И, не ИЛИ). Тег, которого нет ни у одной задачи, `list` называет
вслух: молчаливый ноль читается как «таких задач нет», а чаще это опечатка.
@@ -327,17 +381,20 @@
## Тест «готова к взятию»
Задача готова, если из файла отвечаются четыре вопроса:
Задача готова, если из файла отвечаются четыре вопроса. Первый и четвёртый —
общие, второй и третий у каждого типа свои и перечислены в его файле.
1. **Что станет наблюдаемо иначе**, когда она сделана — снаружи: пользователю,
владельцу сервиса или разработчику. «Отрефакторить X» — не ответ; «перестанет
ломаться Y при Z» — ответ. **У `kind:chore` адресат — разработчик, и это
ломаться Y при Z» — ответ. **У `chore` адресат — разработчик, и это
законно**: «уедет последний вызов устаревшего API» — ответ, а не отговорка.
Род объявлен как раз затем, чтобы такие задачи не выдумывали себе
Тип объявлен как раз затем, чтобы такие задачи не выдумывали себе
пользовательскую пользу.
2. **Каких границ это касается** — раздел «Затрагивает». Без него задачу нельзя
оценить: остаётся судить по длине текста.
3. **По чему видно, что закончено** — критерии приёмки с оракулами.
2. **Что известно про сегодня** — то, что тип требует знать до работы:
у `fix` это `Воспроизведение`, у `research` — `Вопрос`, у `feature` и
`chore` — `Затрагивает`.
3. **По чему видно, что закончено** — критерии приёмки с оракулами;
у `research` вместо них `Куда ляжет ответ`.
4. **Какую часть «Завершения» своей цели она двигает** — у задачи с целью.
Строкой: «двигает пункт 2 «Завершения» — накопительная метрика перестаёт
уменьшаться». Это и есть защита от задачи «отрефакторить X»: она проваливает
@@ -349,9 +406,10 @@
**У задачи без цели** (`fix`, `chore`, `research`) вопрос не задаётся: они
служат работоспособности, а не направлению.
Не отвечается первый, второй или третий вопрос → это **идея** (`[idea]`), её
место в штурме. Не отвечается четвёртый у `feature` → либо цель есть и не
проставлена, либо это не новая возможность.
Не отвечается первый, второй или третий вопрос → это ещё не задача, а **сырьё**:
тип `research` без раздела «Вопрос», место — конец секции, работа над ним —
штурм. Не отвечается четвёртый у `feature` → либо цель есть и не проставлена,
либо это не новая возможность.
Отвечается всё, но задача не делается одним заходом и не мерджится целиком →
это **несколько задач под одной целью**, дроби сразу. Промежуточного зонтика
@@ -0,0 +1,70 @@
# 🎯 `goal` — возможность приложения
Цель отвечает на **«что приложение будет уметь»**. Не область работ и не имя
подсистемы: не «Работа со слиянием», а «Исход слияния не зависит от порядка
доставки». Свойство поведения — тоже возможность.
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
Здесь только то, что у этого типа своё.
## Схема
| | |
| --- | --- |
| Заголовок отвечает на | что приложение будет уметь |
| Обязательные разделы | `Завершение` |
| Допустимые сверх того | — |
| Поле места | **Секция** — часть роадмапа |
| Цель (`goal:<слаг>`) | запрещена: цель и есть цель |
| Индекс | `ROADMAP.md`, и никогда `BACKLOG.md` или `SPRINT.md` |
| Берётся в спринт | нет — берутся её задачи |
Поле места у цели называется **«Секция»**, а не «Категория», и это не разнобой:
у задачи оно называет полку домена, в которую она вернётся из спринта, а у цели
— часть роадмапа, то есть состояние очереди. Одно имя на два смысла и было
конфляцией.
## «Завершение» — списком, а не абзацем
Это признаки того, что приложение **уже умеет**, и на строки этого раздела
ссылаются задачи цели: «двигает пункт 2 «Завершения» — накопительная метрика
перестаёт уменьшаться». Абзацем такая ссылка не берётся, поэтому список.
Отсюда же читается обратное и более полезное: **строка «Завершения», к которой
не относится ни одна задача, — незакрытая часть возможности**. Достаточность
набора задач видна из самой цели, а не из чьей-то памяти.
## Алгоритм
1. **Проверить, что это возможность, а не работа.** Сборка, проверки, выкладка,
мониторинг, дежурство на вопрос «что приложение будет уметь» не отвечают. Им
отведена секция `Сопровождение` — там они видны в том же экране и не читаются
как обещание продукта. Граница проходит по тому, **кто наблюдает**:
«приложение сообщает о своём состоянии» — возможность, «дежурный видит
состояние на одном экране» — сопровождение.
2. **Выбрать секцию.** Очередь значима и обоснована прозой — `Запланировано`;
тянется долго и очереди не имеет — `Направления`; про то, чем держат проект,
`Сопровождение`. В `Готово` кладёт сам `close`.
3. **Написать «Завершение»** — 2–5 наблюдаемых признаков списком. Пишутся до
декомпозиции: иначе задачи придумают себе цель задним числом.
4. **Разложить на задачи** и проставить им `goal:<слаг>`. Перечень задач в теле
цели **не хранится** — он был бы третьим индексом и поехал бы на первой же
закрытой задаче; выводит `tasks.py list --goal <слаг>`.
5. **Пометить `decomposed`.** Тег отличает «ещё не разобрана» от «все задачи
закрыты» — два состояния с одним внешним признаком. `check --fix` ставит его
сам цели, у которой задачи есть.
6. **Закрыть достигнутой**`close <слаг> --implemented`, когда не осталось
открытых задач. Файл удаляется, строка с датой переезжает в `Готово`. Скрипт
откажет, если задачи ещё живы.
## Что видит машина, а что человек
`check` считает цели, различает разобранные и пустые, ставит `decomposed`,
запрещает закрыть цель с живыми задачами и держит `Секцию` в согласии с
заголовком роадмапа. **Годность формулировки — не машине**: «возможность это или
область работ» решает [агент вычитки](../SKILL.md#вычитка-два-прохода-а-не-один).
Достигнутая цель **не исчезает**: «что приложение умеет» — половина вопроса, ради
которого роадмап открывают. Вторым домом поведения роадмап при этом не
становится: нормативное поведение живёт в `openspec/specs/`, роадмап отвечает,
**когда и в каком порядке** оно появилось.
@@ -0,0 +1,83 @@
# 🔬 `research` — исход работы знание, а не изменение системы
Ответ на вопрос, замер, разведка, проработка сырой мысли. Приёмка — **записанный
ответ**, а не изменённый код.
Общая форма записи (мета, слаг, строка индекса) — [task-format.md](task-format.md).
Здесь только то, что у этого типа своё.
## Схема
| | |
| --- | --- |
| Заголовок отвечает на | о чём разведка (предмет, а не действие) |
| Обязательные разделы | `Вопрос`, `Куда ляжет ответ` |
| Допустимые сверх того | `Рамки`, `Вопросы` |
| Поле места | **Категория** — полка домена беклога |
| Цель (`goal:<слаг>`) | нет |
| Индекс | `BACKLOG.md``SPRINT.md` |
| Берётся в спринт | да — **но только с заполненным «Вопросом»** |
**Критериев приёмки у `research` нет, и это не поблажка.** Критерии в форме
«оракул: тест» разведке натянуты: проверять нечего, пока ответа нет. Её приёмка
описывается раздельно — вопрос, на который отвечаем, и место, куда ляжет ответ.
**Заголовок формы действия не несёт намеренно.** Что делать, ещё неизвестно, и
заголовок-действие обещал бы решённость, которой нет. «Подсказка следующего
хода», а не «Сделать подсказку следующего хода».
## Этот тип вобрал прежний `[idea]`
Тип `idea` упразднён. Он значил не род работы, а **состояние незаполненности**
«первый, второй или третий вопрос теста готовности не отвечается», — а состояние
типом быть не может: оно меняется по мере того, как запись дописывают, а тип
меняют командой.
Теперь это состояние называется честно: **`research` без раздела «Вопрос» — это
сырьё**.
| | сырьё | разведка |
| --- | --- | --- |
| Раздел `Вопрос` | пуст или отсутствует | заполнен |
| `sprint take` | отказ | берёт |
| Место в секции беклога | **конец**, `check --fix` сносит туда сам | среди прочих |
| `tasks.py list --raw` | показывает | нет |
Порядка «по важности» в беклоге по-прежнему нет. Этот порядок **производен от
типа и заполненности**, а не назначен человеком, — потому его и проверяет машина,
и потому он не противоречит правилу «порядка нет, есть цель».
Сырьём заводится и **сырая функция**: «Подсказка следующего хода» — ещё не
`feature`, потому что неизвестно, что именно делать. Работа над ней — думание, и
её исход — либо задачи, либо отказ.
## Алгоритм
1. **Записать вопрос одной фразой.** Не тему, а вопрос: не «Разобраться с
выводом в терминалах», а «Какими символами рамки печатаются одинаково в
Терминале, iTerm и `tmux`». Вопроса ещё нет — запись заводится сырьём и
лежит в конце секции, пока вопрос не появится.
2. **Назвать, куда ляжет ответ**: `docs/research/<тема>.md`, ADR, тело этой
задачи. Место называется **заранее**, иначе ответ остаётся в переписке, а
через квартал разведку заказывают заново.
3. **Ограничить рамками**, если разведка может утечь: сколько времени, какие
источники, что заведомо вне.
4. **Провести разведку** и **записать ответ по названному адресу**. Числа — с
провенансом: с командой или условиями, которыми получены. Число без источника
проход ревью обязан читать как условие, а не как замер.
5. **Разложить исход на задачи** — если он их родил. Разведка кончается одним из
трёх: заведены задачи, записано знание, отказ. **Отказ — полноправный исход**:
«проверили, не проблема» экономит спринт.
6. **Закрыть**`close <слаг> --implemented`, когда ответ записан. Файл
удаляется: запись ответа и есть след, второго не нужно. Ушла без ответа —
`close --reason`, и строка уезжает в `REJECTED.md`.
## Что видит машина, а что человек
`check` и `sprint take` смотрят на **наличие непустых** разделов `Вопрос` и
`Куда ляжет ответ`, считают сырьё отдельной строкой здоровья и держат его в конце
секции. Годность вопроса — человеку: «вопрос это или тема» машина не различает,
и `check` о годности молчит намеренно.
Штурм сырья, дробление исхода на задачи и тест «части мерджатся порознь» —
[split.md](split.md).