Slash Command

/audit-docs

From sdlc-audit

Audit documentation: drift between docs and code, ADR coverage gaps, README quality, missing API docs.

Invocation

How this command is triggered — by the user, by Claude, or both

Slash command

/sdlc-audit:audit-docs [--depth=quick|standard|deep] [--scope=path/to/dir]

Model invocable

No pre-commands

Context Preview

The summary Claude sees in its command listing — used to decide when to auto-load this command

# /audit:docs - Documentation Audit

Поиск drift между документацией и реальным кодом.

## Что проверяется

1. **README quality** - есть ли, актуален ли, покрывает ли setup/run/test
2. **ADR coverage** - архитектурные решения задокументированы в ADR?
3. **API documentation** - endpoints / functions описаны?
4. **Inline docstrings** - публичные API без docstrings?
5. **Code examples drift** - примеры в docs реально работают?
6. **Outdated info** - упоминания старых версий, удалённых features
7. **Setup instructions accuracy** - реально ли можно поднять проект по docs
8. **Conventions documen...

Command Content

92 lines · ~783 tokens

Stats

LanguageShell

Parent stars0

MaintenanceGood

Last CommitMay 5, 2026

Actions

View Source View Plugin View on GitHub View README

Stats

Actions

/audit:docs - Documentation Audit

Поиск drift между документацией и реальным кодом.

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

README quality - есть ли, актуален ли, покрывает ли setup/run/test
ADR coverage - архитектурные решения задокументированы в ADR?
API documentation - endpoints / functions описаны?
Inline docstrings - публичные API без docstrings?
Code examples drift - примеры в docs реально работают?
Outdated info - упоминания старых версий, удалённых features
Setup instructions accuracy - реально ли можно поднять проект по docs
Conventions documented - кодстайл, branching, commit messages
Feature briefs (для проектов на нашем kit'е) - существует docs/specs/<feature>/brief.md?

Шаги выполнения

Используй subagent docs-auditor который применяет skill docs-audit.

1. Inventory

Прочитай:

README.md (если есть)
CONTRIBUTING.md, CHANGELOG.md
Папки docs/, wiki/, documentation/ если есть
Inline docstrings/JSDoc/GoDoc через выборочное чтение

2. README check

Минимальные требования:

Что это за проект (1 параграф)
Как установить
Как запустить
Как тестировать
Как закомитить (либо ссылка на CONTRIBUTING.md)

Если чего-то нет - finding.

3. ADR coverage

Это пересекается с audit:architecture, но фокус другой - не "правильны ли решения", а "задокументированы ли решения".

Список значимых решений в коде vs ADR:

Выбор фреймворков
Архитектурные паттерны (CQRS, event sourcing)
Схема auth
БД (включая миграционную стратегию)
Стратегия кеширования
Background jobs

4. Drift detection

Прочитать docs которые упоминают конкретный код:

Если в docs упоминается class FooBar - проверить что класс существует с этим именем
Если в docs упоминается endpoint /api/v1/foo - проверить что он реально определён
Если в docs упоминается env variable BAR_BAZ - проверить что она используется

Создай docs/audit/<TS>/docs/drift-report.md.

5. Setup verification (только в deep mode)

Если в README есть Quick Start или Setup:

Прочитать инструкции
Сравнить с реальностью - команды актуальны? Зависимости перечислены полностью?

В deep mode - попытаться выполнить инструкции в read-only режиме (если можно без побочных эффектов). Если не можно - не пытаться.

6. Findings generation

Записать в docs/audit/<TS>/docs/findings.json.

Severity rules для docs findings

Severity	Когда применять
HIGH	Setup инструкции в README не работают. Major architectural decisions без ADR.
MEDIUM	API endpoints без docs. Outdated examples. Missing CONTRIBUTING для public projects.
LOW	Typos, formatting issues, docstrings missing для internal helpers.

Note: docs findings обычно не превышают HIGH - это редко блокирует production, но влияет на onboarding и maintenance.

Output

Сводка в чат
Путь к деталям: docs/audit/<TS>/docs/