diff --git a/skills/using-wiki/SKILL.md b/skills/using-wiki/SKILL.md index ab17f5b..0b4a909 100644 --- a/skills/using-wiki/SKILL.md +++ b/skills/using-wiki/SKILL.md @@ -1,139 +1,202 @@ --- name: using-wiki author: ours -version: 1.1.0 -description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wiki pattern). Use when the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "use project wiki", "обнови вики", "проверь вики", "запроси вики", "заингесть", "query the wiki". Also use when modifying any file under `.wiki/` — the workflow and formats below are mandatory, and project-specific conventions live in `.wiki/CLAUDE.md`. If `.wiki/` is missing or non-canonical, delegate to `setup-wiki` first (it has its own confirmation gate). Renamed from `wiki-maintainer` at v1.0.0. +version: 2.0.0 +description: > + Policy skill for working with the project wiki in Mappa (Karpathy LLM Wiki + pattern, channel = mappa-сущности, решения 14/15 спеки mappa). Use when the + user asks to ingest a document, answer from the wiki, lint/health-check it, or + says «use project wiki», «обнови вики», «проверь вики», «запроси вики», + «заингесть», «query the wiki». Also use when modifying any wiki page — the + workflow and formats below are mandatory, and project-specific conventions live + in the `CLAUDE` wiki-сущности проекта. Wiki = сущности `type=wiki` в сервисе + (чтение — карв-аут лиза; запись — под лизом проекта, решение 19). Файлового + `.wiki/` больше нет; `setup-wiki` умер (нечего настраивать). --- # using-wiki -> Policy for maintaining an LLM Wiki (Karpathy pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Knowledge is **compiled once and kept current** across three layers, via three named operations, with strict file formats that make the wiki parseable and grep-friendly. This skill governs *usage* of an existing wiki — initial creation and migration to canon are owned by `setup-wiki`. +> Policy for maintaining an LLM Wiki (Karpathy pattern: +> https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) whose pages +> live in **Mappa** as `type=wiki` сущности (решение 14/15), not in files. +> Knowledge is **compiled once and kept current**: three named operations +> (ingest / query / lint), strict page formats that keep the wiki parseable and +> grep-friendly, and a cross-linked graph ([[refs]] → рёбра, решение 4). ## Prerequisites -This skill assumes the project has a canonical `.wiki/` layout: `CLAUDE.md` (schema), `index.md` (catalog), `log.md` (op log), `overview.md`, `raw/README.md`, and the six content directories `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`. +Wiki проекта = сущности в сервисе Mappa (HTTP-ядро, MCP-адаптер `mcp__mappa__*`). +Слаг страницы = путь от корня вики без расширения (`index`, `log`, `CLAUDE`, +`concepts/foo`, `entities/bar`, `packages/baz`, `sources/doc`, `overview`). +Body = frontmatter + markdown как есть (content-модель сохраняется, решение 2). -If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`, or `contradictions/`/`open-questions/` directories are absent) — invoke the `setup-wiki` skill first. It detects the situation (greenfield vs migrate) and creates or migrates the structure with its own confirmation gate. Only after `setup-wiki` finishes should this skill proceed with the operations below. +Проектная вики (scope=project) читается/пишется с параметром проекта; +общая вики (scope=shared) — без проекта. Чей именно вики трогаем, определяет +контекст: `wiki.get(project, slug)` — проектная, `wiki.get(slug)` — shared. -## Three layers (do not blur) +Файловый `.wiki/` в репозиториях — легаси: источник истины — сервис. +Если вики проекта пуста (нет сущностей) — **ничего настраивать не надо** +(setup-wiki умер): первый ingest сам создаёт `CLAUDE`, `index`, `log` (см. Ingest). -1. **Raw sources** — `.wiki/raw/` (or external paths registered in `raw/README.md`). **Immutable.** Read, never edit. The only exception is appending a `> Status` blockquote when the user explicitly asks for a status audit. -2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept / package / source summary pages. -3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what entities, what packages, naming). Always read it first if present; it overrides this skill when it conflicts. +## MCP-поверхность -## First step on every operation +| Операция | Тул | Примечание | +|---|---|---| +| Чтение страницы | `mcp__mappa__wiki_get(project?, slug)` | чтение — карв-аут лиза (решение 19) | +| Поиск страниц | `mcp__mappa__entity_search(q, type='wiki', project?, scope?, limit)` | ILIKE по body/title | +| Захват лиза для записи | `mcp__mappa__task_claim_next(project, owner)` | → `token` (лиз проекта, решение 19); таска может отсутствовать | +| Продление лиза | `mcp__mappa__task_heartbeat(project, claim_token)` | долгие ingest-циклы | +| Создать страницу | `mcp__mappa__wiki_create(project, slug, body, claim_token)` | под лизом | +| Обновить страницу | `mcp__mappa__wiki_update(project, id, title?, body?, claim_token)` | под лизом; id — internal (см. ниже) | -1. Read `.wiki/CLAUDE.md` if it exists. -2. Read `.wiki/index.md` to locate relevant pages. -3. Only then act. +**Запись всегда под лизом.** Мутации wiki гейтятся лизом проекта: без +валидного `claim_token` — 422 busy. Лиз экспирится по TTL (дефолт 600s); +закрыть вручную нечем (кроме `admin_release_lease` для залипших) — пиши, +затем отпусти (не держи лиз на время чтения/размышлений). -If `.wiki/CLAUDE.md` is missing, the layout is incomplete — invoke `setup-wiki` rather than improvising. +**Рефы и id (#1037).** Публичная поверхность несёт per-type реф первым полем: +`ref: "w:3"` (тип+номер, решение 20), `num` следом, глобальный `id` — internal +(последним полем). Для `wiki.update` нужен internal `id` — бери его из ответа +`wiki_get`/`entity_search`. В тексте страниц ссылайся викилинками по слагу +(`[[concepts/foo]]`, решение 4) или per-type рефами (`[[i:N]]`/`[[t:N]]`). -## Three operations +## Три слоя (не смешивать) + +1. **Raw-источники** — `sources/` страницы. Иммутабельны: читай, не + редактируй (единственное исключение — блок-цитата `> Status` по явной + просьбе пользователя). +2. **Вики** — все остальные страницы (entities/concepts/packages/…). +3. **Схема** — сущность `CLAUDE` (slug `CLAUDE`). Конвенции проекта. Читай её + первой; она перекрывает этот скил при конфликте. + +## Первый шаг любой операции + +1. `mcp__mappa__wiki_get(project, 'CLAUDE')` — если есть, читай (схема). +2. `mcp__mappa__wiki_get(project, 'index')` — каталог, найди нужные страницы. +3. Только потом действуй. + +Если `CLAUDE` нет — вики либо новая, либо неухоженная: не импровизируй +структуру, создай `CLAUDE`/`index`/`log` при первом ingest (см. ниже). + +## Три операции ### Ingest — «заингесть X» -1. Read the raw source fully. -2. Extract: entities, concepts, packages, cross-cutting patterns. -3. Create `sources/.md` (one summary page per source, ~50–150 lines). -4. For each affected entity/concept/package page: - - If it exists → update it. **Flag contradictions explicitly** with `> **Противоречие:** источник A говорит X, источник B — Y`. Don't silently overwrite. - - If not → create it. -5. Update `index.md` — add or move entries. -6. Append one line to `log.md` (format below). -7. Report to the user: what created, what updated, what contradictions found. +1. Прочитай источник полностью. +2. Извлеки: entities, concepts, packages, кросс-резы. +3. Создай `sources/` — одну страницу-резюме на источник (~50–150 строк; + ссылку на raw клади в frontmatter `raw_path` + `ingested:`). +4. Для каждой затронутой страницы: + - есть → обнови (`wiki_update(project, id, body, claim_token)`). **Противоречия + помечай явно** блоком `> **Противоречие:** источник A говорит X, источник B — Y`. + Не затирай молча. + - нет → создай (`wiki_create`). +5. Обнови `index` (каталог: одна строка на страницу). +6. Допиши одну строку в `log` (формат ниже). +7. Отчитайся пользователю: что создано, что обновлено, какие противоречия. -**One ingest may touch 10–15 pages. This is normal — that's why LLMs do it.** +**Один ingest может затронуть 10–15 страниц. Это нормально — для того LLM и нужны.** -### Query — вопрос по wiki +Порядок записи: сначала лиз (`task_claim_next`), затем все wiki-мутации одним +циклом (не бери лиз на чтение), затем отпусти (лиз живёт TTL — просто закончи +писать; heartbeat только если цикл реально долгий). -1. Read `index.md` first, then drill into relevant pages. -2. Answer with citations as markdown links to wiki pages. -3. **Compound the wiki.** If the answer is a real synthesis (comparison, analysis, new connection) — ask the user: "Сохранить как страницу wiki?" Good queries become durable pages under `concepts/`, `analyses/`, or similar. -4. Append one line to `log.md`. +### Query — вопрос по вики -### Lint — «проверь wiki» +1. Читай `index` сначала, затем углубляйся в страницы (`wiki_get` по слагу). +2. Отвечай с цитатами-викилинками: `[[concepts/foo]]` (рёбра создаются при + записи, решение 4). +3. **Компаундируй вики.** Если ответ — реальный синтез (сравнение, анализ, + новая связь) — спроси пользователя: «Сохранить как страницу wiki?» Хорошие + вопросы становятся страницами в `concepts/`. +4. Допиши строку в `log`. -Scan for: -- **Contradictions** between pages. -- **Orphans** — pages with no inbound links. -- **Stale claims** — git `log -p` on the raw source shows it was updated after the summary's `ingested:` date. -- **Missing entities** — concepts mentioned in prose but without their own page. -- **Empty/TODO sections.** +### Lint — «проверь вики» -Report as a punch list. Don't delete anything automatically. -Append one line to `log.md` summarizing the findings. +Ищи: +- **Противоречия** между страницами. +- **Сирот** — страницы без входящих ссылок: `mcp__mappa__graph_backlinks(id)` + (id из `wiki_get`) → нет входящих рёбер = сирота (подробнее — using-wiki-graph). +- **Stale-claims** — `updated_at` страницы старше источника, который она резюмирует. +- **Потерянные сущности** — понятия из текста без своей страницы + (`entity_search` по имени → пусто). +- **Пустые/TODO-секции.** -## File formats (MANDATORY) +Отчёт — панч-лист. Ничего не удаляй автоматически. +Допиши строку в `log` с итогом. -### Page frontmatter +## Форматы страниц (ОБЯЗАТЕЛЬНО) + +### Frontmatter ```yaml --- title: Человекочитаемое имя type: entity | concept | package | source | contradiction | open-question | overview tags: [short, tokens] -sources: [../sources/foo.md, ../sources/bar.md] -updated: 2026-04-21 +sources: [concepts/mappa.md] +updated: 2026-08-24 --- ``` -Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`. +Страницы `sources/` дополнительно несут `ingested: YYYY-MM-DD` и `raw_path: …`. +`contradictions/` — `status: open | resolved | accepted-divergence` и `affects:`. +`open-questions/` — `status: open | answered | obsolete` и `touches:`. -Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`. +### Слаги -Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`. +- `kebab-case`, **только латиница**. Кириллицу/др. скрипты транслитерируй + (`план переписывания` → `ozon-client-rewrite`). Оригинальный title — в H1 и frontmatter. +- `entities/`, `concepts/`, `packages/`, `sources/`, + `contradictions/`, `open-questions/`. -### File naming +### `log` — append-only, grep-parseable -- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / other scripts in filenames (`план переписывания` → `ozon-client-rewrite.md`). Keep the original title in the H1 and frontmatter. -- `entities/.md`, `concepts/.md`, `packages/.md` (no `@org/` prefix), `sources/.md`, `contradictions/.md`, `open-questions/.md`. - -### `log.md` — append-only, grep-parseable - -Every entry **must** start with: +Каждая запись **обязана** начинаться с: ``` ## [YYYY-MM-DD] | ``` -Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`. +Операции: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`. +Парсится: `entity_search(q="## [", type="wiki", project=…)` по сущности `log`. -Parseable with: `grep "^## \[" .wiki/log.md | tail -20`. +### `index` -### `index.md` - -Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources / contradictions / open-questions). Update on every ingest. - -### Cross-references - -- Wiki → wiki: relative markdown links, `[Name](../entities/x.md)`. -- Wiki → code: relative path from repo root: `[foo.js](../../packages/api/foo.js)`. -- Wiki → raw: `../raw/`. -- URL-encode spaces in paths (`%20`) and Cyrillic when needed. +Каталог, не нарратив. Одна строка на страницу: `- [Title](concepts/foo.md) — hook.` +Секции по типам. Обновляется на каждом ingest. ## Quick reference -| Situation | Files touched | +| Ситуация | Что трогаем | |---|---| -| Ingest one doc | `sources/.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` | -| Query | (read only) + optionally new wiki page + `log.md` | -| Lint | (read only) + `log.md` | -| Bootstrap / migrate to canon | (delegated to `setup-wiki`) | +| Ingest одного документа | `sources/` (новая) + 3–15 entities/concepts/packages + `index` + `log` | +| Query | (чтение) + возможно новая страница + `log` | +| Lint | (чтение) + `log` | +| Новая вики проекта | первый ingest создаёт `CLAUDE`/`index`/`log` + контент | -## Common mistakes +## Частые ошибки -- **Editing `raw/`.** Don't. Only allowed: status blockquote when user explicitly asks. -- **Dumping raw content into `sources/`.** Summaries are summaries. Link to raw, don't copy it. -- **Silent overwrites.** When a new source contradicts an existing page, flag it with a `> **Противоречие:**` block; don't just overwrite. -- **Narrative `log.md`.** `Today I added…` is wrong. Use `## [YYYY-MM-DD] ingest | `. -- **Non-ASCII file names.** Breaks greppability and cross-platform. Transliterate. -- **Forgetting `index.md`.** Pages not listed there are effectively invisible for future queries. -- **Skipping contradictions in lint.** The wiki's value grows from surfaced tensions, not from false consensus. -- **Improvising layout when canon files are missing.** If the wiki is missing or partial, hand off to `setup-wiki` instead of patching ad hoc. +- **Правка `sources/`.** Нельзя. Только статус-блок по явной просьбе. +- **Дамп сырья в `sources/`.** Резюме — это резюме. Ссылайся на raw, не копируй. +- **Молчаливые перезаписи.** Новый источник противоречит странице — пометь + блоком `> **Противоречие:**`; не затирай. +- **Нарративный `log`.** «Сегодня я добавил…» — неверно. Формат: + `## [YYYY-MM-DD] ingest | <что>`. +- **Не-ASCII слаги.** Ломают grep и кросс-платформенность. Транслитерируй. +- **Забытый `index`.** Страницы без записи в каталоге невидимы для будущих query. +- **Пропущенные противоречия в lint.** Ценность вики — в вскрытых напряжениях, + а не в ложном консенсусе. +- **Запись без лиза.** Wiki-мутации без `claim_token` → 422 busy; не пытайся + писать «напрямую». +- **Держать лиз на чтение/раздумья.** Лиз — на время записи. Чтение — карв-аут. -## When NOT to use this skill +## Когда НЕ использовать этот скил -- Project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular project documentation, not an LLM Wiki. -- User wants a single-file README or ADR — this skill is for persistent interlinked knowledge bases. -- One-off questions about code — use regular file reading, not wiki workflow. +- Проект без вики в mappa (нет сущностей `type=wiki`) — обычная документация, + не LLM Wiki. +- Пользователь хочет однофайловый README/ADR — скил для персистентной + связной базы знаний. +- Разовые вопросы по коду — обычное чтение файлов, не вики-воркфлоу. +- Реляционные/структурные вопросы о вики (связи, сироты, пути) — это + **using-wiki-graph** (`mcp__mappa__graph_*`).