# diagnose — дизайн
Почему диагностика устроена именно так. Как пользоваться — в
[[diagnose — документация]].
## Оглавление
- [[#Назначение и границы]]
- [[#Почему нужен корпус языка]]
- [[#Что пробовали до него]]
- [[#Почему не собрать корпус из своей речи]]
- [[#Исключения — заплатка к корпусу]]
- [[#Пометки модели]]
- [[#Разобранное — память по пометкам]]
- [[#Заведённое гасится вместе с падежами]]
- [[#Какой текст анализируется]]
- [[#Как определяется находка]]
- [[#Решения по разбору слов]]
- [[#Составные слова через дефис]]
- [[#Склейка падежных форм]]
- [[#Кириллица и латиница порознь]]
- [[#Чего диагностика не найдёт]]
- [[#Решения по поведению]]
## Назначение и границы
Скрипт **только находит**. Он не правит словарь и не трогает настройки
приложения — решение по каждой находке принимает человек.
Так же, как `dict` только ведёт словарь, а `apply` только переносит: у каждого
шага свой риск, и смешивать их в одной команде не стоит.
## Почему нужен корпус языка
Задача звучит просто: отделить обычную речь от терминов. Но у «клавиши»
и «hotfix» **одинаковая статистика** — по 15 употреблений в схожем числе
записей. Никакая формула их не различит, потому что различие не в цифрах.
«Клавиши» — обычное слово, «hotfix» — нет. Это знание **о языке**, и взять его
из истории распознавания неоткуда.
Поэтому нужен внешний корпус словоформ. Всё остальное — арифметика поверх него.
### Что пробовали до него
Три подхода проверены на реальном корпусе и отброшены.
**Мера «часто и редко одновременно».** Классическая формула: частота
умножается на редкость. Наверху оказались `что`, `есть`, `это` — частота
перевешивает. Обычные слова встречаются стократно чаще терминов, и бонус
за редкость этого не компенсирует.
**Чистая редкость.** Наверх всплыло то, что встретилось один раз: оговорки
и мусор распознавания. Их почти половина от всех уникальных слов.
**Сортировка по возрастанию частоты.** Идея была в том, что термины
произносятся реже обычной речи. На практике вперемешку пошли `процитируешь`,
`оберни`, `клавиши` — редкие, но совершенно обычные слова. А главный проблемный
термин оказался бы в самом низу: `Claude Code` произносится сотни раз.
Вывод из всех трёх: редкость в собственной речи и специфичность — разные вещи.
### Почему не собрать корпус из своей речи
Такой корпус описывает не язык, а привычки говорящего на момент сбора.
Прочитал книгу, сменил тему работы — и он устарел, а слова из новой области
посыплются в находки как «необычные».
Внешний корпус этим не страдает: язык меняется медленнее.
## Исключения — заплатка к корпусу
Корпус описывает язык не целиком. Новояз, свежие заимствования и англоязычные
слова, которые распознаются верно, в нём отсутствуют — и всплывают как находки
при каждом запуске, хотя чинить в них нечего.
Поэтому у диагностики есть второй источник: список исключений, который ведёт
`dict`. Слово оттуда находкой не становится.
**Почему не дописать корпус.** Он скачан целиком и заменяется целиком: при
обновлении источника правки пропадут. Свои решения обязаны лежать отдельно
от чужих данных.
**Почему не в `notMatch` словаря.** Оно едет в промпт разделом «не путать»
и потому предназначено для слов, созвучных конкретному канону. У обычного
слова канона нет, и предупреждать модель не о чем — а промпт она читает при
каждой диктовке.
**Почему число исключений выводится в шапке.** Подавление не должно быть
молчаливым: список из трёх находок читается по-разному, когда за ним стоит
ноль заглушённых слов и когда двести.
Наполняется список вручную, по одному решению человека на слово, — как и всё
остальное в этом решении. Скрипт сам туда ничего не пишет.
## Заведённое гасится вместе с падежами
Слово считается заведённым не только при точном совпадении, но и когда оно —
**словоформа** чего-то из словаря или исключений.
Без этого каждый падеж приходилось заносить отдельно: `оркестратор` не гасил
`оркестратора`, `транскрибацию` не гасило `транскрибации`. Список исключений
рос бесконечно, а каждый разбор начинался с одних и тех же слов в другом
падеже.
Признак словоформы взят тот же, что при склейке находок в таблице, —
см. [[#Склейка падежных форм]]: общее начало не меньше 80 % длины, расхождение
не больше трёх букв.
```
оркестратор / оркестратора 92 % -> гасится
транскрибацию / транскрибации 85 % -> гасится
постобработчик / постобработки 79 % -> НЕ гасится, разные слова
промпт / промт 67 % -> НЕ гасится, это искажение
```
Последние две строки показывают, что порог работает в обе стороны. Обработчик
и обработка — действительно разные вещи, и то, что они не слились, правильно.
**Чем платим.** Настоящее искажение, похожее на падежную форму, спрячется:
при заведённом `фреймворк` искажение `фреймворг` даёт 89 % и будет сочтено
формой.
Цена принята сознательно. Порог 80 % выбирался ради `промпт`/`промт` и такие
подмены разводит, а то, что проскочит, — одноразовые сбои распознавания,
которые при разборе всё равно закрываются как «игнорируем».
**Проверяются только однословные записи длиной от четырёх букв.** У коротких
слов общее начало набирается случайно, а на фразах вроде `super whisper`
понятие словоформы бессмысленно.
## Какой текст анализируется
Берётся **итоговый текст** — тот, что увидел пользователь: результат работы
языковой модели, а если её в режиме нет, то результат после замен.
Это принципиально. Смотреть можно было бы и на сырой вывод распознавания,
но тогда в находки попадало бы всё, что уже успешно чинится заменами и
промптом, и список состоял бы из решённых задач.
Значит находка по определению — то, что **до пользователя доехало
неисправленным**.
## Как определяется находка
```
слово есть в словаре -> пропустить, уже заведено
слово — форма заведённого -> пропустить, падеж уже разобран
слово есть в исключениях -> пропустить, признано обычным вручную
слово есть в корпусе -> пропустить, обычная речь
иначе -> находка
```
Находки сортируются по частоте: чем чаще слово произносится, тем важнее его
завести. Разовые оговорки сами опускаются вниз и отсекаются порогом.
Проверка по нашему словарю включает и `notMatch` — то, что однажды признано
ложной находкой, больше не всплывает.
## Решения по разбору слов
### Составные слова через дефис
Слово считается обычным, если **все** его части есть в корпусе.
Без этого правила `какие-то`, `какую-то`, `по-умному`, `что-нибудь` попадали
в находки: как единые формы их в списке нет, хотя обе половины — обычные
русские слова. На коротком периоде это была самая крупная группа шума.
При этом `Kanban-доской` и `shell-команды` остаются находками: одна из частей
языку неизвестна. Части короче трёх букв не проверяются — иначе `то`, `либо`,
`нибудь` ломали бы разбор.
### Склейка падежных форм
Формы одного слова показываются одной строкой с суммарным счётчиком.
Признак словоизменения: общее начало занимает **не меньше 80 %** длины слова,
а расхождение — не больше трёх букв.
```
оркестратор / оркестратора общее начало 92% -> одна строка
Kanban-доской / Kanban-доски общее начало 85% -> одна строка
промпт / промт общее начало 67% -> РАЗНЫЕ строки
```
Последний случай объясняет высокий порог. `промт` — не падежная форма,
а искажение. Слить его с `промпт` значит спрятать находку, ради которой скрипт
и запускается.
По той же причине не сводятся разные написания одного названия: `Джарвиса`
и `Jarvis`, `Superwhisper` и `Supervisper`. Они расходятся не хвостом,
и видеть их нужно порознь.
### Кириллица и латиница порознь
Двумя таблицами, потому что латиницы в русском языке нет вовсе — любое
английское слово окажется «необычным» и забьёт общий список, вытеснив
кириллические находки.
Слово с буквами обоих алфавитов считается кириллическим и попадает в первую
таблицу: `Kanban-доской`, `shell-команды`, `JSON-файлов`. Так и правильно —
это русские конструкции с иноязычным корнем, и разбираться с ними надо вместе
с остальной кириллицей.
## Пометки модели
Единственный источник, который не опирается на корпус.
Языковая модель по правилу в промпте оборачивает в знаки `‡ ‡` места, где
слово сидит в фразе криво — не вяжется с соседями, выпадает из смысла.
Скрипт достаёт помеченное и показывает первой таблицей, с куском фразы вокруг.
Нужно это потому, что сравнение с корпусом слепо к целому классу ошибок:
искажение, совпавшее с настоящим словом языка. `ищу` вместо `Issue`, `паф`
вместо `path` — оба есть в корпусе, и никакая арифметика поверх него их
не покажет. Подробнее про правило — в [[apply — дизайн#Пометка неопознанного]].
**Порог частоты на эту таблицу не действует.** Обычная находка при частоте 1 —
скорее всего мусор. Помеченная — наоборот: модель споткнулась осознанно,
и такой сигнал ценен даже в единственном экземпляре. Отсекать его по частоте
значило бы выбрасывать самое полезное.
**Непонятную пометку слушают, а не отгадывают.** Для этого есть отдельный
скрипт — [[listen — документация]]: он даёт ссылку на нужный кусок записи
по таймингам из неё. Контекст в выводе помогает не всегда, а домысел в словаре стоит
дорого.
**Контекст показывается сразу,** в отличие от обычных находок. Метка указывает
точное место, и по фразе обычно видно, что имелось в виду: «надо ‡ищу‡ создать
продукт» читается как `Issue` без гадания. У обычной находки такого места нет —
слово могло встретиться в сотне разных фраз.
**Пометка обрывается переводом строки.** Потерянный моделью закрывающий знак
испортит одно место, а не проглотит половину текста.
## Разобранное — память по пометкам
Пометка стоит в тексте истории и оттуда не исчезнет. Значит разобранная
однажды, при следующем запуске она появится снова — и так вечно.
Обычные находки этой болезнью не страдают: слово уходит в словарь или
в исключения, и оба списка его глушат. У пометки такого дома нет. Она может
оказаться оговоркой (`даю чем я`), обрывком (`виде`) или так и остаться
непонятой — а закрыть её всё равно надо.
Отсюда четвёртый список: текст пометки, кусок фразы, решение и дата.
**Комментарий обязателен.** Через месяц пометка `виде` сама по себе не скажет
ничего; нужен ответ на вопрос «что мы с этим сделали и почему». Список
без комментариев быстро превратился бы в свалку молча заглушённого.
**Контекст сохраняется вместе с решением.** Он есть в момент разбора и стоит
дёшево, а восстановить его потом — значит идти в базу истории руками.
**Пометки на словах из словаря гасятся сами,** без записи в разобранное.
Такая пометка почти всегда стоит в записи, сделанной ДО того, как слово
попало в словарь: модель тогда канона не имела и споткнулась законно. Держать
это в списке разобранного значило бы дублировать словарь.
**Сорванные записи пропускаются целиком.** Распознавание иногда уходит
в бессмыслицу — обычно на тишине, — и модель добросовестно помечает почти
каждое слово. Одна такая запись дала **39 пометок из 45 слов**: четверть
всего списка за четыре дня.
Разбирать там нечего, а по правилу каждую пометку надо закрыть вручную —
то есть сорок бессмысленных вопросов человеку. Признак: помечено больше
четверти слов при четырёх пометках и более. Порог с запасом: у настоящих
записей доля пометок — единицы процентов, ближайшая к границе давала 14 %.
Число пропущенных записей выводится в шапке: подавление не должно быть
молчаливым.
**Фраза гасится, если заведено каждое слово в ней.** Пометка не обязана быть
словом: `кварка имплемент`, `integrate кварк integrate`. Как строка такой
фразы в словаре нет, и она висела в выводе даже после того, как все её слова
были заведены по отдельности.
Проверка идёт по словам, короче трёх букв — пропускаются: предлоги и союзы
иначе рушили бы её, а смысла в них нет. Разбирать в такой фразе действительно
нечего: каждое слово уже разобрано.
## Чего диагностика не найдёт
**Термины, совпадающие с обычными словами.** Для языка `докер` — портовый
рабочий, `обсидиан` — вулканическое стекло, `кварк` и `глюон` — частицы,
`опус` — музыкальное произведение. Все они есть в корпусе, и находкой
не станут.
Отчасти эту дыру закрывают пометки модели — но только когда она спотыкается.
Термин, стоящий в предложении складно, не заметит никто.
**Прижившиеся заимствования.** Список знает `баг`, `релиз`, `хостинг`,
`контент`, `кейс`. Проверено: из двенадцати айтишных слов девять он не знает
(`бэкенд`, `деплой`, `коммит`, `репозиторий`, `фича`, `промпт` и другие),
но три пропускает.
**Слово, которое всегда искажается одинаково.** Если правильная форма
не встречается ни разу, сравнивать не с чем — но такое слово всё равно
попадёт в находки, если языку неизвестно.
Пропуски не критичны: эти слова обычно уже заведены вручную, а новые заметны
при чтении текста.
## Решения по поведению
**Ограничить вывод нечем.** Флага для этого нет вовсе — не «по умолчанию
выводится всё», а «обрезать невозможно».
Сначала такой флаг был, с полным выводом по умолчанию. Убран после того, как
обрезка случилась на практике: показанная человеку половина списка превращает
его согласие в согласие вслепую. Раз обрезать нельзя никогда, флаг только
создаёт соблазн. Длинный вывод — повод сузить период, а не спрятать находки.
**Порог частоты по умолчанию — два.** Три пятых находок встречаются ровно
один раз: на всей истории порог 1 даёт 4307 находок, порог 2 — уже 1670.
Отсеянное — оговорки, обрывки и мусор распознавания вроде «витлений»
или `Pungaline`.
Единица не выбрана потому, что термин, которым пользуются, повторяется.
А если однократное слово всё же окажется нужным, оно всплывёт при следующем
запуске: порог не теряет находку навсегда, он откладывает её разбор
до второго употребления.
**Период отменяет ограничение по количеству.** Иначе запрос «за вчера» молча
обрезался бы до одной записи — значение по умолчанию у счётчика.
**Границы суток по местному времени.** История хранится в UTC. Без пересчёта
«вчера» съезжало бы на несколько часов и захватывало соседние сутки.
**Отдельная строка про записи без наших правил.** Если диктовка шла в режиме,
где блока нормализации нет, разбирать находки бессмысленно — сначала надо
переключить режим. Такое уже случалось, и без этой строки было незаметно.
**Корпус вне репозитория.** 33 МБ чужих данных в истории заметок ни к чему;
отсутствие файла — явная ошибка, а не тихая работа вхолостую.
**База читается через временную копию, только на чтение.** Приложение может
работать и писать в неё в этот момент; диагностика не должна ни мешать ему,
ни блокировать файл.
**Сравнение без учёта регистра, показ — как в тексте.** Искать слово, помня
его точное написание, неудобно. Но в выводе оно должно выглядеть так, как
встретилось: `Kanban-доской`, а не `kanban-доской`.
**Слова короче трёх букв пропускаются.** Предлоги, союзы и обрывки
распознавания дают сплошной шум, а полезных терминов такой длины почти нет.
**Фразы из списка шума разбиваются на слова.** Иначе выдуманные распознаванием
титры попадали бы в находки по частям: сама фраза заведена целиком, а её слова
языку неизвестны.
**Папка словаря подменяется переменной `SW_DICT_DIR`.** Нужно, чтобы прогонять
диагностику против тестовой копии, не трогая рабочую. Исключения читаются
из той же папки и подменяются вместе со словарём.