# Fact Audit > Read-only комплексный аудит качества чужой кодовой базы/системы с приоритизированной критикой, провенанс file:line. Триггеры: «проведи аудит», «покритикуй», «что не так в коде», «найди баги/слабые места». Голое «проверь» на кодовую базу целиком → сюда; один финализированный артефакт на гейте → six-corner-audit; код внешнего заказчика → code-audit-core. Строго read-only, НЕ для написания фичи. - Skill: `vibeengineering-llc/fact-audit` (Agent Skill) - Install (CLI): `npx skillmds@latest add vibeengineering-llc/fact-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/vibeengineering-llc/fact-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: VibeEngineering-LLC (https://skillmd.com/u/vibeengineering-llc) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vibeengineering-llc/fact-audit --- # Fact-Audit — read-only аудит качества по факту Аудит ценен ровно настолько, насколько каждая находка **верифицирована фактом** и **правильно приоритизирована**. Ложная находка в аудите хуже пропущенной: она тратит время команды и подрывает доверие к остальным. Поэтому скилл строит вокруг двух осей — систематическое покрытие (измерения A–H) и доказуемость каждого пункта (провенанс + проверка против намеренного дизайна). Аудит **строго read-only**: ноль мутаций целевого репо. Если репо заморожен — только `git show :path`. Реализацию фиксов делегируешь (это работа автора кода или отдельного субагента), сам только находишь и приоритизируешь. Роль и оркестрация вокруг аудита — в скилле `censor`; этот — про методологию разбора. --- ## Измерения качества A–H (систематическое покрытие) Прогоняй разбор по всем восьми — это защита от «посмотрел только на то, что бросилось в глаза». Каждая находка тегируется измерением. - **A. Correctness** — логика делает то, что заявлено; краевые случаи; off-by-one; неверная модель домена. - **B. Security** — инъекции, XXE/десериализация, креды в коде, небезопасные дефолты, недоверенный вход. - **C. Reliability / error-handling** — тихо проглоченные исключения (`except: pass`/`return None`), отсутствие таймаутов, неустойчивость к сбою. - **D. Reproducibility** — незапиненные зависимости (нет lockfile), недетерминизм (FP/BLAS-порядок, time/random), env-зависимость результата. - **E. Testability / coverage** — что не покрыто; flaky-тесты; тесты, зелёные по неправильной причине; обойдённые/замьюченные гейты. - **F. Maintainability** — мёртвый код, дублирование, god-объекты, связность, «магические» константы без объяснения. - **G. Documentation** — расхождение кода и доков; необъяснённые эвристики; отсутствие провенанса решений. - **H. Process / release-engineering** — CI-гейты, версионирование (SSOT README==const==tag), политика push, two-tier publish, манифест зависимостей. ## Severity P0–P3 - **P0** — ломает корректность/безопасность сейчас; релиз нельзя выпускать. - **P1** — серьёзный дефект, тихая деградация результата, или дыра процесса; чинить до следующего релиза. - **P2** — заметный долг/риск; запланировать. - **P3** — косметика/полировка. Каждая находка: `[severity][измерение] заголовок — file:line — суть — почему это дефект — (если применимо) предлагаемое направление фикса`. ## Провенанс и фиксация на commit - **Каждая** находка ссылается на конкретику: `file:line`, байт-offset, commit SHA, URL. Нет ссылки — нет находки. «Не нашёл» — допустимый и честный результат. - Когда HEAD целевого репо движется (сосед активно работает) — **фиксируй аудит на конкретный SHA**: `git show :path`. Иначе ссылки `file:line` протухают между чтением и доставкой. В шапке критики укажи SHA снимка. - Read-only: не переключай ветки с мутацией, не трогай рабочее дерево соседа. ## Каждую находку — верифицировать по факту Находка существует, только когда подтверждена в источнике. Две типовые ловушки, которые ОБЯЗАН ловить: - **false-green** (ложно-зелёное): гейт/проверка проходит, но не по той причине. Пример: зависимость стоит только в inline-install команде CI, а в манифесте (`requirements.txt`/lockfile) её нет → прод сломается, CI «зелёный». Или CI-гейт замьючен/закомментирован, но числится активным. - **false-red** (ложно-красное): тест краснит гейт не из-за дефекта продукта, а из-за собственной flaky-природы (FP/BLAS-недетерминизм при `-n auto`, гонка порядка). Не выдавай инфраструктурную flaky за баг продукта — но и не позволяй ей маскировать настоящие падения (карантин ≠ решение проблемы). Валидируй вывод любого субагента/Ollama против исходных строк. Субагент заявил «0 hits / кэшей нет» — перепроверь сам прежде, чем внести в критику. ## Дефект vs намеренный дизайн (проверка ПЕРЕД ранжированием) Самая дорогая ошибка аудитора — выдать намеренное решение автора за баг. Прежде чем ранжировать **доменную** находку (физика детектора, бизнес-правило, эвристика идентификации) как дефект — **прочитай документированную методологию/ручные эвристики автора**. Пользователь часто закладывает практические указания («эвристика спектрометра», proxy-нуклиды, grandfather-chain), которые выглядят «странно» вне контекста, но являются осознанным дизайном. - Нашёл «странность» в домене → ищи в `NOTES/methodology/README` обоснование → только если обоснования нет ИЛИ оно противоречит коду, это находка. - Уже внёс находку, а потом нашёл документированный дизайн, который её опровергает → **отзови находку аддендумом** (честная само-коррекция), не тихой правкой. Отзыв с указанием источника дизайна (`methodology.md:296`) — это работающий verify-by-fact, а не слабость. В этой практике так были отозваны две физические находки, когда выяснилось: bare-NPR и raw-branching — намеренны. ## Формат deliverable ВСЕГДА этот скелет (адаптируй заголовки под домен): ``` # Критика <система> — снимок , режим read-only ## Резюме (вердикт одной фразой + счётчики P0/P1/P2/P3) ## Критика по измерениям A–H (по каждому измерению — находки с file:line-провенансом) ## Таблица статуса закрытия | Находка | severity | измерение | file:line | статус | commit-провенанс | ## Приоритизированный план P0→P1→P2→P3 ## Аддендумы / само-коррекции (отозванные находки с указанием источника намеренного дизайна) ``` - **Статус закрытия** ведётся по commit-провенансу: какой коммит закрыл находку (верифицировано фактом, не «автор сказал, что починил»). - **Само-коррекции — аддендумом**, не тихой правкой тела. Прозрачность отзыва так же важна, как сама находка. ## Анти-паттерны - ❌ Находка без `file:line`/SHA. → Нет провенанса — нет находки. - ❌ Ранжировать доменную странность как баг, не прочитав методологию автора. - ❌ Принять «зелёный CI» / «0 hits субагента» на слово (false-green, неверифиц.). - ❌ Тихо удалить отозванную находку (теряется честность аудита) — только аддендум. - ❌ Мутировать целевой репо ради проверки. Аудит read-only; фикс делегируется. - ❌ Аудит «по верхам» вместо прохода по всем A–H.