Audit

/audit — проверка готовности документации к разработке

Задача — ответить на один вопрос: можно ли по этим документам запустить /kickoff и отдать проект Claude Code так, чтобы разработка не упёрлась в отсутствующее решение на второй день. Аудит читает всё, ничего не придумывает и не переписывает документы без разрешения. Результат — docs/06-audit-report.md с вердиктом и списком находок.

Правило остановки

После отчёта (и, если пользователь согласился, исправления мелких находок) шаг закончен. Не запускай /kickoff, не пересобирай документы с крупными проблемами сам — для этого есть /assemble <DOC> и /explore, и решение о пересборке принимает пользователь.

Как задавать вопросы

Любой вопрос пользователю — только через AskUserQuestion, с готовыми вариантами ответа: 2–4 конкретных варианта, рекомендуемый — первым с пометкой «(Recommended)». Вопрос обычным текстом в ответе — нарушение: пользователь ждёт кликабельные варианты. В этом скиле развилок немного (выбор папки, что делать с Minor-находками, приложить ли недостающие файлы), но все они идут через этот инструмент.

Где живут файлы

Как у остальных шагов: подключённая папка проекта (docs/, при наличии — openspec/) → AskUserQuestion «Подключу папку сейчас (Recommended)» / «Работать в документах Project» → документы claude.ai Project под теми же путями (project_read / project_write) + SendUserFile. Состояние — docs/STATUS.md. В режиме Project-документов openspec/, AGENTS.md и CLAUDE.md недоступны — их создаёт init-kickoff уже в репозитории; повторный аудит спецификаций возможен только в подключённой папке репозитория или по файлам, которые пользователь приложит. Скажи об этом в отчёте, а не пропускай молча.

Что проверяем

0. Состав и состояние

Прочитай docs/STATUS.md и все документы 00–05 целиком, а также docs/07-kickoff.md, openspec/ и AGENTS.md, если они уже есть (повторный аудит после /kickoff или init-kickoff). Документ отсутствует или в статусе draft/stale — это уже находка уровня Blocker/Major, но аудит всё равно доводи до конца: пользователю нужен полный список, а не первая ошибка. Исключение — exploration, пропущенный по решению пользователя (BRD §1 об этом говорит явно): тогда проверяй, что BRD §5–§7 содержат то, чего не хватает, — карту capabilities с ID и описаниями (их возьмёт init-kickoff для ## Purpose), non-goals, выбранное направление, — и ставь Major, а не Blocker, если чего-то из этого нет.

Для больших комплектов (суммарно больше ~60 КБ — это уже около 25 000 токенов кириллицы в одном контексте) распараллель чтение: по одному субагенту (Agent) на документ с чек-листом ниже и просьбой вернуть находки в формате таблицы находок; сводить и выносить вердикт — самому. Субагенту передавай пути к файлам и чек-лист, а не свои выводы, чтобы получить независимый взгляд.

1. Полнота каждого документа

Сверь с шаблонами /assemble: все разделы присутствуют и содержат содержимое, а не заглушки. Особые точки:

• exploration: выбранное направление, карта capabilities с ID, non-goals;
• BRD: измеримые KPI, приоритеты MoSCoW у всех BR, критерии приёмки;
• TRD: каждая CAP-xx покрыта хотя бы одним FR; NFR по всем категориям (развёртываемость, производительность, надёжность, безопасность, масштабируемость, доступность, локализация, наблюдаемость, сопровождаемость) — либо явное «не применимо, потому что…»; требования к данным и ПДн;
• SAD: ADR-01 фиксирует Clean Architecture с привязкой слоёв к компонентам; ADR для каждого нетривиального выбора (БД, хостинг, фреймворк, auth); §4 называет линтер и форматтер для языка; таблица «NFR → как обеспечивается → как проверяется»; §7 называет целевое окружение для walking skeleton и путь доставки сборки в него;
• SDD: реестр интерфейсов IF-xx с привязкой к модулям и FR (полные контракты должны быть в DDD §4, а не продублированы здесь), модель данных с инвариантами, обработка граничных случаев, стратегия тестирования;
• DDD: план изменений CH-xx с нулевым change walking skeleton (CH-00) и каркасом CH-01; детальный дизайн модулей, контракты API и задачи T-xxx с критериями готовности — для CH-00–CH-02 (их отсутствие у дальних changes — норма, а не находка: их достроит Claude Code по актуальному коду); структура репозитория, разложенная по слоям Clean Architecture; DoD; соглашения для AGENTS.md с правилами слоёв и линтером (их отсутствие — Major: без них init-kickoff не соберёт AGENTS.md, а 001 останется без задач на линтер).

2. Согласованность и трассируемость

• Цепочка BR → FR/NFR → C → M/IF/E → CH → T замкнута в обе стороны: нет BR без FR, FR без компонента, Must/Should FR/NFR без change в DDD §7, задач без FR («осиротевшие» задачи часто означают невысказанное требование). Задачи T-xxx проверяй только для FR/NFR из CH-00–CH-02: у дальних changes их по замыслу нет, хвост цепочки для них заканчивается на CH-xx.
• Версии в шапках: каждый документ основан на актуальной версии предыдущих (STATUS stale или расхождение версий — Major).
• Противоречия между документами: стек в exploration vs SAD, границы MVP в BRD vs план изменений в DDD, NFR-значения в TRD vs SAD.
• Терминология: одни и те же сущности называются одинаково во всех документах и в глоссарии.
• Дублирование: контракт API описан только в DDD §4, требование — только в TRD §3. Дубль — Minor; разошедшийся дубль (две несовпадающие версии одного контракта или требования) — Major.

3. Качество требований (EARS)

Для каждого FR/NFR в TRD проверь:

• формулировка соответствует ровно одному шаблону EARS (The … SHALL, WHEN …, the … SHALL, WHILE …, IF …, THEN …, WHERE …, комбинация WHILE … WHEN …) и написана по-английски;
• ровно один SHALL и одно действие; нет and/or, склеивающих два поведения;
• нет слов-маркеров неоднозначности: should, may, might, could, appropriate, adequate, user-friendly, fast, easy, etc., and/or, as needed, if possible, TBD внутри требования;
• проверяемость: есть число, состояние или наблюдаемый результат; для NFR — конкретная величина и условия измерения;
• есть хотя бы один сценарий приёмки WHEN … THEN …, и он не повторяет требование дословно;
• у требования есть приоритет и источник BR-xx.

Считай долю требований, прошедших проверку, и приводи её в отчёте — это самая наглядная метрика зрелости TRD.

4. Готовность к OpenSpec и Claude Code

• Capabilities названы в kebab-case по-английски и пригодны как имена openspec/specs/<capability>/.
• Нулевой change в DDD — walking skeleton: минимальное приложение, запускаемое в целевом окружении из SAD §7, без БД, auth и CI, с NFR развёртываемости; первый — каркас проекта (CI, БД, тесты), к нему привязаны остальные сквозные NFR (оба станут спецификацией capability platform); остальные — вертикальные срезы с проверяемым результатом, зависимости указаны и не образуют цикла. Каждое Must/Should FR/NFR отнесено ровно к одному change.
• Каждая задача T-xxx из CH-00–CH-02 выполнима за одну сессию Claude Code (ориентир — меньше дня работы) и имеет критерий готовности.
• Есть всё для AGENTS.md: стек, команды сборки/тестов/линтера/деплоя, слои Clean Architecture с каталогами, соглашения, DoD.
• Все Must-требования не содержат [TBD]/[ДОПУЩЕНИЕ] без решения; открытые Q-xx, помеченные «нужен к /kickoff» или раньше, закрыты.

Если docs/07-kickoff.md уже существует — проверь волны выполнения так же строго, как отсутствие цикла: волна каждого change больше волны любой его зависимости; внутри волны модули M-xx (по SDD §1 «Реализует FR») попарно не пересекаются; волны 0 и 1 содержат только 000 и 001; номера NNN не убывают по волнам, 002 соответствует CH-02; числа §2а (последовательно, параллельно, экономия) пересчитываются из таблицы. Ошибка в волнах — Major: параллельные агенты столкнутся в одних файлах. Если есть и openspec/ — строка - Wave: N в каждом proposal.md совпадает с дорожной картой.

Если openspec/ уже существует — дополнительно проверь, что спецификации следуют формату ### Requirement: / #### Scenario: (ровно четыре решётки) с EARS-формулировками и SHALL, что новые capabilities имеют ## Purpose, что openspec/config.yaml парсится как YAML и содержит правила EARS (CLI молча игнорирует нечитаемый config), и что каждое Must/Should-требование TRD встречается ровно в одном change. При наличии CLI (openspec --version; можно установить npm install -g @fission-ai/openspec@latest) запусти openspec validate --all --strict и включи вывод в отчёт. Помни, что валидатор проверяет только структуру и наличие SHALL/MUST — соответствие EARS-паттернам и качество сценариев проверяешь ты.

Классификация находок

Вердикт:

• READY — нет Blocker и Major; Minor допустимы.
• READY WITH CONDITIONS — нет Blocker, есть Major, которые можно закрыть до конца каркаса (CH-01) или не затрагивают CH-00–CH-02; условия перечислены явно.
• NOT READY — есть хотя бы один Blocker.

Отчёт docs/06-audit-report.md

# Audit report: <название проекта>
Версия: N · Дата: YYYY-MM-DD · Проверенные версии: exploration v1, BRD v2, TRD v1, SAD v1, SDD v1, DDD v1

## 1. Вердикт
READY | READY WITH CONDITIONS | NOT READY — одним абзацем почему.

## 2. Сводка
| Документ | Статус в STATUS | Blocker | Major | Minor |
Доля FR/NFR, соответствующих EARS: NN % (X из Y).
Трассируемость: BR без FR — n; Must/Should FR/NFR без change — n; FR из CH-00–CH-02 без задач — n; задачи без FR — n.

## 3. Находки
| ID | Уровень | Документ / раздел | Что не так | Почему важно | Что сделать | Куда возвращаться |
| F-01 | Blocker | TRD §3 CAP-04 | … | … | … | /assemble TRD |

## 4. Условия (для READY WITH CONDITIONS)
| Условие | До какого change должно быть закрыто | Кто |

## 5. Проверка EARS — детали
| FR | Проблема | Предложенная формулировка |

## 6. Что проверено и признано хорошим
Коротко — чтобы пользователь видел, что аудит был полным, а не только список претензий.

После отчёта

1. Запиши отчёт, обнови docs/STATUS.md (строка audit: вердикт и дата).
2. Покажи вердикт и 3–5 самых важных находок в чате.
3. Если есть Minor-находки — AskUserQuestion: «Исправить Minor прямо в документах сейчас» / «Не трогать, исправлю сам» / «Показать список правок до применения». При согласии вноси правки точечно (Edit, не перезапись), поднимай версию документа, добавляй строку в его журнал изменений (последний раздел документа, см. шаблоны /assemble), помечай находку в отчёте как fixed. После правок обнови в шапке отчёта «Проверенные версии» на новые версии документов и дату аудита — именно по ним /kickoff решает, актуален ли аудит; статус approved у исправленных документов сохраняется. Blocker и Major в документах не правь: покажи, какой шаг перезапустить, и остановись.
4. Если вердикт READY / READY WITH CONDITIONS — скажи, что следующий шаг /kickoff, и остановись. Не запускай его.

Чего не делать

• Не смягчать вердикт, потому что «в целом неплохо»: NOT READY при одном Blocker — это и есть польза аудита.
• Не раздувать отчёт стилистическими замечаниями — они уместны только как Minor и только если мешают пониманию.
• Не переписывать требования за автора в документах без согласия; в отчёте предложить формулировку можно и нужно.
• Не задавать вопросы обычным текстом — только AskUserQuestion с вариантами.
• Не переходить к /kickoff.