---
name: doc-to-cache
description: "Конвертирует сырую документацию (MD/TXT файлы) из docs/documentation/ или любого пути в структурированные знания tech-research/cache/. Принимает файл или папку (рекурсивно). Триггеры: '/doc-to-cache', 'конвертировать документацию в кеш', 'обработать документацию', 'создать знания из файлов', 'загрузить доки в кеш', 'convert docs to cache', 'process documentation'. Параметр: путь к файлу или папке."
---

# Doc-to-Cache: конвертер сырой документации в кеш знаний

## Обзор

Превращает сырые файлы документации (MD, TXT) в структурированные записи кеша знаний `tech-research/cache/` по 7-категорийному шаблону. Принимает **файл** или **папку** (рекурсивно обходит вложенные).

---

## Вызов

```
/doc-to-cache <путь>
```

**Примеры:**
```
/doc-to-cache docs/documentation/Claude Code Docs
/doc-to-cache docs/documentation/Lang Chain Docs/Lang Graph
/doc-to-cache docs/documentation/Claude_Code_Hooks_Reference_RU.md
```

---

## Алгоритм

### Шаг 1: Определение входа

| Вход | Действие |
|------|----------|
| Файл (.md/.txt) | Обработать один файл |
| Папка | Найти все .md/.txt рекурсивно, обработать каждый |
| Папка с подпапками | Группировать файлы по подпапкам = одна тема на группу |

**Группировка по темам:**
- Файлы в одной подпапке объединяются в одну тему
- Имя темы = нормализованное имя папки (lowercase, дефисы)
- Одиночный файл = одна тема (имя из filename)

### Шаг 2: Определение темы и домена

**Нормализация имени темы:**
```
"Claude Code Docs" → "claude-code"
"Lang Chain Docs/Lang Graph" → "langgraph"
"Протокол контекста модели (MCP)" → "mcp-protocol"
"Language Server Protocol (LSP)" → "lsp-protocol"
"Claude_Code_Hooks_Reference_RU.md" → "claude-code-hooks"
```

**Определение домена:**

| Содержимое/путь | Домен |
|-----------------|-------|
| Claude Code, hooks, skills | `tools` |
| LangChain, chains, prompts | `python` |
| LangGraph, agents, state | `agents` |
| MCP, protocol, server | `tools` |
| LSP, language server | `tools` |
| Qdrant, vector, FAISS | `vector-db` |
| embeddings, sentence-transformers | `embeddings` |
| RAG, retrieval, search | `rag` |
| LLM, Claude API, model | `llm` |

**Определение категории:**

| Тип содержимого | Категория |
|-----------------|-----------|
| Библиотека/фреймворк | `library` |
| Протокол/спецификация | `api` |
| Концепция/подход | `concept` |
| Инструмент | `tool` |
| Алгоритм | `algorithm` |
| Паттерн | `pattern` |

### Шаг 3: Чтение и анализ

Для каждой группы файлов:

1. **Прочитать все файлы** группы (используй `Read` tool)
2. **Объединить содержимое** — устранить дубликаты между файлами
3. **Извлечь знания** по 7 категориям шаблона

### Шаг 4: Заполнение шаблона (7 категорий)

Используй шаблон из `.claude/skills/tech-research/cache/_topic_template.md`.

**Правила трансформации:**

| Из сырого документа | В кеш знаний |
|--------------------|--------------|
| Вступление, история | **Убрать** |
| Маркетинг, buzz-words | **Убрать** |
| Описание "что это" | → **1. Идентификация** |
| Команды установки | → **2. Установка** |
| API/методы/классы | → **3. Core API** |
| Примеры кода | → **4. Паттерны** |
| Архитектура, схемы | → **5. Архитектура** |
| Ошибки, FAQ | → **6. Диагностика** |
| Ссылки, URL | → **7. Источники** |

**Обязательные поля frontmatter:**
```yaml
---
topic: "имя-темы"
domain: "tools|python|agents|rag|embeddings|vector-db|llm|ml|search"
category: "library|api|tool|concept|algorithm|pattern"
created: "YYYY-MM-DD"
last_verified: "YYYY-MM-DD"
version: "если известна"
source_urls: ["docs/documentation/путь/к/исходнику"]
keywords: ["ключевое1", "ключевое2", ...]
---
```

### Шаг 5: Сохранение

1. Записать файл: `.claude/skills/tech-research/cache/<имя-темы>.md`
2. Обновить `.claude/skills/tech-research/cache/_index.json`:
   ```json
   {
     "<имя-темы>": {
       "file": "<имя-темы>.md",
       "domain": "<домен>",
       "category": "<категория>",
       "created": "YYYY-MM-DD",
       "keywords": ["..."],
       "summary": "1-2 предложения"
     }
   }
   ```

### Шаг 6: Отчёт

После обработки всех файлов — вывести сводку:

```
Обработано: 5 тем из 28 файлов
  claude-code (tools) — 8 файлов → claude-code.md
  langgraph (agents) — 12 файлов → langgraph.md
  mcp-protocol (tools) — 6 файлов → mcp-protocol.md
  ...
Кеш обновлён: .claude/skills/tech-research/cache/_index.json
```

---

## Правила качества

| Критерий | Проверка |
|----------|----------|
| Полнота | Все 7 категорий заполнены (хотя бы N/A если данных нет) |
| Копируемость | Команды и код готовы к копированию |
| Без воды | Нет маркетинга, истории, прозы |
| Атрибуция | source_urls указывает на исходный файл |
| Keywords | >= 5 ключевых слов для поиска |
| Размер | Каждый topic-файл <= 500 строк |
| Русский | Описания на русском, код/команды на английском |

---

## Обработка больших папок

Если папка содержит > 30 файлов:

1. **Группировка первая** — покажи пользователю план группировки
2. **Батчевая обработка** — обрабатывай по 5-10 файлов за раз
3. **Прогресс** — показывай сколько обработано из скольки

---

## Обработка дубликатов

Если тема уже есть в `_index.json`:

1. Прочитать существующий topic-файл
2. **Merge** — объединить новые данные с существующими
3. Обновить `last_verified` и `source_urls`
4. Сообщить: "Обновлена существующая тема: <имя>"

---

## Антипаттерны

| Плохо | Почему | Как правильно |
|-------|--------|---------------|
| Копировать файл целиком | Не структурировано | Извлечь по 7 категориям |
| Один topic на файл | Слишком гранулярно | Группировать по папкам |
| Пропустить frontmatter | Индекс не обновится | Всегда заполнять YAML |
| Игнорировать _index.json | Кеш не найдёт тему | Обновлять индекс |
| Огромный topic (>500 строк) | Медленный lookup | Сжимать, выносить детали |