хвост задачи: отражение молча, новое — по слову человека
Синк документации делил правки по документам, а делить их надо по роду. Отражение сделанного (вливание дельт, миграция, компонент в обзоре) пишется молча: без правки документ станет ложным. Новая запись и новая норма — ADR, конвенция, записка разведки, инвариант, периметр, дефект в журнале — только предлагаются, а пишет их третий такт шага 6 после слова человека. Реплика при этом одна на весь хвост: вопрос про урожай ревью переехал с шага 5 на шаг 6 и слился с предложениями синка — решение одно, «что из найденного переживёт задачу». Плановых стопов в сценарии решения стало ровно два, и оба про решения человека. Сверка документов получила счётчик: doc-healthcheck оставляет след ключом [healthcheck] last в .av-dev.toml, синк считает по нему задачи с прошлого прогона и говорит строкой. Прежде признак «десяток задач» держался в памяти, то есть не срабатывал. Журнал — тема 78.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doc-healthcheck
|
||||
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без происхождения) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:canon, язык документов — агент doc-wording."
|
||||
description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без происхождения) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Прогон оставляет след — ключ [healthcheck] last в .av-dev.toml, — и по нему синк документации считает, сколько задач сделано с прошлой сверки, и выдаёт сигнал строкой. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:canon, язык документов — агент doc-wording."
|
||||
---
|
||||
|
||||
# Здоровье документации
|
||||
@@ -20,7 +20,10 @@ check` и его скрипт; здесь начинается там, где к
|
||||
- **с прошлой сверки сделан десяток задач.** Документы протухают ровно от
|
||||
сделанной работы: переименованная цель сборки, ушедшая зависимость, второй
|
||||
способ делать то, что обзор объявил единственным, факт, дописанный в
|
||||
`architecture.md` и уже живущий в `CLAUDE.md`;
|
||||
`architecture.md` и уже живущий в `CLAUDE.md`. **Этот признак считается, а не
|
||||
вспоминается**: счёт ведёт синк документации по следу прошлого прогона и
|
||||
выдаёт строкой на каждой сделанной задаче (`av-dev:doc-sync`, раздел «Сигнал
|
||||
сверки»);
|
||||
- **вернулись к проекту после перерыва** — прежде чем опираться на написанное;
|
||||
- **перед тем как опереться на документ в решении**, если оно дорогое;
|
||||
- шагом `adopt` и шагом `upgrade` — их зовёт скилл `canon` сам.
|
||||
@@ -123,6 +126,28 @@ check` и его скрипт; здесь начинается там, где к
|
||||
прогоне. Класс ошибок, который повторяется, идёт в `docs/review.*`, раздел
|
||||
настройки, — там дом типовых ложноположительных.
|
||||
|
||||
## След прогона
|
||||
|
||||
**Последним шагом прогон правит `.av-dev.toml`** — ключ `last` в секции
|
||||
`[healthcheck]`: хеш коммита `HEAD` и дата комментарием рядом. Состав ключей —
|
||||
[канон](../canon/references/canon.md), раздел `.av-dev.toml`; правится **строка**,
|
||||
а не файл целиком.
|
||||
|
||||
**Без следа признак «десяток задач» не считается никем.** Так и было: сверку
|
||||
звали по памяти, то есть не звали — тот же прозаический триггер, что дал 6
|
||||
записей ADR на 43 изменения. След превращает признак в число, которое
|
||||
`av-dev:doc-sync` считает командой
|
||||
`git rev-list --count <last>..HEAD -- openspec/changes/archive` и говорит вслух
|
||||
на каждой задаче.
|
||||
|
||||
Ключ **необязательный и заводится сам** — первым же прогоном сверки; проекту для
|
||||
этого делать нечего. Его отсутствие значит «сверки не было ни разу», и синк
|
||||
говорит это отдельной строкой.
|
||||
|
||||
**Позвал одного агента из двух — след всё равно ставится, но в докладе назван
|
||||
неполным.** Иначе следующая сверка отсчитывалась бы от прогона, который смотрел
|
||||
половину.
|
||||
|
||||
## Доклад
|
||||
|
||||
- **Кого позвал** — обоих или одного, и почему одного.
|
||||
@@ -147,3 +172,5 @@ check` и его скрипт; здесь начинается там, где к
|
||||
- **Не правит документы за агентов** — они возвращают формулировки, решение
|
||||
подставить принимает человек или ты по его правилу.
|
||||
- **Не заводит задачи** — этим владеет `av-dev:task-track`.
|
||||
- **Не решает, когда себя звать.** Признак считает синк и говорит строкой; часы
|
||||
на прогон тратит человек своим словом.
|
||||
|
||||
Reference in New Issue
Block a user