| name | vibedata-docs-router |
| description | Use when an agent needs to find which Vibedata documentation source(s) cover a topic,
including questions like "where is X documented in Vibedata", "load context for X",
"find docs about Y in vd-intelligence/strategy/architecture/flows", or any question
that requires routing across the Vibedata source graph before reading content.
Auto-activates on Vibedata-specific routing questions; does not activate for generic
web/library docs.
|
Vibedata Docs Router
Routes a topic string to the most relevant Vibedata documentation source nodes in graph.json. The skill's job ends at "here are the N best sources" — it does NOT read the matched files. The calling agent's next step is to read the returned sources.
Why this skill exists
The Vibedata source graph can have dozens of nodes across strategy, architecture, context, flow, and GTM types. Without routing, an agent either reads everything (expensive) or guesses wrong. This skill runs a lightweight keyword-overlap scoring pass so the caller loads only the most relevant nodes.
Step 1 — Fetch the Source Graph
Run via Bash:
gh api -H "Accept: application/vnd.github.raw" repos/accelerate-data/vd-intelligence/contents/reports/graph.json
If the call fails (non-zero exit, 404, or empty response), halt with:
Error: Could not fetch graph.json from accelerate-data/vd-intelligence. Confirm gh is authenticated for that repo and retry.
Step 2 — Tokenize the Topic
The input topic comes from the user's question or the slash-command argument.
-
Lowercase the entire topic string.
-
Split on whitespace and punctuation ([ \t\r\n.,;:!?/()\[\]{}"' + backtick]).
-
Drop tokens that match the stop-word list:
the, a, an, of, in, on, for, with, and, or, is, are, where, how, what,
when, why, vibedata, docs, doc, documentation, source, sources
-
The remaining tokens are the topic tokens (a set — duplicates don't add signal).
Why: Stop words are too common to distinguish nodes. Vibedata-specific terms like "vibedata" and "docs" appear in almost every node and would flood scores.
Step 3 — Score Each Node
Iterate over every node in graph.json["nodes"]. For each node:
Skip rules (apply before scoring):
- SKIP if
type == "code" — code repo nodes are not documentation.
- SKIP if
summary is null AND tags is an empty list — no signal to rank against.
Score computation (additive):
| Signal | Points |
|---|
Each topic token that appears verbatim in tags | +3 per match |
Each topic token that appears in lowercased, whitespace-split summary tokens | +1 per match |
| Any topic token appearing verbatim as a substring in the node id | +2 (applied once, not per token) |
Any topic token appearing verbatim as a substring in canonical_path | +1 (applied once, not per token) |
Why these weights: Tags are curated keywords — a direct match is high-confidence. Summary matches are weaker (longer text, more incidental words). Node-id and canonical-path substring matches are structural signals, worth less than curated tags.
Step 4 — Return Top Results
Collect all nodes with score > 0. Sort descending by score. Take the top 5.
For each result, output:
**<node-id>**
<summary> (if summary is non-null)
(no summary — only canonical_path: <canonical_path>) (if summary is null)
(score=<n>, matched: <comma-separated matched tokens>)
Separate results with a blank line.
Step 5 — Zero-Match Fallback
If no nodes score above 0, output:
No matches in the graph for `<original topic>`. Try broader terms, or load the
full baseline context: strategy, architecture, and context:product.
Fallback sources:
- strategy — <canonical_path of strategy node, or "(see graph.json)">
- architecture — <canonical_path of architecture node, or "(see graph.json)">
- context:product — <canonical_path of context:product node, or "(see graph.json)">
Why: Strategy, architecture, and context:product are the broadest Vibedata docs. If topic-specific routing fails, these three give the widest coverage without loading everything.
What NOT to do
- Do NOT read any of the matched files. Return paths and scores only. The calling agent decides what to fetch.
- Do NOT modify graph.json or any local files.
- Do NOT call the
gh api graph-fetch more than once per invocation.
