Documentation Quality Review

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

Проверять документацию как независимый аудитор. Оценивать, позволяет ли она реализовать заявленное поведение без новых продуктовых и архитектурных решений. Не дописывать требования и не исправлять документы.

Перед созданием отчёта полностью прочитать report-template.md и использовать заданные там структуру, значения полей и правила обновления.

Рабочий процесс

1. Прочитать действующие инструкции репозитория.
2. Определить режим и область:
   • явно названные документы, раздел или слой означают ограниченную проверку;
   • просьба проверить весь комплект документации означает полную проверку.
3. Составить перечень документов области. Отделить нормативные документы от черновиков, примеров, предложений и справочных материалов.
4. Динамически обнаружить применимые documentation-writing скилы по актуальному каталогу среды. Не поддерживать закрытый перечень их имён.
5. Отобрать кандидатов по metadata, виду документов, слоям, транспортам и технологиям. Исключить implementation-, creator-, installer-, meta- и review-скилы.
6. Полностью прочитать SKILL.md каждого кандидата. Прочитать назначенные им review-checklist и references для проверяемого вида документов. После чтения подтвердить применимость или исключить кандидата.
7. Если каталог скилов недоступен, искать frontmatter name и description в указанных пользователем каталогах и отметить ограничение обнаружения.
8. Перед содержательным анализом вывести стартовую сводку: режим, область и её основание, документы, выбранные скилы, планируемые виды проверки, исключения и путь .review/documentation-quality.md. После однозначной сводки не ждать подтверждения.
9. При необходимом расширении области сначала вывести обновлённую сводку.
10. Определить назначение каждого документа и владельца его требований. Собрать стабильные обозначения, термины, состояния, операции, DTO, порты, события и внешние контракты.
11. Проверить каждый нормативный документ локально по профильному скилу: полноту, однозначность, обязательную структуру, открытые вопросы и готовность к реализации.
12. Разрешить ссылки и обозначения между документами. Сопоставить одинаковые понятия во всех местах использования.
13. Проверить направление зависимостей и владение требованиями. Не требовать дублирования: корректную ссылку на документ-владелец считать достаточной.
14. Считать противоречием только несовместимые нормативные утверждения. Не считать различную степень непротиворечивой детализации проблемой.
15. Считать неоднозначностью только несколько наблюдаемо разных трактовок. Не фиксировать стилистическую неидеальность ясного текста.
16. Проверить, можно ли реализовать каждое требование без самостоятельного продуктового или архитектурного решения. Не придумывать отсутствующий ответ.
17. Создавать замечание только при достаточном доказательстве. Подозрения, недоступные источники и непроверяемые области переносить в ограничения.
18. Обновить отчёт по шаблону. При ограниченной проверке не менять замечания вне области. Не удалять исправленные замечания без явной просьбы.
19. Проверить корневой .gitignore. Если отдельной строки .review/ нет, предложить пользователю добавить её. Не изменять .gitignore без согласия и не использовать .git/info/exclude вместо проектного правила.
20. Проверить git status и убедиться, что отчёт не добавлен в index.
21. Завершить краткой сводкой: новые и обновлённые замечания, количества по статусам и приоритетам, высокоприоритетные проблемы, вопросы согласования, ограничения и ссылка на отчёт. Не начинать исправление документации.

Источники проверки

Использовать в порядке применимости:

• явно заданные пользователем требования к документации;
• требования и рекомендации выбранных documentation-writing скилов;
• нормативные документы проверяемого комплекта;
• правила структуры и навигации репозитория.

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

Классы замечаний

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

Не вводить другие классы. Последний класс всегда имеет приоритет Низкий. Остальным назначать приоритет по влиянию, а не автоматически по классу.

Граница полноты

Фиксировать отсутствующие входы, результаты, исходы, владельцев, границы согласованности, доставки и совместимости, неопределённые ссылки, термины и состояния, а также открытые вопросы с неуказанным влиянием на реализацию.

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

Границы изменений

Разрешено изменять .review/documentation-quality.md и создавать каталог .review/ для него. Строку .review/ разрешено добавлять в корневой .gitignore только после согласия пользователя. Не исправлять нормативные документы и не менять .git/info/exclude.