| name | doc-lint |
| description | Аудит качества документации — размер, структура, дубликаты между файлами, нарушения SSOT. Используй для контроля качества human-readable файлов, поиска дублирования и проверки структуры. Не используй для code review или анализа исходного кода. |
| allowed-tools | Read Write Edit Glob Grep Bash(wc*) |
| agent | agents/auditor.md |
| context | fork |
/doc-lint — Аудит качества документации
Сканирует все human-readable файлы проекта, находит проблемы с размером, структурой, дубликатами между файлами и нарушения SSOT (Single Source of Truth). Генерирует отчёт с приоритизированными findings и планом рефакторинга.
Перед началом
Прочитай .claude/qa_agent.md и .claude/agents/auditor.md.
Когда использовать
- После добавления нового документа или skill
- При подозрении на дублирование контента между файлами
- Для периодического аудита документации (раз в спринт)
- Перед рефакторингом документации
Входные данные
| Параметр | Обязательность | Описание |
|---|
| Scope | Опционально | Конкретные файлы/директории. По умолчанию — весь проект |
| Focus | Опционально | Только определённые фазы (size, structure, duplicates) |
Алгоритм (6 фаз)
Verbosity Protocol (STRICT)
SILENT MODE ENFORCED:
- NO CHAT TABLES: Никогда не выводи таблицы (Inventory, Findings, Stats) в чат. Только в файл отчёта.
- NO LISTS: Не перечисляй проверенные файлы в чате.
- ONLY STATUS: В чат выводить только финальный блок
SKILL COMPLETE и путь к отчёту.
Пример единственного допустимого вывода в чат:
📝 Audit Complete.
📊 Report: audit/doc-lint-report.md
📉 Health Score: 78/100
💡 Action: Run bash audit/safe-fix.sh to apply safe fixes.
Фазы 1-7: Детальный алгоритм
Полное описание всех фаз (Discovery, Size Analysis, Structure Analysis, Cross-File Duplicate Detection, Content Hygiene, Report Generation, Safe-Fix Script) — в references/phases.md.
Severity Model
| Severity | Критерии |
|---|
| CRITICAL | Фактическое превышение лимитов (>700 generic, >500 SKILL); Битые ссылки (файл не найден) |
| WARNING | Приближение к лимиту (90% от порога); Дубликаты >10 строк; Wall-of-text >30 строк |
| INFO | TODO маркеры; Мелкие дубликаты (3-5 строк); Stale dates; Formatting issues |
Health Score Logic
Start Score: 100.
Deductions (вычитание):
- CRITICAL: -15 баллов (за каждый finding)
- WARNING: -5 баллов
- INFO: -0.5 балла (снижаем вес мусора)
Formula: MAX(0, 100 - (Count_Crit * 15) - (Count_Warn * 5) - (Count_Info * 0.5))
Бонусных баллов за "хорошее поведение" не начислять.
| Диапазон | Оценка | Интерпретация |
|---|
| 90-100 | Excellent | Документация в отличном состоянии |
| 70-89 | Good | Есть незначительные проблемы |
| 50-69 | Needs attention | Требуется рефакторинг |
| <50 | Refactoring needed | Срочный рефакторинг документации |
Формула должна быть показана с подстановкой значений:
Score = 100 - (2 × 15) - (5 × 5) - (8 × 0.5) = 100 - 30 - 25 - 4 = 41/100
Формат вывода
Артефакт: audit/doc-lint-report.md
# Doc-Lint Report
> Дата: {YYYY-MM-DD}
> Scope: {описание scope}
> Health Score: {N}/100 ({оценка})
## Summary
| Метрика | Значение |
|---------|----------|
| Файлов просканировано | N |
| CRITICAL | N |
| WARNING | N |
| INFO | N |
| Health Score | N/100 |
| Кластеров дубликатов | N |
## File Inventory
| # | Файл | Строк | Тип | Size Status |
|---|------|------:|-----|-------------|
| 1 | ... | ... | ... | OK/WARNING/CRITICAL |
## CRITICAL Findings
| # | Файл | Фаза | Описание | Рекомендация |
|---|------|------|----------|--------------|
## WARNING Findings
| # | Файл | Фаза | Описание | Рекомендация |
|---|------|------|----------|--------------|
## INFO Findings
| # | Файл | Фаза | Описание | Рекомендация |
|---|------|------|----------|--------------|
## Duplicate Map
### Кластер D-1: {название паттерна}
- **Тип:** Exact / Near-duplicate / Conceptual
- **SSOT Owner:** {файл}
- **Найдено в:** {список файлов с номерами строк}
- **Рекомендация:** Оставить в {Owner}, в остальных заменить ссылкой
### Кластер D-N: ...
## SSOT Refactoring Plan
| # | Действие | Файл | Что сделать |
|---|----------|------|-------------|
| 1 | REMOVE | file.md:10-25 | Удалить копию Tech Stack, добавить ссылку |
## Statistics
- Общий объём документации: {N} строк в {M} файлах
- Средний размер файла: {N/M} строк
- Файлов в пределах нормы: {X}/{M} = {%}
- Health Score: {формула с подстановкой}
Post-Check Scorecard
Формат Post-Check — аналогично /spec-audit (см. qa_agent.md § Skill Completion Protocol, qa_agent.md § Quality Gates).
Post-Check Scorecard:
## Scorecard
| Критерий | Результат |
|----------|-----------|
| Все файлы просканированы | X/Y = NN% |
| Line counts верифицированы | ✅/❌ |
| Cross-file detection выполнен | ✅/❌ |
| Каждый finding имеет severity + рекомендацию | X/Y = NN% |
| Нет placeholder {xxx} | ✅/❌ |
| SSOT owner назначен для каждого кластера | X/Y = NN% |
| Формулы с числителем/знаменателем | ✅/❌ |
### Итоговый Score: NN%
Quality Gates
Anti-Patterns (BANNED)
False Positive на одинаковых заголовках
❌ Flagging таблиц с одинаковыми заголовками но разными данными как "duplicate"
✅ Сравнивать содержимое ячеек, не только headers
Phantom Findings
❌ Генерировать findings на основе предположений без чтения файла
✅ Каждый finding подтверждён содержимым файла (строка, фрагмент)
Missing Context
❌ "File is too long"
✅ "CLAUDE.md: 305 строк > порог CRITICAL (300). Рекомендация: вынести секцию X в qa_agent.md"
Over-flagging Intentional Repetition
❌ Flagging ссылок на паттерны как дубликатов (ссылки — не дубликаты)
✅ Отличать полное копирование от ссылок и краткого упоминания
Связанные файлы
| Файл | Содержание |
|---|
references/check-rules.md | Пороги размеров, сигнатуры дубликатов, SSOT-матрица, Diataxis-маркеры |
references/best-practices.md | Корпоративные практики: Google, Amazon, Diataxis, Microsoft, GitLab, Stripe |
Завершение
После создания отчёта и скрипта — напечатай блок SKILL COMPLETE (формат в qa_agent.md § Skill Completion Protocol).
✅ SKILL COMPLETE: /doc-lint
├─ Артефакты: audit/doc-lint-report.md, audit/safe-fix.sh
├─ Compilation: N/A
├─ Upstream: нет
└─ Score: {Health Score}/100
