--- name: ckb-onboard-me description: Walk the wiki knowledge graph for a topic and print a guided reading order — a short overview plus the best sequence of pages to read, prerequisites first. Use for "onboard me on X", "where do I start with X", "walk me through X", "mini tour of X", or "what should I read to understand X". --- # Onboard me (guided wiki tour) skill ## Purpose Read-only: never writes `wiki/` or `wiki/log.md`, adds no claims. The route walks the graph outward from the topic, foundations first. If the wiki has nothing on the topic, say so rather than invent a tour. ## How to run this skill ### Step 1 — Resolve the topic to a starting page Read the cheap indexes first, in cascade order (first match wins): 1. `wiki/index.md` — match the topic against the **Use when** column. 2. `wiki/entities/index.md` — match against entity titles and their `tldr`. 3. If nothing local matches, check each `linked//` index, then each `libs//` index (alphabetical). The local `wiki/` always wins if both have a candidate. Pick the single best-matching page as the **anchor** of the tour. - **No match anywhere** — tell the user the wiki has nothing on that topic yet. Offer the closest 2–3 pages by title/`tldr` if any are vaguely related, and suggest running Ingest to add the material. Do not fabricate a tour. - **Several equally good anchors** — list them (title + `tldr`) and ask which one to start from, or offer to build a short tour that covers all of them. ### Step 2 — Walk the graph outward from the anchor Read `wiki/graph/edges.json`. Edges are typed relationships between entity pages (`uses`, `depends_on`, `caused`, `contradicts`, `supersedes`) with a `source` and a `target`. Starting from the anchor, do a breadth-first walk: - Collect every page directly connected to the anchor (anchor is `source` or `target` of the edge). - Follow one more hop out from those pages. **Stop at 2 hops** — a tour is a route, not the whole map. Keep a visited set so cycles don't loop. - Cap the tour at roughly **8 pages**. If the 2-hop neighbourhood is larger, keep the pages closest to the anchor and highest `confidence` / `retention: high`, and tell the user you trimmed it (say how many were left out) rather than silently dropping them. **If `edges.json` is missing or empty** (no ingest has extracted edges yet), fall back to link-following: read the anchor page and collect the pages it links to via `[[wikilinks]]` and `[markdown](path.md)` links, then one hop out from those. Same 2-hop, ~8-page, visited-set rules apply. Note in the output that ordering came from page links rather than the typed graph. ### Step 3 — Order the pages pedagogically The reading order is the whole point — don't just dump the neighbourhood. Order by dependency direction, not by hop distance alone: 1. **Foundations first.** A page the anchor `depends_on` or `uses` is a prerequisite — it comes *before* the anchor. Recurse: a prerequisite's own prerequisites come before it. 2. **The anchor** — the topic itself, once its groundwork is laid. 3. **Builds-on / related** — pages that `depend_on` or `use` the anchor, or are related without a clear dependency, come after. These are "where to go next." 4. Put `contradicts` / `superseded_by` links near the page they qualify, with a note that they offer a competing or newer view. Within a tier, order by `confidence` then `last_updated` (higher/newer first) so the most solid reading comes first. Read each page's `tldr` (frontmatter) to write its one-line "what you'll find" — only open the body if the `tldr` is missing or too thin to describe the page. ### Step 4 — Print the tour Print to chat (this skill produces a message, not a file). Use this shape: ```markdown ## Guided tour: [Topic] [2–3 sentence overview: what the topic is and what this tour will teach you, synthesized from the anchor page's tldr and its immediate context.] **Reading order:** 1. **[Page title](wiki/entities/foo.md)** — *foundation.* [what you'll find, and why it's first — e.g. "the concept everything here builds on."] 2. **[Page title](wiki/entities/bar.md)** — *the core.* [what you'll find.] 3. **[Page title](wiki/entities/baz.md)** — *builds on it.* [what you'll find.] ... **After this you'll understand:** [one line on the payoff — what the reader can do or reason about once they've read the sequence.] ``` Rules for the output: - Use clickable markdown links to the actual pages (project-root-relative, e.g. `wiki/entities/foo.md`), so the reader can jump straight in. - Label each step with its role in the tour (*foundation* / *core* / *builds on it* / *alternative view*) so the ordering logic is visible. - Keep each "what you'll find" to one line, drawn from the page's `tldr`. - If pages came from `linked/` or `libs/`, link them with their full cascade path and mark them as upstream. ### Step 5 — Offer follow-ups Close with a short offer: to go deeper on any single step, to widen the tour (3+ hops), or to start a different topic. Don't act on these unless asked. ## Edge cases Unusual situations — an empty target, a partial run, a conflicting state, a missing dependency — are catalogued in [`references/edge-cases.md`](references/edge-cases.md). Read that file when a run hits something the steps above don't cover; don't load it otherwise.