dev-skills/av-dev/skills/doc-healthcheck/SKILL.md

name, description

name

description

doc-healthcheck

Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без происхождения) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Прогон оставляет след — ключ [docs] healthcheck_last в .av-dev.toml, — и по нему синк документации считает, сколько задач сделано с прошлой сверки, и выдаёт сигнал строкой. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию раскладки проверяет скилл av-dev:canon, язык документов — агент doc-wording.

Здоровье документации

Проверяет то, чего машина не видит: разошлись ли документы между собой и с кодом. Раскладка, версия, битые ссылки, нетронутые плейсхолдеры — это canon check и его скрипт; здесь начинается там, где кончается docs.py.

Разрез проверяемый: машина сверяет форму, этот скилл — утверждения. «В architecture.md есть раздел» проверит скрипт. «В architecture.md написано, что зависимость одна, а в манифесте их три» — суждение, и его выносит агент.

Когда звать

Зовёт человек, но признак наблюдаемый, а не календарный:

• с прошлой сверки сделан десяток задач. Документы протухают ровно от сделанной работы: переименованная цель сборки, ушедшая зависимость, второй способ делать то, что обзор объявил единственным, факт, дописанный в architecture.md и уже живущий в CLAUDE.md. Этот признак считается, а не вспоминается: счёт ведёт синк документации по следу прошлого прогона и выдаёт строкой на каждой сделанной задаче (av-dev:doc-sync, раздел «Сигнал сверки»);
• вернулись к проекту после перерыва — прежде чем опираться на написанное;
• перед тем как опереться на документ в решении, если оно дорогое;
• шагом adopt и шагом upgrade — их зовёт скилл canon сам.

Не на каждой задаче и не на каждом синке документации. Цена реальная: doc-consistency идёт на opus, потому что сличение утверждений — суждение; doc-code-drift хоть и на sonnet, но читает репозиторий целиком. Прогон по каждой сделанной задаче был бы самой дорогой церемонией процесса, а находок дал бы почти те же: документы расходятся не с одной задачи, а с десятка.

Прежде оба звались шагом сессии между спринтами. Спринтов нет, и момент пришлось назвать заново — иначе их не звал бы никто, кроме разовых adopt и upgrade, то есть на живом проекте никогда.

Чего может не быть

Копия. Дом правила — shared/absence.md в репозитории плагина. Правится дом, а не этот файл.

Скилл не вправе считать раскладку проекта полной. Части заводятся порознь и живут порознь; каждая узнаётся своим следом:

Чего нет	Как видно	Чего теперь не делает никто
настройки av-dev	нет .av-dev.toml в корне	проект под процесс не заводился; версии нет, настроек нет
документы канона	нет docs/	проектную конкретику брать неоткуда — темы, инварианты, прецеденты
учёт работ	нет каталога задач	запись остаётся владельцу: назови её текстом в докладе
источник требований	нет openspec/config.yaml	цикл SDD не запускается: спеки не с чем сверять

Свой скилл зовётся полным именем — av-dev:canon, av-dev:task-track, av-dev:code-review. Короткое имя может разрешиться в устаревшую проектную копию из .claude/skills/, и подмены не будет видно ни в докладе, ни в поведении.

Внешний плагин может не стоять. Их два: opsx:* — цикл SDD, и av-dev-git:commit — сообщения коммитов. Путь в дерево чужого плагина не пишется никогда: $CLAUDE_PLUGIN_ROOT ведёт только в своё дерево, а вычисленный от него путь к соседу либо не откроется, либо откроет чужую установку. Нужен чужой справочник — зови владеющий им скилл, он прочитает его сам.

Отсутствие — исход, а не поломка. Назови строкой доклада, чего теперь не делает никто, и продолжай работу. Молчать нельзя: пропуск неотличим от сделанного. Выдумывать обходной путь нельзя тоже.

Присутствие узнаётся следом в проекте, а не объявлением. Перечня того, что здесь заведено, проект не ведёт — он разошёлся бы с действительностью молча.

Здесь сосед один: av-dev:task-track, когда находка тянет на задачу. Его нет — находки остаются списком в докладе, и это говорится строкой.

Пачка — весь канон, и это не расточительство

Оба агента зовутся на весь канон разом, а не на пачку, отобранную работой.

Когда пачку отбирала работа, без присмотра оставалось ровно то, чего работа не касалась: правка, отменившая решение, живёт в одном документе, а парный статус нужен в другом; факт, продублированный год назад, не попадёт ни в один диапазон диффа. Канон мал — он читается целиком, и цена этого известна заранее.

Кого зовёшь и что передаёшь

Агент	Что смотрит	Читает	Модель
doc-consistency	смысловой дубль, прямое противоречие между документами, поведение в architecture.md вместо спек, ADR без ссылки и парного статуса, число без происхождения, заглушка вместо честной строки	docs/, openspec/	opus
doc-code-drift	протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки проекта, capability	весь репозиторий	sonnet

doc-code-drift обязан получить раздел запретов CLAUDE.md. Он гоняет команды — только читающие, — и без перечня запретов не знает, чего в этом проекте запускать нельзя. Не передал — он либо остановится, либо тронет то, чего трогать не следовало.

Судит не тот, кто писал. Ни один из двоих ничего не правит: оба возвращают готовые формулировки, подставляешь ты. Самопроверка документа слабее всего ровно там, где формулировка казалась удачной при написании.

Одного из двух можно позвать отдельно — но скажи в докладе, кого именно позвал. Доклад, умолчавший об этом, читается как «сверено целиком».

Разбор урожая

Находки — обычный материал правки, и разбирать их надо порциями, а не одним заходом: тридцать находок подряд получают «принято» не потому, что верны, а потому, что разбор затянулся.

По каждой находке ровно три исхода:

1. Строка на замену — правь документ сразу. Формулировка уже готова, спорить не с чем, и откладывание превращает её в задачу дороже самой правки.
2. Работа больше чем на абзац — задача типа chore. Заводит её не этот скилл: вызови Skill av-dev:task-track, у него свой формат, дедупликация против беклога и кладбища. Каталога задач в проекте нет — отдай списком в докладе и скажи это строкой.
3. Не находка — агент ошибся, документ прав. Скажи это прямо: неразобранная находка и отклонённая различаются, и вторая экономит время на следующем прогоне. Класс ошибок, который повторяется, идёт в docs/review.*, раздел настройки, — там дом типовых ложноположительных.

След прогона

Последним шагом прогон правит .av-dev.toml — ключ healthcheck_last в секции [docs]: хеш коммита HEAD и дата комментарием рядом. Состав ключей — канон, раздел .av-dev.toml; правится строка, а не файл целиком.

Секцию и имя ключа не выбирай сам. Неизвестный ключ .av-dev.toml — отказ кодом 3, а не пропуск: ключ, заведённый мимо константы скрипта-владельца, роняет docs.py, tasks.py и гейт проекта разом. Этот ключ там уже назван (DOCS_KEYS в av-dev/skills/canon/scripts/docs.py), а любой другой пришлось бы заводить правкой скрипта.

Без следа признак «десяток задач» не считается никем. Так и было: сверку звали по памяти, то есть не звали — тот же прозаический триггер, что дал 6 записей ADR на 43 изменения. След превращает признак в число, которое av-dev:doc-sync считает командой git rev-list --count <last>..HEAD -- openspec/changes/archive и говорит вслух на каждой задаче.

Ключ необязательный и заводится сам — первым же прогоном сверки; проекту для этого делать нечего. Его отсутствие значит «сверки не было ни разу», и синк говорит это отдельной строкой.

Правку следа коммитит тот, кто позвал прогон. Своего коммита у скилла нет: он правит документы, заводит задачи и ставит след — всё это уезжает одним коммитом разбора, и last в нём указывает на прежний HEAD, то есть на состояние, которое сверяли. Оставить правку незакоммиченной нельзя: счёт пойдёт от коммита, которого в истории нет.

Позвал одного агента из двух — след всё равно ставится, но в докладе назван неполным. Иначе следующая сверка отсчитывалась бы от прогона, который смотрел половину.

Доклад

• Кого позвал — обоих или одного, и почему одного.
• Находки по каждому агенту: сколько, что поправлено сразу, что стало задачей (со слагами), что отклонено и почему.
• Границы покрытия: что смотрели и чего не смотрели. У doc-code-drift она идёт из его собственного отчёта — перечень фактов у него закрытый, и он называет, какие из них проверить было нечем.
• Канона в проекте нет вовсе — это исход, а не пустой прогон: скажи строкой и предложи av-dev:canon.

Чего этот скилл не делает

• Не проверяет раскладку, версию и ссылки — это canon check, там машина.
• Не судит язык документов: залог, англицизмы, жаргон, термин без дома — это агент doc-wording, и зовут его отдельно, по пачке правленных документов. Звонящие у него названные — последний заход синка в av-dev:doc-sync, шаг вычитки сценария разведки (av-dev:code-resolve), шаг 9 av-dev:doc-init и шаг вычитки в обоих режимах canon, — просто ни один из них не здесь. У него другой ритм: он нужен там, где текст только что писали, а не там, где он год лежал. Оркестровать его нечем — он один и работает по названному списку.
• Не правит документы за агентов — они возвращают формулировки, решение подставить принимает человек или ты по его правилу.
• Не заводит задачи — этим владеет av-dev:task-track.
• Не решает, когда себя звать. Признак считает синк и говорит строкой; часы на прогон тратит человек своим словом.