audit-docs
starsforks
How to install audit-docs?
tserentserenov/fmt-exocortex-template/audit-docs
$npx -y skills add TserenTserenov/FMT-exocortex-template --skill audit-docsAudit repository documentation: detect drift between code and docs, report coverage by category. Run manually or on triggered drift critical.
SKILL.md
| 1 | # Audit Docs (R24 Аудитор) |
| 2 | |
| 3 | > **Роль:** R24 Аудитор. Полное описание: `PACK-digital-platform/pack/digital-platform/02-domain-entities/DP.ROLE.024-auditor.md` (WP-224). Маппинг: R24 = VR.R.002. |
| 4 | > **Метод:** R24 coverage по категориям + R23 pair-diff между парами `код файл ↔ docs файл`. |
| 5 | > **Получатель отчёта:** владелец репо в другой временной позиции (категория 3 — внешняя проектная роль). Это аудит в строгом смысле — не автор кода, не ты сейчас. |
| 6 | > **Тип роли (DP.D.080):** R24 — контрольная роль. Read-only к аудитуемым артефактам. Отчёт = output-канал, не изменение аудитуемого. |
| 7 | |
| 8 | Аргументы: $ARGUMENTS |
| 9 | |
| 10 | ## Что делает |
| 11 | |
| 12 | Проходит указанный репо и формирует **отчёт** о расхождениях между кодом и документацией. **Не правит ни код, ни docs** — только отчёт. |
| 13 | |
| 14 | ## Параметр |
| 15 | |
| 16 | - `--repo <path>` (обязателен) или `.` (текущая директория). |
| 17 | |
| 18 | ## Шаг 0. Загрузка контекста |
| 19 | |
| 20 | При старте обязательно прочитать: |
| 21 | |
| 22 | 1. `<repo>/CLAUDE.md` целиком — как любой агент в этом репо. В частности § 10 «Известные ловушки/инварианты» (если есть). |
| 23 | 2. `<repo>/docs/.audit-context.yaml` — категории docs, source patterns, file_naming. Без этого файла аудит невозможен — сообщить и остановиться. |
| 24 | 3. `${IWE_ROOT:-$HOME/IWE}/.claude/sync-manifest.yaml` — найти пары, где `source` или `derived` пересекают этот репо. Использовать как дополнительный источник связей «код ↔ docs». |
| 25 | |
| 26 | ## Шаг 1. R24 coverage по категориям |
| 27 | |
| 28 | Для каждой категории из `.audit-context.yaml`: |
| 29 | |
| 30 | 1. Перечислить все source-файлы (по `source_patterns`). |
| 31 | 2. Для каждого source-файла найти связанный docs-файл по `file_naming` или эвристике. |
| 32 | 3. Посчитать: `coverage % = docs_files / source_files`. |
| 33 | 4. Зафиксировать **gaps** (source без docs) и **orphans** (docs без source). |
| 34 | |
| 35 | ## Шаг 2. R23 pair-diff (drift детекция) |
| 36 | |
| 37 | Для каждой существующей пары `source ↔ docs`: |
| 38 | |
| 39 | 1. Сравнить mtime — если docs старше source более чем на N дней (порог из манифеста или дефолт 7), отметить как кандидат на обновление. |
| 40 | 2. Если есть git history — посмотреть последние коммиты в source и проверить, упоминаются ли затронутые сущности (функции, таблицы, эндпоинты) в docs. |
| 41 | 3. Зафиксировать `drift_candidates` с приоритетом (critical / warn / ok). |
| 42 | |
| 43 | ## Шаг 3. Связь с CLAUDE.md § 10 |
| 44 | |
| 45 | Для каждой ловушки/инварианта из § 10 CLAUDE.md репо проверить: упомянута ли в docs? Если нет — добавить в раздел «Неочевидности». |
| 46 | |
| 47 | ## Шаг 4. Формирование отчёта |
| 48 | |
| 49 | Записать отчёт в `<repo>/docs/audit-reports/audit-YYYY-MM-DD.md` со структурой: |
| 50 | |
| 51 | ```markdown |
| 52 | # Audit report — <repo> — <YYYY-MM-DD> |
| 53 | |
| 54 | ## Coverage по категориям |
| 55 | | Категория | Source файлов | Docs файлов | Coverage % | Статус | |
| 56 | |-----------|---------------|-------------|------------|--------| |
| 57 | |
| 58 | ## Gaps (source без docs) |
| 59 | - ... |
| 60 | |
| 61 | ## Orphans (docs без source) |
| 62 | - ... |
| 63 | |
| 64 | ## Drift candidates (pair-diff) |
| 65 | | Source | Docs | mtime lag | Приоритет | |
| 66 | |--------|------|-----------|-----------| |
| 67 | |
| 68 | ## Неочевидности (§ 10 CLAUDE.md, не покрыто docs) |
| 69 | - ... |
| 70 | |
| 71 | ## Итого |
| 72 | - Coverage суммарный: X% |
| 73 | - Drift critical: N |
| 74 | - Drift warn: N |
| 75 | - Gaps: N |
| 76 | - Orphans: N |
| 77 | ``` |
| 78 | |
| 79 | ## Чего НЕ делает |
| 80 | |
| 81 | - НЕ правит код. |
| 82 | - НЕ правит docs. |
| 83 | - НЕ создаёт draft-PR с предложениями (это будет следующий шаг — `/auto-docs`). |
| 84 | - НЕ принимает решений о категориях docs (новая категория = архитектурное решение, не аудит). |
| 85 | |
| 86 | ## Связь с другими скиллами |
| 87 | |
| 88 | - `/verify` — проверка артефакта по эталону Pack (VR.R.001). `/audit-docs` — кросс-репо coverage аудит (R24/VR.R.002). Разные роли, разные методы. |
| 89 | - `iwe-drift.sh` — детектирует drift между парами в `sync-manifest.yaml` (S-класс). `/audit-docs` — углублённый аудит docs/ внутри одного репо. drift→решение «нужно пройтись /audit-docs» — типовой workflow. |
| 90 | |
| 91 | ## Связь с SC.024.∞ |
| 92 | |
| 93 | Этот скилл реализует Variant C (manual baseline) из дизайна `SC.024.∞ — Auto-update docs/`. После 2 недель обкатки и калибровки точности — переход на Variant A (post-merge GitHub webhook). См. README.md рядом. |
People who liked this also viewed
6 picksType
- grill-with-docsA relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.SkillsJul 2026
- lark-minutes飞书妙记：搜索妙记、查看妙记基础信息、下载/上传音视频、读取或编辑妙记的产物内容、改标题、替换说话人/关键词、申请妙记查看/编辑权限。当给出minute_token、本地音视频文件，要查/改/转妙记产物，或用户明确要主动申请妙记权限时使用；本地音视频转纪要/逐字稿优先走本 skill，不要用 ffmpeg/whisper 本地转写。不负责：获取会议关联妙记，或仅按自然语言标题定位纪要SkillsJul 2026
- lark-markdown飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。SkillsJul 2026
- docxUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', SkillsJul 2026
- edit-articleSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- lark-note飞书会议纪要（Note）直查：已知 note_id 时查询纪要详情、展示类型、关联文档 token，并读取 unified 原始逐字记录。当用户已持有 note_id，或从文档显式 vc-node-id 获得 note_id 时使用。不负责会议/日程/妙记定位、文档标题搜索或 Docx 正文读取。SkillsJul 2026
