ckb/.agents/skills/ckb-retrieve/SKILL.md

---
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 workflow routed by CLAUDE.md/AGENTS.md, 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 index-first
navigation and skill routing) 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 routes a KB question
  to retrieval — 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, first match wins:
1. `wiki/index.md` — match the question against the **Use when** column.
2. `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.
3. `wiki/entities/index.md` — match against entity titles/`tldr`.
4. `wiki/decisions/index.md` — for any "why is it like this", "who decided",
   "when did we choose", or "is that still current" question. If decisions
   *are* the subject of the question, hand off to `ckb-decide`, which owns
   the decisions-scoped path including supersession chains; pull decision
   pages in here as one source among many when they're only part of a wider
   answer. Either way, a superseded decision is history, not noise — say so
   rather than silently answering from the current one.
5. 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/`, `raw/inbox/`, 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.

Sweep `raw/inbox/` even though nothing there has been ingested yet.
Material dropped an hour ago can already hold the answer, and finding it
there is also the clearest possible signal that an `ckb-ingest` run is
overdue — mention that. Say plainly when an answer rests on un-ingested
inbox material rather than on a synthesized page.

Keep each signal's hits as its own ranked list rather than merging them by
eye as you go. Step 4 needs the separate orderings.

### 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 to catch a connected page the index text match alone
wouldn't have surfaced.

For "who knows about X" and "who owns X" questions — both advertised in
the trigger phrases above — the graph is the primary lookup rather than a
fallback. Read the `has_expertise_in` and `owns` edges pointing at the
topic entity and answer from the people or teams on the other end,
ordered by how many distinct sources evidence each edge. Where no such
edge exists yet, fall back to authorship evidence: who the `## Sources`
material actually shows answering questions on that topic. Say which of
the two grounded the answer, since an inferred expert is a weaker claim
than a recorded one.

While the edge file is open, build one more ranked list for Step 4:
**in-degree** — for each candidate already on the shortlist, how many edges
point *at* it.

```bash
python3 -c "import json,collections;e=json.load(open('wiki/graph/edges.json'))['edges'];\
c=collections.Counter(x['to'] for x in e);print(c.most_common(20))"
```

Centrality is a genuinely different signal from every other one in Step 4:
text match, freshness, confidence and quality are all properties of a page in
isolation, while in-degree is what the rest of the KB has to say about it. A
page a dozen others depend on is usually the one that settles a question;
a leaf page with an identical `tldr` usually isn't. Rank only the candidates
already shortlisted — this ranks the shortlist, it doesn't widen it. Skip the
list entirely when `edges.json` is empty or every candidate has in-degree 0,
since a list with no ordering contributes nothing to the fusion.

### Step 4 — Fuse the signals, dedupe, then rerank

Signals disagree, and none of them is trustworthy alone: an exact `rg` hit
can sit in a page that answers a different question, and a confident TLDR
match can be a loose paraphrase of something stale. Don't settle that by
picking a favourite signal — fuse the ranked lists from Step 2.

**Fuse.** For every candidate, sum `weight / (k + rank)` across each list
it appears in, where `rank` is its 1-based position in that list. Use
`k = 10` and a default `weight` of 1.0. A page ranked third in three
different lists beats one ranked first in a single list; consensus is the
whole point.

Give the in-degree list a weight *below* 1.0 (around 0.5 is a reasonable
start). Centrality is a prior, not evidence — it says a page matters
generally, not that it answers this question — so it should break ties
between comparable candidates without ever promoting a page the text signals
didn't surface.

`k = 10` is deliberately smaller than the `k = 60` rank fusion is usually
quoted with. 60 is tuned for retrievers returning hundreds of candidates,
and against the dozen-or-so a local wiki produces it flattens every score
into near-identical values. Raise a list's weight when the question
warrants it — for a pasted error string, command, flag, or ID, weight the
exact-match list around 2.0, because no amount of title/TLDR similarity
should outrank a literal match on the token the user actually pasted.

**Dedupe.** Collapse candidates carrying the *same claim* into one entry
before ranking further. Step 6 actively manufactures these: a `wiki/`
page, the `raw/archive/` file it cites, and a connector-index page whose
`resource:` points back at that same wiki page are three hits for one
fact. Keep whichever sits closest to the primary material and record the
others as corroboration, not as independent evidence. Three views of one
claim are not three sources.

**Rerank.** Score each surviving candidate 0–10 on how well it answers
*the literal question asked*, not on how well it matches the query's
vocabulary, then keep the best handful and drop the rest. This is the same
agent making a deliberate second pass, not a separate model. The point is
that relevance judgment happens explicitly, over the shortlist, in one
place — rather than being folded silently into how the final answer gets
drafted.

### Step 5 — Expand local context and build an evidence packet

For every result that survived Step 4, 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
- which signals it was fused from, its rerank score, and anything it
  absorbed during dedupe — this is what Step 7 draws caveats from

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 6 — 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 with a `## Crux` covering the exact claim** — the Crux
  is verbatim source text, not synthesis, so it is already the evidence
  this step exists to fetch. Confirm the page's recorded fingerprint still
  matches the cited source (cheap: `sha256sum <source> | cut -c1-8` against
  the digest in the `## Sources` bullet). If it matches, quote the Crux and
  answer — one hash beats one full file read, and citing a quote is strictly
  stronger than citing a summary. If it **differs**, the source moved under
  the page: open the source, answer from it, and say the page's Crux is now
  stale — that's a real `ckb-lint` finding, not a formality. If the page has
  no fingerprint recorded at all, treat the Crux as unverified and fall
  through to the full read below.

  This shortcut is narrow on purpose. It applies only when the quote covers
  the specific claim being used — not when it is merely on-topic, and never
  as a reason to skip reading a source that would qualify or contradict it.
- **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 7 — 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.

State caveats in the answer itself, not only in the metadata you read to
build it. When a page grounding the answer is past its
`freshness_window_days`, carries a low `confidence` or `quality`, rests on
un-ingested `raw/inbox/` material, or was checked against a cached
connector index rather than a live re-fetch, say so in a short clause next
to the claim it qualifies. Surface a conflict between two live pages the
same way, even when neither is marked `superseded_by` yet. The metadata
already exists and Step 4 already put it in front of you; the failure mode
is answering confidently *from* a stale or contested page without passing
that on, which leaves the reader no way to weigh it.

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

- **Only one signal returned anything** — fusion is a no-op, so don't run
  the arithmetic for show. The rerank still applies (it's the check that
  the one list actually answers the question rather than merely matching
  its wording), and dedupe still applies as soon as Step 6 pulls in a
  page's own cited source.
- **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.
- **A page's `## Crux` quote is no longer found in the source it cites** —
  the fingerprint check will usually catch this first, but where it doesn't
  (no fingerprint recorded, or a source edited without the page being
  rebuilt), answer from the source and report the divergence. A quote that
  has drifted from its source is a stronger lint finding than a stale date,
  because it is a page asserting something the evidence no longer says.
- **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](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*