- 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>
322 lines
17 KiB
Markdown
322 lines
17 KiB
Markdown
---
|
||
name: ckb-retrieve
|
||
description: 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
|
||
|
||
```bash
|
||
<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):
|
||
|
||
```bash
|
||
<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`:
|
||
|
||
```markdown
|
||
---
|
||
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`](references/edge-cases.md). Read that file when a
|
||
run hits something the steps above don't cover; don't load it otherwise.
|