name: ckb-retrieve description: Governs how a question actually gets answered from the knowledge base. An index entry — a wiki page's `tldr`, a connector-index document/entity page — is deliberately compressed so lazy-loading stays cheap; that compression also means it can be incomplete, paraphrased loosely, or stale relative to the real source. This skill makes "go verify against the source before answering" a standing step, not an optional last resort: every time a page surfaced by the index looks relevant enough to actually ground part of the answer, follow it to its underlying source material — a wiki page's own `## Sources` citations into `raw/archive/`/`outputs/`, or a connector-index page's `resource:` pointer back to the live connector item — before treating its content as settled. Use whenever answering a question or researching a topic from `wiki/`, `linked/<name>/`, or a connector-backed `libs/<name>/` — this is the retrieval half of CLAUDE.md/AGENTS.md §5 QUERY WORKFLOW, always in play, not something the user needs to name explicitly. Distinct from `ckb-onboard-me` (produces a reading-order tour, not an answer to a specific question) and from the write-side skills `ckb-ingest`/`ckb-index-external`/`ckb-lint` (build or repair the index; this skill only ever reads it, plus the sources behind it).

Retrieve (source-verified query) skill

Purpose

The whole point of tldr/lazy-loading (CLAUDE.md/AGENTS.md §1 "Lazy-Loading with 'Use When' Triggers", §5 "QUERY WORKFLOW") is that most of the wiki never has to enter context — a one-sentence summary decides whether a page is worth opening at all. That's the right trade for deciding relevance. It's the wrong trade for grounding an answer: a tldr is a compression of whatever the page's author judged important at write time, a connector-index entity page is (per ckb-index-external) deliberately a thin pointer rather than a synthesis, and either can have drifted from the primary material since — a source updated, a nuance dropped, a paraphrase that's subtly wrong.

This skill closes that gap: once a page looks relevant enough to actually use in an answer, don't stop at its tldr or even its full synthesized body — follow it to the source material that page was built from, and answer from there. It's the difference between citing what the index says about the evidence and citing the evidence.

This skill is read-only. It never writes to wiki/, libs/<name>/, or anywhere else — it only reads what already exists (the index, and the source material behind it) to answer the question in front of it. If verification surfaces a real gap or contradiction worth fixing in the wiki, say so and suggest ckb-lint/ckb-ingest rather than editing anything mid-answer.

Trigger phrases

This is the default retrieval path for any question answered from the knowledge base — the user does not need to name this skill. Typical prompts that should route here:

A direct question answerable from the wiki ("what do we know about X", "what's the status of Y", "who owns Z").
"Look up X" / "check the wiki for X" / "search for X".
Mid-conversation moments where CLAUDE.md/AGENTS.md §5's QUERY WORKFLOW applies — this skill is that workflow's implementation.

Do not use this skill for:

Building or refreshing an index in the first place — that's ckb-ingest (raw material → wiki/) or ckb-index-external (connector → libs/<name>/). This skill only ever consumes what those produced.
A guided reading order across many pages on a topic — that's ckb-onboard-me. This skill answers one question with verified evidence; it doesn't produce a curriculum.
Health-checking the index's own structure (frontmatter, staleness, broken links) — that's ckb-lint. Verification failures found here (Edge cases, below) are worth mentioning to the user as a possible lint finding, but this skill doesn't run the lint checklist itself.

How to run this skill

Step 1 — Read the index

Same cascade order as CLAUDE.md/AGENTS.md §5, first match wins:

wiki/index.md — match the question against the Use when column.
wiki/projects/index.md — if a project scope matches the question, use that project's listed pages, entity pages, raw/archive sources, connector-backed libs, outputs, and graph areas as the first search boundary. A project scope narrows the first pass only; it never hides the rest of the cascade.
wiki/entities/index.md — match against entity titles/tldr.
If nothing local matches: each linked/<name>/ index (alphabetical), then each connector-backed libs/<name>/entities/index.md — for a connector-backed lib this means its generated index (both the Documents and the Entities & Processes sections ckb-index-external produces), never the live source directly. If it isn't built yet, suggest "index external sources" rather than querying the live connector ad hoc from inside this skill.

Step 2 — Shortlist every page that looks relevant

Read the tldr of every page the index match surfaced — don't stop at the first plausible hit. A question is often best answered by triangulating two or three pages (e.g. a concept page plus the specific person/decision page that qualifies it), and a page whose tldr looks only tangential can still be hiding the exact fact needed in its body or its Sources. Keep the shortlist to what's plausibly relevant; this isn't "open everything," it's "don't stop at one."

If index/TLDR matching is not enough, run a local hybrid pass before giving up: use rg for exact tokens across wiki/, raw/archive/, outputs/, and readable upstream indexes; combine those hits with project-scope matches, entity/title/TLDR matches, graph proximity, freshness, confidence, and quality. Prefer exact text matches for error strings, commands, flags, filenames, hostnames, IDs, and other literals; prefer entity/semantic matches for paraphrased questions.

Step 3 — Walk the graph for anything the shortlist missed

If a shortlisted page has edges in wiki/graph/edges.json (or a connector's own graph/edges.json), follow depends_on/uses/caused edges one hop out — the same way §5 Step 4 already directs — to catch a connected page the index text match alone wouldn't have surfaced.

Step 4 — Expand local context and build an evidence packet

For every result that might ground the answer, keep a small evidence packet with:

source path or connector resource
matched claim or short excerpt
source date or last_updated
freshness/confidence/quality signals, when available
project-scope or graph relationship hints, when relevant

When a match is a section, heading, or snippet inside a larger Markdown file, include nearby headings/paragraphs before deciding what it means. Avoid answering from an isolated fragment when the neighboring context changes the interpretation.

Step 5 — Follow every page on the shortlist to its source before answering from it

This is the step this skill exists to enforce. For each page on the shortlist that will actually ground part of the answer:

A wiki/ page — every page synthesized via ckb-ingest carries a ## Sources section citing the exact raw/archive/<date>/... or outputs/... file(s) it was built from. Open the cited file(s) — or the specific section of a large one — and confirm the wiki's claim matches what the primary material actually says. This also often surfaces adjacent detail the synthesis compressed away that's directly useful for the current question.
A connector-index page in libs/<name>/ (a document page, or an entity/process page from the ckb-index-external extraction) — read its resource: field. If the connector is authorized this session (per ToolSearch/MCP auth state), re-fetch the live item for current, complete content rather than trusting the cached tldr — connector pages use a deliberately short freshness_window_days (30, vs. a typical wiki page's 60-90) precisely because external sources drift without notice. If the connector isn't authorized, or the item is a calendar acceptance / metadata-only page with nothing more to fetch, say plainly that the answer relies on the cached index rather than a live re-check, so the user can weigh that.
A linked/<name>/ page — this is already full mirrored content, not a summary; reading the page itself already is reading the source. No extra fetch needed unless that page itself cites something further outside the mirror.

Target the specific claim, not the whole file — a large transcript or deck doesn't need a full read every time, just enough (search for the name/topic, read the surrounding context) to confirm the point actually being used.

Step 6 — Reconcile and answer

If the source confirms the index, answer normally — but note what grounded it (e.g. "per the kickoff transcript cited in gt-fde-access-requirements.md") rather than presenting the answer as if sourced from the tldr alone.

If the source contradicts, extends, or is more precise than what the index said, prefer the source for the answer and say so explicitly — this is exactly the kind of drift ckb-lint's freshness/confidence checks exist to eventually catch, so mention it's worth a lint pass if the gap looks like more than a one-off, but don't rewrite the wiki page yourself mid-answer unless the user asks for that separately.

If no page anywhere is even plausibly relevant, say so — don't verify against a source that has nothing to do with the question just to appear thorough, and don't fabricate an answer either. For durable missing knowledge, add or propose a short wiki/query-gaps.md entry with the question, date, search areas tried, and the smallest missing source/page that would close the gap. If you edit wiki/query-gaps.md, update wiki/log.md immediately.

Edge cases

A cited source file no longer exists (moved, renamed, or cleaned up) — say so plainly rather than silently falling back to the tldr as if it had been verified. Flag it as a likely ckb-lint finding (a broken Sources reference) rather than treating it as a dead end.
Connector item unreachable or connector not authorized this session — state clearly that the answer is based on the cached connector index, not a live re-check, and name which connector would need authorizing to go further.
Question is low-stakes and the matched page is high-confidence, recently updated, and well within its freshness_window_days — still open the source at least once to ground the answer; skip only a second redundant read if the same source has already been opened earlier in the same retrieval pass for another part of the same question.
Many pages are relevant and reading every cited source in full would be excessive — prioritize the sources that actually carry the specific fact the question needs, not every source any shortlisted page has ever cited. Say what was skipped rather than silently narrowing without a note.
The "source" is itself a generated artifact (e.g. an outputs/emails/*.md draft cited as a wiki page's Source) rather than raw external material — that's still the source relative to the wiki page; no further hop beyond it is required.
A connector-index entity/process page's resource: points at a full wiki/entities/ page (per ckb-index-external's thin-page convention) — treat the wiki page as the real source to verify against; the connector page is just the pointer that got you there.
Nothing in the index is even plausibly relevant — say the knowledge base has nothing on this yet, and suggest ckb-ingest (for new raw material) or ckb-index-external (for a connector-backed source) if that seems like the actual gap. For durable gaps, record or propose a wiki/query-gaps.md entry. Don't stretch a weak match into an answer just to have one.

Licensed under the Apache License, Version 2.0 — see LICENSE at the repository root, or http://www.apache.org/licenses/LICENSE-2.0.

12 KiB Raw Blame History