- F13 new skill ckb-consolidate with consolidate.py: a proposals-only report in outputs/reports/ (topic clusters and their state, merge candidates, missing links, stale pages, old log entries by month); never edits a page, never rewrites the log - F15 topic pages (type: topic) in the new wiki/topics/, built only on approval, with member-page digests as ## Sources so lint flags drift; ckb-retrieve routes "overall" questions to wiki/topics/index.md first - Schema 1.7 (D-0016): ckb-upgrade b4, ckb-init and ckb-reset know wiki/topics/; ckb-routine suggests a fortnightly Consolidate --confirm Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
17 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
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:
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, and follow its## Rulesin how you answer. A project scope narrows the first pass only; it never hides the rest of the cascade.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## Sourcesare member pages, and Step 6 follows them like any other source.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;
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 <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 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.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## 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.
Text between <private> and </private> 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):
<python> .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_<question-slug>.md:
---
type: answer
question: How many times does Atlas retry a failed batch?
date: YYYY-MM-DD
author: Name <email>
---
# How many times does Atlas retry a failed batch?
<the answer as given, caveats included>
## 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 <file> | 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. Read that file when a
run hits something the steps above don't cover; don't load it otherwise.