| name | clarity-validator |
| description | This skill should be used when the user asks to "validate text", "check consistency", "проверь консистентность", "валидация текста", "проверка слоёв", "layer check", "clarity check", "проверь логику текста", "найди противоречия", "check cross-file consistency", "терминология дрифтит", "смешение слоёв", "проверь на синтетику", "AI-паттерны в тексте", "выдуманный флоу", "negation of nothing", "leaked invariant". Also triggered proactively by an orchestrating agent after review rounds, before docs-repo publication, and after batch edits to documentation. Catches 12 common AI-authoring antipatterns with FPF grounding. |
| version | 0.2.1 |
Clarity Validator
Валидация консистентности текстов на основе FPF (A.7 Strict Distinction + A.10 Evidence Graph +
A.1.1 BoundedContext + Intellect Stack). Выявляет смешение когнитивных слоёв, противоречия
между файлами, скачки логики, терминологический дрифт и 12 специфичных для AI-авторов
синтетических паттернов (negation of nothing, выдуманный флоу, leaked invariants,
имитация авторитета через цифры и другие).
Когда запускать
| Триггер | Инициатор |
|---|
| После раунда ревью | оркестратор (проактивно) |
| Перед коммитом в docs-репозиторий | автор / оркестратор |
| После серии правок в нескольких файлах | автор / оркестратор |
| По запросу | пользователь |
Входные данные
Принимает один или несколько файлов:
- Один файл: полная проверка слоёв + логики + терминологии внутри файла
- Несколько файлов: дополнительно кросс-файловая проверка (консистентность + терминология между файлами)
- Директория: проверить все .md файлы в директории и связи между ними
Если файлы не указаны — спросить у вызывающего.
Пять проверок
1. Смешение когнитивных слоёв (Intellect Stack)
Каждая секция документа должна содержать утверждения одного когнитивного слоя:
| Слой | Вопрос | Маркеры |
|---|
| Structure | Из чего состоит? | Перечисления, определения, таблицы состава |
| Knowledge | Что наблюдаем? | «Показывает», «даёт сигнал о», факты, метрики |
| Action | Что делать? | Императивы: «задавай», «фиксируй», «не тестируй» |
| Strategy | Как выбирать? | «Если X → Y», правила решения, приоритеты |
| Governance | Кто решает? | Ответственные, процессы согласования, SLA |
Процедура проверки:
- Прочитать файл целиком
- Для каждой секции определить заявленный слой по заголовку
- Пройти по утверждениям, определить фактический слой каждого (тест: «могу наблюдать» = Knowledge, «должен сделать» = Action, «выбираю» = Strategy)
- Если заявленный ≠ фактический → находка
Подробные примеры и тесты: references/intellect-stack.md
2. Консистентность между файлами
Одно правило не должно противоречить себе в разных документах.
Процедура:
- Извлечь ключевые утверждения из проверяемого файла (правила, критерии, определения, SLA)
- Для каждого — Grep по связанным файлам
- Сравнить формулировки
- Расхождение → находка (противоречие / дублирование / устаревшая ссылка)
3. Логика аргументации
Выводы должны следовать из посылок.
Что ищем:
- Вывод без посылки (утверждение «потому что Y» — но Y не установлено)
- Скачок логики (из A следует C, но B пропущен)
- Self-justifying loop («делаем X, потому что X работает»)
- Circular reference (A → B → A, ни одно не самодостаточно)
- Assertion без evidence (факт без источника)
4. Терминология
Одни вещи — одними именами. Разные вещи — разными.
Что ищем:
- Одна вещь — разные имена (синонимы: «блок» / «секция» для одного)
- Одно имя — разные вещи (омонимы)
- Неуместная иноязычная вставка рядом с аналогом языка документа (но НЕ устоявшиеся заимствования — «фидбек», «баг»; при сомнении — спросить Человека, см. паттерн 6)
- Дрифт внутри файла (в начале «мерж», в конце «слияние»)
- Расхождение с глоссарием проекта (если есть)
Подробные процедуры и форматы находок: references/checks-detail.md
5. Синтетические паттерны AI-текста
Готовый каталог из 12 паттернов, которые AI-авторы систематически вносят в документы.
Не нужно выводить проблему логически — сравнение с шаблоном.
| # | Паттерн | Маркер | FPF |
|---|
| 1 | Negation of nothing | «Без X» где X не обсуждался | A.1.1 |
| 2 | AI-метки провенанса | (Owner, Q5), (Alt-A, D2) | A.7 |
| 3 | Плейсхолдеры без флоу | [имя], [дата] без источника | A.7 |
| 4 | Выдуманный флоу | «бот назначает ревьюера» — не проверено | A.7 |
| 5 | Имитация авторитета через цифры | «80%», «15-20 часов» без источника | A.10 |
| 6 | Неуместная иноязычная вставка | чужое слово при наличии аналога (не устоявшееся заимствование; спорное → к Человеку) | F.0.1 |
| 7 | Design/Run-time смешение | «Alt-B рассмотрен» в публичном тексте | A.7 |
| 8 | Панибратский/канцелярит тон | «все мы ребята», «в рамках» | BoundedContext |
| 9 | Self-justifying loop | «X работает, потому что X» | A.10 |
| 10 | Ссылка на несуществующее | ссылки на файлы/роли которых нет | A.10 |
| 11 | Скачки логики | вывод без посылки | B.5 |
| 12 | Дублирование вывода | одно правило в двух секциях | A.11 |
Критические: 1, 3, 4, 5, 7, 9, 10, 12. Рекомендации: 2, 6, 8, 11.
Полные определения, FPF-обоснования и примеры до/после — в references/synthetic-patterns.md.
Примеры находок на нейтральном домене — в references/examples.md.
Перекрытие проверок и паттернов. Паттерны 11 (Скачки логики) и 12 (Дублирование) —
это каталог-форма проверок 3 (Логика) и 2 (Консистентность). Не репортить одно и то же
дважды: если находка уже зафиксирована в проверке 5 по паттерну 11/12, не дублируй её
в проверках 3/2 — оставь один раз.
Правило применения всех 5 проверок
Применять в указанном порядке:
- Сначала проверка 5 — быстрое сопоставление с паттернами. Большинство находок AI
ловятся здесь.
- Затем проверка 1 — смешение слоёв. Требует вдумчивого чтения.
- Проверка 2 — консистентность между файлами. Требует Grep (пропусти находки,
уже пойманные паттерном 12).
- Проверка 3 — логика. Требует отслеживания цепочек «посылка → вывод» (пропусти
находки, уже пойманные паттерном 11).
- Проверка 4 — терминология. Быстрая, но поверхностная.
Подробные процедуры и форматы находок: references/checks-detail.md
Формат отчёта
# Clarity Validator — отчёт
**Файлы:** [список]
**Дата:** YYYY-MM-DD
## Критические находки
[Находки, блокирующие публикацию]
## Рекомендации
[Находки для улучшения, не блокируют]
## Чисто
[Секции/файлы без замечаний]
## Итого
- Критические: N
- Рекомендации: N
- Проверено секций: N
Каждая находка по шаблону:
ТИП: СЛОЙ-СМЕШЕНИЕ | РАССОГЛАСОВАНИЕ | ЛОГИКА | ТЕРМИНОЛОГИЯ | СИНТЕТИЧЕСКИЙ ПАТТЕРН
Серьёзность: критическая | рекомендация
Файл: [путь]:[секция/строка]
Паттерн: [#N — название, если проверка 5]
Утверждение: «цитата»
Диагноз: [описание, со ссылкой на FPF-основу]
Рекомендация: [направление исправления, не готовый текст]
Серьёзность
| Контекст | Критическая | Рекомендация |
|---|
| Документ для конечного пользователя | Смешение слоёв, противоречие между файлами, вывод без посылки | Терминологический дрифт, дублирование |
| Внутренний артефакт проекта | Противоречие с публичной докой | Всё остальное |
| Черновик (draft) | — | Всё (отметить, не блокировать) |
Что НЕ проверяет этот скилл
- Фактическую корректность утверждений (это задача предметных ролей/ревьюеров)
- Стилистические AI-паттерны в художественной прозе — дистанция, метафоры,
физиология, ритм (это
ai-prose-detector для беллетристики)
- Полноту покрытия процесса или формы (это задача профильной роли)
- Fairness и bias (это задача профильной роли)
Разница с ai-prose-detector: тот ловит стилистические AI-паттерны в художественной
прозе (как написано). Clarity Validator ловит смысловые синтетические паттерны
в технических документах (что утверждается и как структурировано).
Интеграция с оркестратором
При вызове из оркестрирующего агента или скрипта:
- Оркестратор передаёт список файлов и контекст (после каких правок, кто работал)
- Clarity Validator возвращает отчёт
- Оркестратор маршрутизирует находки:
- Критические → правки перед публикацией
- Рекомендации → в следующий раунд ревью или в backlog
- При отсутствии критических → разрешение на публикацию
Дополнительные ресурсы
Справочные файлы
references/intellect-stack.md — 5 когнитивных слоёв: определения, тесты принадлежности, типичные ошибки с примерами (для проверки 1)references/synthetic-patterns.md — 12 AI-паттернов с FPF-обоснованием, маркерами и примерами до/после (для проверки 5, НОВОЕ в v0.2)references/examples.md — Каталог находок с диагнозами на нейтральных примерах. Сверяйся при любой проверке — чаще всего текущая проблема уже встречалась (НОВОЕ в v0.2)references/checks-detail.md — Подробные процедуры для каждой из 5 проверок: что ищем, как проверяем, форматы находок, типичные пары файлов
