ckb/.agents/skills/ckb-retrieve/SKILL.md
Michał Kopeć 27d84fe008 Template 1.11.0: optional Python with degraded fallbacks; lint check 13 per-block Crux matching
- 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>
2026-10-01 21:26:43 +02:00

13 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

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:

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