--- name: healthcheck description: "Проверка здоровья документации проекта судом, а не машиной: не разошлись ли документы между собой и с кодом. Зовёт двух агентов на весь канон разом — doc-consistency (один факт в двух домах, прямое противоречие, поведение в architecture.md вместо спек, ADR без парного статуса, число без провенанса) и doc-code-drift (протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки, capability). Разбирает урожай порциями: строка на замену идёт в документ сразу, работа больше абзаца становится задачей. Использовать, когда с прошлой сверки сделан десяток задач, когда вернулись к проекту после перерыва, перед тем как опереться на документ в решении, а также шагом adopt и upgrade. Дорого — не на каждой задаче. Раскладку и версию канона проверяет скилл canon, язык документов — агент doc-wording." --- # Здоровье документации Проверяет то, **чего машина не видит**: разошлись ли документы между собой и с кодом. Раскладка, версия, битые ссылки, нетронутые плейсхолдеры — это `canon check` и его скрипт; здесь начинается там, где кончается `docs.py`. Разрез проверяемый: **машина сверяет форму, этот скилл — утверждения**. «В `architecture.md` есть раздел» проверит скрипт. «В `architecture.md` написано, что зависимость одна, а в манифесте их три» — суждение, и его выносит агент. ## Когда звать **Зовёт человек**, но признак наблюдаемый, а не календарный: - **с прошлой сверки сделан десяток задач.** Документы протухают ровно от сделанной работы: переименованная цель сборки, ушедшая зависимость, второй способ делать то, что обзор объявил единственным, факт, дописанный в `architecture.md` и уже живущий в `CLAUDE.md`; - **вернулись к проекту после перерыва** — прежде чем опираться на написанное; - **перед тем как опереться на документ в решении**, если оно дорогое; - шагом `adopt` и шагом `upgrade` — их зовёт скилл `canon` сам. **Не на каждой задаче и не на каждом синке документации.** Цена реальная: `doc-consistency` идёт на `opus`, потому что сличение утверждений — суждение; `doc-code-drift` хоть и на `sonnet`, но читает репозиторий целиком. Прогон по каждой сделанной задаче был бы самой дорогой церемонией процесса, а находок дал бы почти те же: документы расходятся не с одной задачи, а с десятка. Прежде оба звались шагом сессии между спринтами. Спринтов нет, и **момент пришлось назвать заново** — иначе их не звал бы никто, кроме разовых `adopt` и `upgrade`, то есть на живом проекте никогда. ## Обращение к соседним плагинам **Копия.** Дом — `shared/plugin-boundary.md` в репозитории плагинов. Правится дом, а не этот файл. Плагины `av-dev` ставятся порознь, и ни один не вправе считать, что сосед на месте. **Чужой скилл зовётся полным именем** — `av-dev-docs:canon`, `av-dev-tasks:tasks`, `av-dev-code:review`. Короткое имя может разрешиться в устаревшую проектную копию из `.claude/skills/`, и подмены не будет видно ни в докладе, ни в поведении. **Путь в дерево чужого плагина не пишется никогда.** `$CLAUDE_PLUGIN_ROOT` ведёт только в свой плагин; вычисленный от него путь к соседу либо не откроется, либо откроет чужую установку. Нужен чужой справочник — зови владеющий им скилл, он прочитает его сам. **Вызов не разрешился — плагина в проекте нет.** Это исход, а не поломка: назови строкой доклада, чего теперь не делает никто, и продолжай работу. Молчать нельзя, пропуск неотличим от сделанного; выдумывать обходной путь нельзя тоже. **Присутствие узнаётся вызовом или следом в проекте, но не объявлением.** Перечня установленных плагинов проект не ведёт — он разошёлся бы с действительностью молча. Что сосед здесь работал, видно по заведённому им файлу: `docs/.pm.json` — канон, `<каталог задач>/.tasks.json` — задачи, `openspec/config.yaml` — конвейер. Здесь сосед один: `av-dev-tasks:tasks`, когда находка тянет на задачу. Его нет — находки остаются списком в докладе, и это говорится строкой. ## Пачка — весь канон, и это не расточительство Оба агента зовутся **на весь канон разом**, а не на пачку, отобранную работой. Когда пачку отбирала работа, без присмотра оставалось ровно то, чего работа не касалась: правка, отменившая решение, живёт в одном документе, а парный статус нужен в другом; факт, продублированный год назад, не попадёт ни в один диапазон диффа. Канон мал — он читается целиком, и цена этого известна заранее. ## Кого зовёшь и что передаёшь | Агент | Что смотрит | Читает | Модель | | --- | --- | --- | --- | | `doc-consistency` | смысловой дубль, прямое противоречие между документами, поведение в `architecture.md` вместо спек, ADR без ссылки и парного статуса, число без провенанса, заглушка вместо честной строки | `docs/`, `openspec/` | `opus` | | `doc-code-drift` | протухший факт: имя ветки, команды, пути, зависимости поимённо, настройки с числом, единые точки проекта, capability | весь репозиторий | `sonnet` | **`doc-code-drift` обязан получить раздел запретов `CLAUDE.md`.** Он гоняет команды — только читающие, — и без перечня запретов не знает, чего в этом проекте запускать нельзя. Не передал — он либо остановится, либо тронет то, чего трогать не следовало. **Судит не тот, кто писал.** Ни один из двоих ничего не правит: оба возвращают готовые формулировки, подставляешь ты. Самопроверка документа слабее всего ровно там, где формулировка казалась удачной при написании. Одного из двух можно позвать отдельно — но **скажи в докладе, кого именно позвал**. Доклад, умолчавший об этом, читается как «сверено целиком». ## Разбор урожая Находки — обычный материал правки, и разбирать их надо **порциями**, а не одним заходом: тридцать находок подряд получают «принято» не потому, что верны, а потому, что разбор затянулся. По каждой находке ровно три исхода: 1. **Строка на замену** — правь документ сразу. Формулировка уже готова, спорить не с чем, и откладывание превращает её в задачу дороже самой правки. 2. **Работа больше чем на абзац** — задача типа `chore`. Заводит её **не этот скилл**: вызови Skill `av-dev-tasks:tasks`, у него свой формат, дедупликация против беклога и кладбища. Плагина нет — отдай списком в докладе и скажи это строкой. 3. **Не находка** — агент ошибся, документ прав. Скажи это прямо: неразобранная находка и отклонённая различаются, и вторая экономит время на следующем прогоне. Класс ошибок, который повторяется, идёт в `docs/review.*`, раздел настройки, — там дом типовых ложноположительных. ## Доклад - **Кого позвал** — обоих или одного, и почему одного. - Находки по каждому агенту: сколько, что поправлено сразу, что стало задачей (со слагами), что отклонено и почему. - **Границы покрытия**: что смотрели и чего не смотрели. У `doc-code-drift` она идёт из его собственного отчёта — перечень фактов у него закрытый, и он называет, какие из них проверить было нечем. - Канона в проекте нет вовсе — это исход, а не пустой прогон: скажи строкой и предложи `av-dev-docs:canon`. ## Чего этот скилл не делает - **Не проверяет раскладку, версию и ссылки** — это `canon check`, там машина. - **Не судит язык** документов: залог, англицизмы, жаргон, термин без дома — это агент `doc-wording`, и зовут его отдельно, по пачке правленных документов. Звонящие у него названные — последний шаг синка в `av-dev-docs:docs`, шаг 9 `av-dev-docs:init` и шаг вычитки в обоих режимах `canon`, — просто ни один из них не здесь. У него другой ритм: он нужен там, где текст только что писали, а не там, где он год лежал. Оркестровать его нечем — он один и работает по названному списку. - **Не правит документы за агентов** — они возвращают формулировки, решение подставить принимает человек или ты по его правилу. - **Не заводит задачи** — этим владеет `av-dev-tasks:tasks`.