форма записи: заголовок отвечает на вопрос своего типа
Обкатка скилла tasks на выдуманном проекте — консольные крестики-нолики на JavaScript, каталог заведён с нуля тем же скриптом. Форма вылезла раньше содержания, и правки все про неё. Заголовок отвечает на вопрос типа записи, и форм три: цель — утверждение о возможности, задача — глагол в неопределённой форме (допускается «не» перед ним), идея — назывное, без обещания. Причина не стилистическая: описательный заголовок называет состояние, а из состояния не видно, чего от работы ждут — «Ничья объявляется, пока клетки есть» одинаково читается как жалоба и как задание. Отсюда же разница индексов: роадмап — список возможностей, беклог — список работ, и перепутанные формы делают каждый похожим на другой. Механизировано ровно то, что механизируется: check считает заголовки, где первое слово не на -ть/-ти/-чь, и печатает число в блоке здоровья. Замечанием на файл нельзя — эвристика грубая, а на 97 записях двух живых проектов это поток одинаковых строк, после которого пропускают весь блок. Годность формулировки судит отдельный агент task-wording, а не чек-лист в скилле: сейчас формулировку пишет и проверяет один агент в одном контексте, а самопроверка текста слабее всего там, где формулировка казалась удачной при написании. Он ничего не правит — возвращает готовые формулировки, и заголовок с «зачем» показываются человеку, потому что по ним задачу выбирают. Ничего из того, что ловит tasks.py check, он не трогает намеренно: это был бы второй дом для правила. Заголовки секций — с прописной, после заголовка пустая строка, во всех индексах. Канонические имена стали Готово | Запланировано | Направления | Разработка (англ. Done | Planned | Directions | Tooling), сверка везде по нижнему регистру, так что старые индексы читаются по-прежнему. Отбивка живёт на записи, а не на вставке: через Plan.index проходит каждая правка индекса, а мест вставки три. Имя секции принадлежит заголовку индекса, файл на неё только ссылается. Это разрешает единственную неоднозначность починки — расхождение в одном регистре правится в пользу заголовка. Без него переезд на канон оставил бы «Готово» в роадмапе и «готово» в каждом файле цели, и свести это было бы некому. Регистр правится только у канонических секций: имена секций беклога выбирает проект. Обкатка нашла два дефекта, которых не находили ни линтеры, ни свои проверки. Вставка в пустую секцию съедала отбивку перед следующим заголовком — пропуск пустых строк теперь идёт только до первой непустой. Мета, разорванная пустой строкой, теряла поля молча: check видел лишь следствие («без рода работы») и советовал edit --kind, который дописывал второе такое же поле. Поле меты в теле стало ошибкой с названной причиной, и --fix её намеренно не чинит — какое из двух значений верное, знает человек. DECISIONS тема 20 (ЕЕЕ–ККК, следствия 82–85), changelog канона v3 пополнен двумя пунктами и двумя шагами переезда, TODO — два шага для healthlog и jellybit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -71,22 +71,28 @@ docs/tasks/
|
||||
|
||||
| Секция | Англ. | Что в ней |
|
||||
| --- | --- | --- |
|
||||
| `готово` | `done` | достигнутые цели — строкой с датой, **без ссылки на файл**: файл удалён, поведение живёт в спеках |
|
||||
| `запланировано` | `planned` | очередь значима и обосновывается прозой рядом |
|
||||
| `направления` | `directions` | очереди нет, тянутся долго |
|
||||
| `разработка` | `tooling` | инструмент и процесс — не возможности приложения, и потому отдельно |
|
||||
| `Готово` | `Done` | достигнутые цели — строкой с датой, **без ссылки на файл**: файл удалён, поведение живёт в спеках |
|
||||
| `Запланировано` | `Planned` | очередь значима и обосновывается прозой рядом |
|
||||
| `Направления` | `Directions` | очереди нет, тянутся долго |
|
||||
| `Разработка` | `Tooling` | инструмент и процесс — не возможности приложения, и потому отдельно |
|
||||
|
||||
**Секции роадмапа канонические, секции беклога — нет**, и разница не в любви к
|
||||
единообразию. У каждой секции роадмапа свой смысл, в первую пишет сам `close`, и
|
||||
роадмап, названный по-своему, читался бы только своим автором. Секции беклога
|
||||
(`ядро`, `инфра`) смысла не несут — это полки, и остаются делом проекта.
|
||||
(`Ядро`, `Инфра`) смысла не несут — это полки, и остаются делом проекта.
|
||||
|
||||
Отсюда три правила, которые проверяет `tasks.py check`: **состав закреплён**
|
||||
(чужая секция — ошибка, а не вольность), **все четыре обязаны быть** (нет
|
||||
секции — нет ответа на её часть вопроса), **язык один на весь индекс**.
|
||||
`--roadmap-sections` у `init` нет: выбирать нечего.
|
||||
|
||||
Оговорка про `разработка`: слово `окружение` сюда не годится — в
|
||||
**Заголовок секции — с прописной, после него пустая строка.** Во всех индексах
|
||||
одинаково, включая секции беклога, которые проект называет сам. Написание
|
||||
канонических секций правит `check --fix` (заодно и ссылку на секцию в мете
|
||||
файлов: имя секции принадлежит заголовку индекса, файл на неё только
|
||||
ссылается); отбивку он ставит везде.
|
||||
|
||||
Оговорка про `Разработка`: слово `окружение` сюда не годится — в
|
||||
`architecture.md` оно уже значит боевое окружение приложения, и одно слово в двух
|
||||
смыслах развело бы документы канона.
|
||||
|
||||
@@ -110,7 +116,7 @@ docs/tasks/
|
||||
всех наборов без отдельного журнала.
|
||||
|
||||
**У достигнутой цели запись остаётся, и это единственное исключение.** Файл
|
||||
удаляется так же, а строка переезжает в секцию `готово` с датой. Причина в том,
|
||||
удаляется так же, а строка переезжает в секцию `Готово` с датой. Причина в том,
|
||||
что цель — не работа, а **возможность**: «что приложение умеет» это половина
|
||||
вопроса, ради которого роадмап и открывают, и стирать её вместе с файлом значит
|
||||
оставить инструмент, отвечающий только «что осталось». Вторым домом это не
|
||||
@@ -172,9 +178,9 @@ stateDiagram-v2
|
||||
отведена отдельная секция роадмапа, чтобы они были видны в том же экране и при
|
||||
этом не читались как возможности продукта.
|
||||
|
||||
Секция выбирается так: очередь значима и обоснована прозой — `запланировано`;
|
||||
тянется долго и очереди не имеет — `направления`; не про приложение —
|
||||
`разработка`; в `готово` кладёт сам `close`.
|
||||
Секция выбирается так: очередь значима и обоснована прозой — `Запланировано`;
|
||||
тянется долго и очереди не имеет — `Направления`; не про приложение —
|
||||
`Разработка`; в `Готово` кладёт сам `close`.
|
||||
|
||||
- **Список задач цели выводится, а не хранится.** В теле цели — зачем она и что
|
||||
считается её завершением; перечня задач там нет. Он был бы третьим индексом и
|
||||
@@ -184,7 +190,7 @@ stateDiagram-v2
|
||||
- **Статус цели выводится.** Цель достигнута, когда у неё не осталось открытых
|
||||
задач; `[x]`/`[~]` руками не ведутся, а `close` цели с живыми задачами
|
||||
скрипт запретит. Достижение — `close <цель> --implemented`: файл удаляется,
|
||||
строка с датой переезжает в `готово`. Ошиблись — `reopen` вернёт файл и
|
||||
строка с датой переезжает в `Готово`. Ошиблись — `reopen` вернёт файл и
|
||||
**снимет строку достигнутого**, чтобы роадмап не утверждал того, чего нет. Единственная оговорка: цель без задач неотличима — «ещё не
|
||||
разобрана» или «всё закрыто». Различает **тег `decomposed`** в мете
|
||||
цели: он ставится, когда цель разложена на задачи. Тег, а не строка в теле —
|
||||
@@ -248,8 +254,34 @@ stateDiagram-v2
|
||||
|
||||
## Как написана задача
|
||||
|
||||
Два требования к тексту, и оба про то, чтобы задачу можно было **оценить, не
|
||||
открывая код**.
|
||||
Три требования к тексту. Первое — про заголовок, два остальных про то, чтобы
|
||||
задачу можно было **оценить, не открывая код**.
|
||||
|
||||
**Заголовок отвечает на вопрос своего типа.** Вопросов три, поэтому и форм три:
|
||||
|
||||
| Тип | Отвечает на | Пример |
|
||||
| --- | --- | --- |
|
||||
| цель | что приложение будет уметь | Соперником может быть компьютер |
|
||||
| задача | что нужно сделать | Печатать поле одним куском кода |
|
||||
| идея | о чём она | Подсказка следующего хода |
|
||||
|
||||
Задача — **глаголом в неопределённой форме**, перед ним допускается «не»: «Не
|
||||
отбрасывать молча лишние символы в ходе», а не «Лишние символы молча
|
||||
отбрасываются». Описательный заголовок называет **состояние**, а из состояния не
|
||||
видно, чего от работы ждут: «Ничья объявляется, пока клетки есть» одинаково
|
||||
читается и как жалоба, и как задание, — и в списке, где решают «брать или не
|
||||
брать», это разные вещи. Идея формы действия не несёт **намеренно**: что делать,
|
||||
ещё неизвестно, и заголовок-действие обещал бы решённость, которой нет.
|
||||
|
||||
Из этого же правила растёт разница индексов: роадмап — список возможностей,
|
||||
беклог — список работ, и если заголовки перепутать формами, каждый из них
|
||||
начинает читаться как другой.
|
||||
|
||||
`check` считает заголовки не в форме действия и печатает **число** в блоке
|
||||
здоровья, не замечанием на файл: проверка эвристическая (первое слово на
|
||||
`-ть`/`-ти`/`-чь`), а беклог, заведённый до правила, не переоформляют «заодно».
|
||||
Годность формулировки — не машине: её смотрит
|
||||
[агент вычитки](#вычитка-формулировок).
|
||||
|
||||
**Функции и границы, а не намерения.** Задача называет, что система начнёт
|
||||
делать, и какие границы это трогает: эндпоинт или команду, таблицу и миграцию,
|
||||
@@ -428,6 +460,28 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
|
||||
обе половины остаются в одной ступени, потому что несокращаемый костяк проверок
|
||||
платится за каждую задачу отдельно.
|
||||
|
||||
### Вычитка формулировок
|
||||
|
||||
Язык записей судит **отдельный проход** — агент `task-wording`, а не тот же
|
||||
агент, который их только что написал: самопроверка текста слабее всего ровно
|
||||
там, где формулировка казалась удачной при написании.
|
||||
|
||||
Зовётся он **пачкой, а не на каждую запись**: после заведения нескольких задач,
|
||||
после разбора находок ревью и на переоценке. Ему передаётся список файлов и —
|
||||
если есть — паспорт, архитектура и конвенции проекта: по ним он отличает
|
||||
неизвестный термин от известного.
|
||||
|
||||
Он ничего не правит. Возвращает готовые формулировки, и их подставляет скилл:
|
||||
заголовок — `edit <слаг> --title …`, «зачем» — `edit <слаг> --why …`, остальное
|
||||
редактором. **Заголовок и «зачем» — это то, по чему задачу выбирают, поэтому
|
||||
менять их молча нельзя**: покажи предложенное пользователю вместе с тем, что
|
||||
было. Правки в теле (границы, критерии, язык) применяются сразу.
|
||||
|
||||
Что он смотрит и чего не смотрит — в его уставе; коротко: форму заголовка по
|
||||
типу записи, «зачем» вместо пересказа, англицизмы, неизвестные термины, границы
|
||||
вместо замысла, годность оракулов, предписания процесса. Всё, что ловит
|
||||
`tasks.py check`, он не трогает намеренно.
|
||||
|
||||
### Гигиена полей
|
||||
|
||||
Правится по ходу любой операции, которая задачи касается (но не «заодно» по
|
||||
@@ -479,7 +533,7 @@ python3 $tk adopt scan --from … | apply --plan … # разовая адап
|
||||
канон, а не по одному на каталог. Неизвестный ключ — код 3 на любой команде,
|
||||
так что лишнее слово в этом объекте останавливает работу с задачами целиком.
|
||||
- **Секции беклога** берутся из заголовков `##` индекса как есть; их количество
|
||||
и названия — дело проекта (умолчание `ядро` / `инфра`). **В конфиге их нет** —
|
||||
и названия — дело проекта (умолчание `Ядро` / `Инфра`). **В конфиге их нет** —
|
||||
второй список разошёлся бы с заголовками молча.
|
||||
|
||||
### Вызов из другого плагина
|
||||
|
||||
Reference in New Issue
Block a user