doc-lint

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:

1. NO CHAT TABLES: Никогда не выводи таблицы (Inventory, Findings, Stats) в чат. Только в файл отчёта.
2. NO LISTS: Не перечисляй проверенные файлы в чате.
3. 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

• Все файлы в scope отсканированы (Glob + count verification)
• Line counts верифицированы через wc -l
• Cross-file duplicate detection выполнен (Фаза 4)
• Каждый finding имеет severity + рекомендацию
• Нет placeholder {xxx} в отчёте
• SSOT owner назначен для каждого кластера дубликатов
• Формулы показаны с числителем и знаменателем (CLAUDE.md requirement)
• Health Score рассчитан и показан с подстановкой

---

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