ckb/.agents/skills/ckb-retrieve/SKILL.md
Michał Kopeć 221a6a29b1 Template 1.25.0: release 3 batch 2, consolidation and topics, schema 1.7
- 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>
2026-11-02 20:30:26 +01:00

17 KiB
Raw Blame History

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:

  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/<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 — 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 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 "<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 ## 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.

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.