# Documentation Improvement Orchestrator > Сквозная проверка и доработка нормативной документации до готовности к реализации: инвентаризация области, динамический выбор профильных documentation-writing скилов, независимый аудит качества, исправление однозначных замечаний и повторение audit/fix цикла. Использовать, когда пользователь просит проверить и довести документ, комплект требований или документацию сервиса до согласованного состояния. Обязательно запрашивать у пользователя отсутствующие продуктовые и архитектурные решения и не угадывать их. Не использовать для проверки реализации, написания кода или только read-only аудита без исправлений. - Skill: `nemagu/documentation-improvement-orchestrator` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add nemagu/documentation-improvement-orchestrator` - Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/documentation-improvement-orchestrator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: Nemagu (https://skillmd.com/u/nemagu) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/nemagu/documentation-improvement-orchestrator --- # Проверка и доработка документации Доводить всю заявленную область документации до готовности к реализации. Не считать первый аудит, отдельное исправление или промежуточный отчёт завершением задачи. Для многоэтапной работы полностью прочитать [progress-template.md](references/progress-template.md), создать `.orchestration/documentation-progress.md` и поддерживать его актуальным. ## Основной принцип Исправлять без подтверждения только то, что однозначно следует из нормативных источников, инструкций репозитория и применимых documentation-writing скилов. Никогда не выбирать за пользователя новое продуктовое или архитектурное решение, не восстанавливать его из кода и не маскировать догадку как требование. Если данных достаточно, сразу продолжать следующий безопасный этап. Если решение получить нельзя, сформулировать конкретный вопрос, объяснить наблюдаемые варианты и их влияние, запросить пользователя и остановить только зависимую часть работы. ## Подготовка 1. Прочитать инструкции репозитория и проверить состояние рабочего дерева. 2. Сохранить незавершённые изменения пользователя и не откатывать их. 3. Определить цель, режим, область нормативной документации и исключения. 4. Отделить нормативные документы от черновиков, примеров, предложений и кода. 5. Динамически обнаружить профильные documentation-writing скилы по metadata, полностью прочитать выбранные `SKILL.md` и назначенные ими references. Не поддерживать закрытый список имён. 6. Вывести стартовую сводку: цель, область, документы, выбранные скилы, планируемые этапы, исключения, отчёт и progress-файл. 7. Определить порог исправления без отдельного вопроса. Если пользователь явно не задал иное, использовать `Все`: исправлять `Высокий`, `Средний` и `Низкий`. Явно заданные альтернативы: `До среднего` — `Высокий` и `Средний`; `Только высокий` — только `Высокий`. Зафиксировать применённый порог в progress-файле. 8. Проверить корневой `.gitignore` целевого проекта. Если отдельных строк `.orchestration/` или `.review/` нет, предложить пользователю добавить отсутствующие строки. Не изменять `.gitignore` без согласия и не использовать `.git/info/exclude`. 9. Создать или актуализировать `.orchestration/documentation-progress.md`, не стирая решения пользователя и сведения предыдущего запуска. ## План документации 1. Разложить цель на проверяемые документы, разделы, контракты и междокументные связи с устойчивыми ID. 2. Для элемента указать владельца требования, нормативные источники, зависимости, профильный скил, ожидаемый результат и способ проверки. 3. Включить навигацию, терминологию, владение требованиями и ссылки между документами, если они входят в область. 4. Отмечать `Не требуется` только по доказательству из области задачи. 5. При отсутствии профильного скила следовать нормативным источникам и правилам репозитория, отметить ограничение, но не блокировать однозначную работу. ## Первичная доработка 1. Создавать и изменять документацию только через применимые профильные скилы. 2. Сохранять разделение владельцев требований и не дублировать нормативные определения вместо ссылок. 3. Перед изменением, которое допускает разные наблюдаемые варианты, проверить, закреплён ли выбор в нормативных источниках или предыдущем решении пользователя. 4. Если выбор не закреплён, оформить блокер и запросить решение; не выбирать наиболее привычный, простой или удобный для реализации вариант. 5. После каждого элемента выполнять локальную проверку структуры, ссылок и согласованности, затем переходить к следующему независимому элементу. ## Независимый audit/fix loop 1. Динамически обнаружить review-скил проверки качества нормативной документации и выполнить полный аудит заявленной области в его read-only границах. 2. Прочитать `.review/documentation-quality.md`, сохраняя ID, классификацию, статусы и пользовательские записи. 3. Отделить замечания, входящие в согласованный порог. Замечания ниже порога не исправлять, не переводить в `Исправлено` и не удалять; перечислить их в progress-файле и итоговой сводке. 4. Сначала выполнить автономную фазу. Для каждого входящего в порог `Актуально` выбрать профильный documentation-writing скил, исправить первопричину, заменить шаблон блока `Решение` описанием изменения и выполнить относящиеся проверки. Только затем перевести замечание в `Исправлено`. 5. После исправления всех входящих в порог `Актуально` повторно выполнить аудит. Если он создал или вернул хотя бы одно такое замечание, продолжить автономную фазу. Не задавать вопросы согласования, пока остаётся хотя бы одно однозначно исправимое замечание в пороге. 6. Перейти к совместной фазе только когда повторный аудит не находит `Актуально` в пороге. Для каждого входящего в порог `Требует согласования` проверить, нет ли уже явного решения в нормативных источниках или progress-файле. Если нет, не предлагать скрытое решение от имени пользователя и не менять документацию. 7. Сгруппировать не более трёх коротких независимых вопросов за один запрос. Для каждого привести контекст, конкретное требуемое решение, допустимые варианты, если они доказуемы, и последствия выбора. Не добавлять выдуманный вариант только ради списка. 8. После ответа дословно зафиксировать принятое решение в блоке `Решение` и progress-файле, перевести замечание в `Актуально`, внести его в нормативную документацию, проверить и затем перевести в `Исправлено`. 9. После каждого полученного решения вернуться в автономную фазу: исправить все ставшие однозначными и вновь обнаруженные замечания до следующего запроса пользователю. 10. Продолжать цикл, пока в согласованном пороге остаётся `Актуально` или `Требует согласования`. Не удалять исправленные замечания без явной просьбы. 11. Если review-скил недоступен, зафиксировать невыполненный quality gate как блокер и не подменять независимый аудит самооценкой. ## Работа при ожидании решения - До первого и каждого следующего вопроса завершить все независимые безопасные элементы и добиться отсутствия входящих в порог `Актуально` по результату повторного аудита. - Не задавать повторно вопрос, на который уже есть однозначный ответ в истории, progress-файле или нормативном документе. - Не трактовать молчание, пример, существующий код или рекомендацию скила как принятое продуктовое решение. - Не менять статус `Требует согласования`, пока решение не получено и не записано. - После ответа продолжить весь оставшийся цикл без дополнительной команды `продолжай`. ## Definition of Done Считать задачу завершённой, только если одновременно: - каждый элемент области имеет `Выполнено` или обоснованное `Не требуется`; - документация содержит необходимые однозначные требования, владельцев и ссылки; - выполнен независимый полный аудит заявленной области; - в согласованном пороге нет `Актуально` и `Требует согласования`; - все замечания ниже порога сохранены и перечислены как согласованно отложенные; - все принятые решения записаны в нормативные документы и блоки `Решение`; - повторный аудит подтверждает исправления; - progress-файл отражает фактическое итоговое состояние; - исключения `.orchestration/` и `.review/` предложены для корневого `.gitignore`, если отсутствуют; - проверены `git status` и итоговый diff без затрагивания чужих изменений. Финальный ответ должен сообщать доработанную область, принятые решения, результаты аудита, ограничения и путь к progress-файлу. Не объявлять документацию готовой, если Definition of Done не выполнен.