- D-0003: <python> interpreter resolution, per-OS install guide, lint_quick.sh/.ps1 session-start fallback, manual lint checklist, no-script retrieval path, exporters declare Python a hard requirement - Lint check 13 pairs each Crux quote block with the attribution under it, so a multi-source Crux no longer cross-fails; fixture KB gains a second source - Session summaries for 2026-09-29 and 2026-10-01 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
13 KiB
| name | description |
|---|---|
| ckb-retrieve | Answer a question or research a topic from wiki/, linked/<name>/, or a connector-backed libs/<name>/. 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
Index-first navigation means most of the wiki never enters context: a one-sentence
tldr decides whether a page is worth opening. That's the right trade for deciding
relevance and the wrong one for grounding an answer — a tldr compresses whatever
the author judged important at write time, a connector-index entity page is
deliberately a thin pointer, and either can have drifted from the primary material
since.
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 it was built from and answer from there. It is the difference between
citing what the index says about the evidence and citing the evidence.
Read-only, with one exception. It reads the index and the sources behind it and
never edits a page mid-answer — a gap or contradiction it surfaces is reported and
handed to ckb-lint/ckb-ingest. The one write it owns is wiki/query-gaps.md: a
question the cascade could not answer is recorded there (Step 7), logged in
wiki/log.md like any other wiki change.
The mechanical half — gathering ranked lists from each signal and fusing them — runs
as scripts/retrieve_candidates.py, for the same reason lint's detection runs as a
script: a fixed procedure over a growing tree belongs in code, not in per-question
model arithmetic. Judgment stays here: what the question actually asks, which
candidates carry the same claim, and whether the source still says what the page
says.
How to run this skill
Step 1 — Read the index
Same cascade order as CLAUDE.md/AGENTS.md, 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.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 tockb-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.- If nothing local matches: each
linked/<name>/index (alphabetical), then each connector-backedlibs/<name>/entities/index.md— for a connector-backed lib this means its generated index (both the Documents and the Entities & Processes sectionsckb-index-externalproduces), 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
<python> .agents/skills/ckb-retrieve/scripts/retrieve_candidates.py "<the question>" [--scope <project-slug>]
Resolve <python> 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; and
a confidence×quality×freshness "trust" list — 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.
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 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 anckb-ingestrun 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 "<literal tokens>" 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/<slug>.md page list; (d) one-hop
neighbours of the shortlist in wiki/graph/edges.json via
rg '"<page>"' 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.4). 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## Cruxcovering 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-8against the digest in the## Sourcesbullet). 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 realckb-lintfinding, 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 viackb-ingestcarries a## Sourcessection citing the exactraw/archive/<date>/...oroutputs/...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 theckb-index-externalextraction) — read itsresource:field. If the connector is authorized this session (perToolSearch/MCP auth state), re-fetch the live item for current, complete content rather than trusting the cachedtldr— connector pages use a deliberately shortfreshness_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 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).
Edge cases
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
references/edge-cases.md. Read that file when a
run hits something the steps above don't cover; don't load it otherwise.