116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
---
|
||
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/<name>/` index, then each
|
||
`libs/<name>/` 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.
|