skills/skills/using-wiki-graph/SKILL.md

name, author, version, description

name	author	version	description
using-wiki-graph	ours	1.1.0	Use when a question is RELATIONAL about a wiki or any entities in Mappa — «что связывает X и Y», «как связаны», «путь между X и Y», «what connects X and Y», «shortest path» — or about STRUCTURE/HEALTH — «что ссылается на X», «backlinks of X», «сироты», «битые ссылки», «orphan pages». Triggers `mcp__mappa__graph_neighbors|graph_backlinks|graph_path|graph_stats` — детерминированный BFS по рёбрам графа на стороне сервиса (решение 4/7: refs в body → рёбра). Guarded failure-mode: на реляционные вопросы агент читает одну страницу и ОСТАНАВЛИВАЕТСЯ, никогда не ходит по многохоповым цепочкам сам. Адресация — internal id (из wiki_get/entity_search); ответы несут per-type refs полными именами (task:N/inbox:N/wiki:N, решение 20/#1037, конвенция #1028). Read-only, без лиза (карв-аут, решение 19). Skip для одно-страничных контентных вопросов.

using-wiki-graph

Stop and call the graph. On a relational or structural question about wiki-страницы или любые сущности mappa (таски, письма, сессии), не отвечай, прочитав одну страницу — связи образуют граф, который LLM не обходит надёжно чтением. Сервис ходит по рёбрам детерминированно (BFS) и возвращает ответ в нескольких строках; контекст не засоряется.

When to use

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

• relational — "what connects X and Y", "path between X and Y", «что связывает», «как связаны», «путь между»;
• neighbourhood — "neighbours of X", «соседи X», «что рядом с X»;
• incoming — "what links to X", "who references X", «кто ссылается на X», «backlinks»;
• health — "orphan pages", "dangling links", «сироты», «битые ссылки», «здоровье вики».

Precondition — граф реально связан

Граф полезен, когда рёбра есть. Если сомневаешься — сначала mcp__mappa__graph_stats(): edges ≈ 0 ⇒ граф пуст, отвечай чтением. (Слаги без линков рёбер не создают; сироты — норма для разреженных вики.)

Адресация: slug → id (internal)

Тулы graph принимают internal id (SQL PK), который наружу помечен internal (решение 20/#1037). Резолв:

1. mcp__mappa__wiki_get(project, slug) (или entity_search(q, type='wiki')) — из ответа бери id (последнее поле; публичные ref/num — для показа).
2. Передавай id в graph-тулы.
3. Ответы graph несут ref (task:N/inbox:N/wiki:N — полные имена, #1028) на узлах и рёбрах (from_ref/to_ref) — реферируй по ним в ответе, не по id.

Steps

1. Выбери тул по форме вопроса:
   • relational / "what connects" → mcp__mappa__graph_path({from, to}) — кратчайшая неориентированная цепочка.
   • neighbourhood → mcp__mappa__graph_neighbors({id}) — исходящие рёбра узла с резолвом целей (to_ref/kind).
   • "who links to" → mcp__mappa__graph_backlinks({id}) — входящие рёбра.
   • health → mcp__mappa__graph_stats() (nodes/edges/components); сирота конкретной страницы = graph_backlinks(id) пусто.
2. Резолвь id (см. выше), зови graph, отдавай цепочку/список как есть.
3. Пустой path = связи реально нет — так и скажи; не выдумывай цепочку из текстовой близости.

Failure modes

• Страница удалена/не найдена → graph тул вернёт ошибку. Проверь wiki_get — возьми свежий id.
• Разреженный граф → stats показывает ~0 edges. Не форсируй — читай.
• Нет MCP-тулов mappa в сессии → граф недоступен; читай вручную, отметь пользователю, что mappa MCP не подключён.

Side effects

None. Read-only (карв-аут лиза, решение 19): без лиза, без записи, без сети кроме сервиса.

What NOT to do

• Не отвечай на реляционный вопрос чтением одной страницы — это тот самый 0%-recall провал, ради которого скил существует.
• Не тащи всю вики в контекст, чтобы «проследить» связи руками — сервис делает это за ноль токенов.
• Не зови graph на контентные вопросы ("что такое X") — это чтение, не граф.
• Не передавай слаги/пути в graph-тулы — только internal id, и только свежие (удалённая сущность → ошибка).