--- name: ckb-retrieve description: Answer a question or research a topic from wiki/, linked//, or a connector-backed libs//. Index entries (a page's tldr, a connector-index entry) are compressed and can be stale, so this skill makes verifying a surfaced page against its underlying source a standing step before grounding an answer on it. Always in play for KB questions; the user need not name it. --- # Retrieve (source-verified query) skill ## Purpose `raw/saved-conversations/` is never a retrieval source; a question about a past chat itself belongs to `ckb-add-conversation`. A `tldr` decides relevance but cannot ground an answer: it compresses what the author judged important, a connector-index page is deliberately thin, and either may have drifted from the primary material. Once a page is worth using, follow it to the sources it was built from and answer from there. Read-only, with two exceptions: `wiki/query-gaps.md` records a question the cascade could not answer (Step 7, logged in `wiki/log.md`), and an answer the user asks to keep goes to `outputs/answers/` (Step 8). A gap or contradiction found mid-answer is reported and handed to `ckb-lint`/`ckb-ingest`, never fixed here. Ranking and fusion run in `scripts/retrieve_candidates.py`; judgment stays here: what the question asks, which candidates carry the same claim, whether the source still agrees. ## 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, and follow its `## Rules` in how you answer. A project scope narrows the first pass only; it never hides the rest of the cascade. 3. `wiki/topics/index.md` — for a question about what the KB holds *overall* on a subject ("what do we know about X", "summarise X"). A topic page is the fastest map, but it is synthesis: its `## Sources` are member pages, and Step 6 follows them like any other source. 4. `wiki/entities/index.md` — match against entity titles/`tldr`. 5. `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. 6. If nothing local matches: each `linked//` index (alphabetical), then each connector-backed `libs//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 — Run the candidate script ```bash .agents/skills/ckb-retrieve/scripts/retrieve_candidates.py "" [--scope ] ``` Resolve `` per "Scripts and the Python Runtime" in `AGENTS.md`. It builds one ranked list per signal — exact `rg` hits across `wiki/`, `raw/archive/`, `raw/inbox/`, `outputs/`, `linked/*/` and connector-backed `libs/*/`; title/`tldr` token overlap; pages a matching `wiki/projects/` scope lists; one-hop graph neighbours of the text-matched shortlist; in-degree; a confidence×quality×freshness "trust" list; and a `bm25` list from a SQLite FTS5 index of page *sections*, each chunk carrying its page title, heading path and `tldr` as context — then fuses them with reciprocal rank fusion (`weight / (k + rank)`, `k = 10`, exact-match weighted 2.0 when the question carries literal tokens, in-degree 0.5, trust 0.3). A page ranked third by three signals beats one ranked first by a single signal; consensus is the point. `--json` gives the same result as data. `--tag ` (repeatable) keeps only pages carrying those tags, for a question that names a tagged area. Each candidate also shows `~N tok`, the estimated cost of reading the whole file, and, when the section index matched, `sections:` with up to three `#anchor (Heading)` hits. Read in layers: the `tldr` decides relevance, a named section answers most questions, and the full page is for when the section's neighbours change its meaning (Step 5). The Step 6 source check still applies to whatever grounds the answer. A `bm25: unavailable` header line means this Python's `sqlite3` lacks FTS5; the other lists still run. The index is a cache in `tmp/ckb-fts.sqlite` and refreshes itself. A candidate under `outputs/answers/` is an answer kept earlier, not a source: use it to find pages fast, then follow its `## Sources` like any other lead. Never ground an answer on a kept answer alone. Read the whole output, not the first line. Each candidate shows which lists it came from and at what rank, its `tldr`, `STALE`/`INBOX`/`SUPERSEDED`/`DRAFT`/ `NEEDS_UPDATE` flags, and any `raw/archive/` or `outputs/` file it cites that the script folded in as corroboration rather than counting as a second source. Two lines of the header matter on their own: - **`raw/inbox/ hits`** — un-ingested material already holds something relevant. It can answer the question, and it is the clearest signal an `ckb-ingest` run is overdue; say both. - **`graph: empty`** — the graph and in-degree lists were skipped, so the fusion rests on text signals alone. Say so if it affects confidence. **Without Python (degraded path).** Say so once, then reproduce the signals by hand, cheapest first: (a) `rg -il ""` across `wiki/`, `raw/inbox/`, `raw/archive/`, `linked/*/` and connector-backed `libs/*/` — an `raw/inbox/` hit still means "ingest is overdue"; (b) scan `wiki/index.md` and the subdirectory indexes for `tldr` overlap; (c) if `--scope` applies, the `wiki/projects/.md` page list; (d) one-hop neighbours of the shortlist in `wiki/graph/edges.json` via `rg '""' wiki/graph/edges.json`. Prefer pages that appear in more than one of these, which is what the fusion does. State that in-degree and the trust list were skipped and continue to Step 3. ### Step 3 — Shortlist, and walk the graph for what the text missed Keep every candidate that is plausibly relevant — not just the top one. A question is often best answered by triangulating two or three pages (a concept page plus the person or decision page that qualifies it), and a page whose `tldr` looks tangential can hide the exact fact in its body or `## Sources`. This isn't "open everything"; it's "don't stop at one." For "who knows about X" / "who owns X", the graph is the primary lookup, not a fallback: read the `has_expertise_in` and `owns` edges pointing at the topic entity and answer from the people on the other end, ordered by how many distinct sources evidence each edge. Where no such edge exists, fall back to authorship evidence — who the `## Sources` material actually shows answering on that topic — and say which of the two grounded the answer; an inferred expert is a weaker claim than a recorded one. If decisions *are* the subject, hand off to `ckb-decide` (Step 1.5). A superseded decision that surfaces here is history, not noise — say so rather than silently answering from the current one. ### Step 4 — Dedupe by claim, then rerank against the literal question The script folds a cited archive file into the page that cites it; the rest of dedupe is judgment. Collapse candidates carrying the *same claim* into one entry: a `wiki/` page, a connector-index page whose `resource:` points back at it, and a `linked/` mirror of the same fact are three hits for one claim. Keep whichever sits closest to the primary material and record the others as corroboration. Three views of one claim are not three sources. Then score each survivor 0–10 on how well it answers *the question as asked*, not how well it matches the question's vocabulary — the fusion measured the latter. Keep the best handful, drop the rest. This is the same agent making a deliberate second pass, in one place, rather than folding relevance judgment silently into how the 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 (the script's `ranks`), 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 | 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//...` 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//`** (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//` 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. Text between `` and `` in a source is never quoted or paraphrased in an answer, even when it holds the exact fact; say that a private passage exists and who to ask instead. After reading, log the wiki pages you actually opened (not every candidate): ```bash .agents/skills/ckb-retrieve/scripts/retrieve_candidates.py --opened wiki/entities/foo.md wiki/entities/bar.md ``` It appends to `tmp/access.log`, which is per machine and never committed; `ckb-lint --cold` turns it into demotion proposals. Skip it without Python. 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, was checked against a cached connector index rather than a live re-fetch, is `review: draft` (no person has checked it) or `needs_update`, or carries an open `> CONTRADICTION:` marker on the claim, 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 the script's flags 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 a short `wiki/query-gaps.md` entry under `## Open` with the question, date, search areas tried, and the smallest missing source/page that would close the gap — this is the one write this skill owns. Log it in `wiki/log.md` immediately (Rule B). When the answer has a shape Markdown shows badly — a comparison across several items (a table), numbers over time or a distribution (a chart), a walkthrough someone will present (slides), or something a reader will click through (an HTML page) — offer that format in one line after the answer, once. Produce it only on a yes. Markdown stays the record: a kept answer (Step 8) is always Markdown, with any other format as an extra file next to it. ### Step 8 — Offer to keep the answer When the answer took real work — several pages triangulated, a source re-read, or synthesis no single page holds — end with one line offering to keep it: "Want me to keep this answer?" Ask nothing for a one-page lookup, and never save without a yes. On a yes, look in `outputs/answers/` first. If a kept answer already covers the same question (same slug, or a title that asks the same thing), offer to update it instead of writing a second one. Otherwise write `outputs/answers/YYYY-MM-DD_.md`: ```markdown --- type: answer question: How many times does Atlas retry a failed batch? date: YYYY-MM-DD author: Name --- # How many times does Atlas retry a failed batch? ## Sources - `wiki/entities/atlas-retry-policy.md` — sha256:1a2b3c4d (checked YYYY-MM-DD) - `raw/archive/2026-09-02/dlq-review.md` — sha256:5e6f7a8b (checked YYYY-MM-DD) ## Gaps - What the KB could not answer, one line each — or `- none` ``` Fingerprint every page and source the answer rests on, with the same `sha256sum | cut -c1-8` as ingest: `ckb-lint` then reports a kept answer whose ground moved (check 16). Each `## Gaps` line that is durable also goes into `wiki/query-gaps.md` (Step 7). A kept answer is an output, not a wiki page: no `wiki/log.md` entry; name its path in the Rule D note. When the answer holds synthesis worth having in the wiki itself, offer once to file it back: copy the kept answer into `raw/inbox/` and say "Ingest". It then goes through the same check-in, blast radius and fingerprints as any other source — never write it into `wiki/` from here. ## 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.