Documentation Improvement Orchestrator

Проверка и доработка документации

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

Для многоэтапной работы полностью прочитать 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 не выполнен.