---
name: court-practice
description: >
  Поиск и анализ судебной практики Верховного Суда РФ (СКГД и СКЭС) по базе из ~5300 обзоров
  определений ВС РФ за 2018–2026 гг. Используй этот скилл всякий раз, когда пользователь:
  просит найти судебную практику по какому-либо вопросу; хочет подтвердить правовую позицию
  ссылками на определения ВС РФ; спрашивает, как суды разрешают тот или иной спор;
  упоминает СКГД, СКЭС, Верховный Суд, определения ВС; просит подобрать практику для
  процессуального документа (иска, отзыва, жалобы, заключения); задаёт вопрос по российскому
  гражданскому, арбитражному, корпоративному, банкротному, семейному, жилищному,
  земельному, страховому праву и хочет знать позицию судов; просит проанализировать
  конкретную норму ГК/ГПК/АПК/ЖК/СК/НК/КоАП в контексте судебной практики.
  Также срабатывай при упоминании «судебная практика», «позиция ВС», «определение ВС»,
  «практика коллегии», «обзор практики», и при любых запросах, где ссылка на практику ВС
  повысила бы качество ответа — даже если пользователь прямо об этом не просит.
---

# Скилл: Поиск по судебной практике ВС РФ (СКГД и СКЭС)

## Что это

База содержит ~5300 структурированных обзоров определений Верховного Суда РФ из четырёх
Telegram-каналов (СКГД/СКЭС original, Новости ВС РФ, СУДЕБНАЯ ПРАКТИКА, ЭКОНОМКОЛЛЕГИЯ
FRESH). Период: 2018 — 2026.

Каждый обзор содержит: заголовок, реквизиты определения, фабулу, позиции нижестоящих
судов, позицию Верховного Суда, тематические хештеги, ссылки на нормы.

### Тематический охват

Основные направления (по количеству обзоров):
банкротство (350+), гражданский процесс (190+), арбитражный процесс (130+),
недвижимость, убытки, страхование, ЗПП, неустойка, семейные споры, договоры,
аренда, сделки, подряд, корпоративные споры, налоги, моральный вред, лизинг,
судебные расходы, залог, неосновательное обогащение, субсидиарная ответственность,
исковая давность, оспаривание сделок, земельные споры, трудовые споры, жилищные
споры, цессия, ДДУ, деликт, ОСАГО, наследство, IP/авторское право и другие.

## Архитектура поиска

База предварительно проиндексирована в двух слоях:

**Лексический слой (BM25).** Лемматизация через pymorphy3, BM25-индексы по
структурным секциям обзора (заголовок, фабула, позиция нижестоящих судов,
позиция ВС РФ), нормализация номеров дел для дедупликации, удаление стоп-слов.

**Семантический слой (Voyage AI).** Для каждого обзора рассчитан 1024-мерный
эмбеддинг через voyage-3-large по объединённому тексту «заголовок + позиция ВС +
фабула». Эмбеддинги нормализованы, хранятся в `data/embeddings.npy` (~21 МБ).

По умолчанию работает **гибридный поиск** — BM25 и семантика объединяются через
Reciprocal Rank Fusion (RRF). Это покрывает и точные термины, и синонимию.

### Когда что лучше

Чистый **BM25** (`--no-semantic`) сильнее на запросах с конкретными терминами:
«двойная продажа», «ст. 333 ГК», номер дела, имя стороны.

Чистая **семантика** (`--semantic-only`) сильнее на синонимичных запросах:
«снятие корпоративной вуали» находит про привлечение бенефициаров,
«истребование из чужого незаконного владения» находит про виндикацию.

**Гибрид** (по умолчанию) — оптимальный baseline для большинства запросов.

## Команды поиска

```bash
# По умолчанию — гибрид BM25 + семантика
python3 scripts/search.py "ключевые слова"

# Чистый BM25 (без вызова Voyage API, бесплатно)
python3 scripts/search.py "ст. 333 ГК неустойка" --no-semantic

# Чистая семантика — для запросов с синонимами или абстрактных формулировок
python3 scripts/search.py "снятие корпоративной вуали" --semantic-only

# Фильтр по коллегии
python3 scripts/search.py "запрос" --court СКЭС --limit 15

# Фильтр по тегу или статье закона
python3 scripts/search.py "запрос" --tag банкротство
python3 scripts/search.py "запрос" --article "ст. 333 ГК"

# Фильтр по периоду
python3 scripts/search.py "запрос" --year-from 2024
python3 scripts/search.py "запрос" --year-from 2023 --year-to 2024

# Полный текст обзоров (для анализа с цитатами)
python3 scripts/search.py "запрос" --full --limit 5

# Только по тегу, без текстового запроса
python3 scripts/search.py "" --tag залог --limit 20

# Диагностика: разбор скоринга по компонентам
python3 scripts/search.py "запрос" --explain --limit 5

# Без дедупликации (показать все вхождения, в т.ч. дубли из разных каналов)
python3 scripts/search.py "запрос" --no-dedup

# Утилиты
python3 scripts/search.py --stats         # статистика индекса
python3 scripts/search.py --list-tags     # все хештеги с частотами
```

## Технические зависимости и настройка

### Установка зависимостей

Скрипты автоматически ставят при первом запуске: `pymorphy3`, `rank_bm25`, `numpy`,
`voyageai`. Если установка не удалась, выполните вручную:

```bash
pip install --break-system-packages pymorphy3 rank_bm25 numpy voyageai
```

### API-ключ Voyage

Семантика и гибридный поиск требуют ключ Voyage AI. Скрипты ищут его в двух местах,
в порядке приоритета:

1. **Переменная окружения `VOYAGE_API_KEY`** (стандартный способ для CLI/dev):
   ```bash
   export VOYAGE_API_KEY=<your-key>
   ```

2. **Файл `data/.voyage_config.json`** (для claude.ai web, где env-переменные
   недоступны). Структура:
   ```json
   {
     "voyage_api_key": "pa-..."
   }
   ```

В этой сборке скилла ключ уже зашит в `data/.voyage_config.json` — скилл работает
сразу из коробки. Чтобы заменить ключ (например, после ротации) — откройте файл
и впишите новый в поле `voyage_api_key`.

Без ключа работает только режим `--no-semantic` (чистый BM25). Скрипты делают
graceful fallback на BM25 с предупреждением.

**Стоимость**: один поисковый запрос эмбеддит сам запрос (~$0.0001). Эмбеддинги
запросов кешируются в `data/query_cache.pkl`, повторные одинаковые запросы
бесплатны.

### Сборка индекса

Если файлы индекса отсутствуют или устарели:

```bash
# Шаг 1: BM25-индекс (~10 секунд, не требует API)
python3 scripts/index.py --rebuild

# Шаг 2: семантические эмбеддинги (~1 минута, ~$0.60)
python3 scripts/embed.py --rebuild
```

Эмбеддинги опциональны. Без них работает только BM25.

## Скоринг

### BM25-слой

1. **BM25 по секциям** с весами: заголовок ×3, позиция ВС ×3, хештеги ×5,
   полный текст ×1, фабула ×0.7.
2. **Boost за свежесть**: до +30% для свежих, экспонента с периодом 4 года.
3. **Boost за фразовое соседство**: ×1.5 при близости лемм запроса (≤3 позиции).
4. **Boost за структурированность**: ×1.10 если есть выделенная секция «Позиция ВС».

### Семантический слой

Cosine similarity между нормализованным эмбеддингом запроса (через voyage-3-large
с `input_type=query`) и эмбеддингами документов.

### Гибрид (RRF)

```
RRF(d) = Σ_L  w_L / (60 + rank_L(d))
```

где `L` — списки top-100 от BM25 и от семантики, `w_L` — вес списка (по умолчанию
оба = 1.0), `60` — константа из статьи Cormack (2009).

Преимущество RRF: не требует калибровки скоров между разнородными системами
(BM25 даёт 30-200, cosine даёт 0-1). Работает по рангам, а не по значениям.

После RRF применяются те же boost-факторы (свежесть, фразовое соседство), плюс
**дедупликация** по нормализованному номеру дела.

### Лемматизация и стоп-слова

Запрос автоматически лемматизируется и очищается от стоп-слов:
«оспаривание», «оспорил», «оспоренный» дают одну лемму «оспорить»;
слова «суд», «вс», «рф», «дело», «определение» отфильтровываются как шум.

## Стратегия поиска для агента

**Гибрид как baseline.** Для большинства запросов первый вызов — без флагов:
```bash
python3 scripts/search.py "запрос" --limit 10
```

**Узкие запросы — BM25.** Если запрос содержит точные термины (статья закона,
имя стороны, реквизиты дела) — лучше `--no-semantic`. Семантика на таких запросах
может уводить в тематически близкое, но фактически нерелевантное:

```bash
python3 scripts/search.py "ст. 333 ГК неустойка" --article "ст. 333 ГК" --no-semantic
python3 scripts/search.py "А40-12345/2023" --no-semantic
```

**Абстрактные запросы — семантика.** Доктринальные понятия, которые могут
описываться разными словами:

```bash
python3 scripts/search.py "снятие корпоративной вуали" --semantic-only --limit 10
python3 scripts/search.py "виндикация" --semantic-only --limit 10
python3 scripts/search.py "кабальная сделка" --semantic-only --limit 10
```

Семантика найдёт обзоры, в которых эти понятия описаны через ст. 53.1 ГК,
«истребование из чужого незаконного владения», «ст. 179 ГК» и т. п.

**Несколько запросов с синонимами для полноты.** Даже семантика не идеальна.
Для важной задачи делай 2–4 запроса с разными формулировками и объединяй:

```bash
python3 scripts/search.py "снятие корпоративной вуали" --semantic-only
python3 scripts/search.py "контролирующее лицо ответственность" --tag банкротство
python3 scripts/search.py "" --article "ст. 53.1 ГК"
```

**Сужение через фильтры.** Если результатов слишком много:
`--court СКЭС`, `--year-from 2023`, `--tag`, `--article`.

**Глубокий анализ через `--full`.** После поиска топ-релевантных запроси полный
текст лучших — без этого ответ будет поверхностным.

**Диагностика через `--explain`.** Покажет ранг в BM25-списке и в семантическом,
скоры обоих, применённые boost-факторы. По вкладу видно, что работает.

**Если ничего не найдено**: переформулируй с доктринальной лексикой; включи
семантику если был `--no-semantic`; проверь смежные хештеги через `--list-tags`;
если темы реально нет в базе — честно скажи.

## Формат ответа пользователю

### Для каждого релевантного акта:

1. **Реквизиты**: полное наименование определения (номер, дата, дело), коллегия.
2. **Фабула** (кратко, 2–3 предложения): кто, с кем, о чём спор.
3. **Позиция ВС РФ**: ключевые правовые выводы — самое ценное, дай максимум содержания.
4. **Релевантность**: как данный акт соотносится с запросом, почему полезен.
5. **Рекомендация по применению**: как использовать в иске, отзыве, как контраргумент.

### Общая аналитика (в конце):

Тенденция в практике ВС по данному вопросу. Эволюция позиций или противоречия
между актами. На что обратить внимание при использовании.

### Если нужен файл

Когда пользователь готовит документ (иск, отзыв, заключение, аналитическую записку),
оформи подборку практики в структурированном виде, пригодном для включения в документ.

## Важно

- Не придумывай судебные акты — выдавай только то, что реально есть в базе.
- Если по запросу мало релевантного, скажи об этом честно и предложи альтернативы.
- База содержит обзоры, а не полные тексты определений — рекомендуй обращаться к
  полному тексту на сайте ВС РФ или в КонсультантПлюс при необходимости.
- Всегда указывай реквизиты определения, чтобы пользователь мог проверить.
- Если индекс отсутствует — пересобери:
  `python3 scripts/index.py --rebuild && python3 scripts/embed.py --rebuild`.
- Файл `data/query_cache.pkl` создаётся автоматически и накапливает эмбеддинги
  поисковых запросов. Удаление безопасно — пересоздастся при следующем поиске.