- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
53 lines
3.1 KiB
Markdown
53 lines
3.1 KiB
Markdown
# ckb-retrieve — edge cases
|
|
|
|
Reference material for the `ckb-retrieve` skill. Read when a
|
|
run hits an unusual situation the main steps don't cover.
|
|
|
|
- **Only one signal returned anything** — fusion is a no-op, so don't run
|
|
the arithmetic for show. The rerank still applies (it's the check that
|
|
the one list actually answers the question rather than merely matching
|
|
its wording), and dedupe still applies as soon as Step 6 pulls in a
|
|
page's own cited source.
|
|
- **A cited source file no longer exists** (moved, renamed, or cleaned
|
|
up) — say so plainly rather than silently falling back to the `tldr` as
|
|
if it had been verified. Flag it as a likely `ckb-lint` finding (a
|
|
broken `Sources` reference) rather than treating it as a dead end.
|
|
- **A page's `## Crux` quote is no longer found in the source it cites** —
|
|
the fingerprint check will usually catch this first, but where it doesn't
|
|
(no fingerprint recorded, or a source edited without the page being
|
|
rebuilt), answer from the source and report the divergence. A quote that
|
|
has drifted from its source is a stronger lint finding than a stale date,
|
|
because it is a page asserting something the evidence no longer says.
|
|
- **Connector item unreachable or connector not authorized this
|
|
session** — state clearly that the answer is based on the cached
|
|
connector index, not a live re-check, and name which connector would
|
|
need authorizing to go further.
|
|
- **Question is low-stakes and the matched page is high-confidence,
|
|
recently updated, and well within its `freshness_window_days`** — still
|
|
open the source at least once to ground the answer; skip only a *second*
|
|
redundant read if the same source has already been opened earlier in
|
|
the same retrieval pass for another part of the same question.
|
|
- **Many pages are relevant and reading every cited source in full would
|
|
be excessive** — prioritize the sources that actually carry the
|
|
specific fact the question needs, not every source any shortlisted page
|
|
has ever cited. Say what was skipped rather than silently narrowing
|
|
without a note.
|
|
- **The "source" is itself a generated artifact** (e.g. an
|
|
`outputs/emails/*.md` draft cited as a wiki page's Source) rather than
|
|
raw external material — that's still the source relative to the wiki
|
|
page; no further hop beyond it is required.
|
|
- **A connector-index entity/process page's `resource:` points at a full
|
|
`wiki/entities/` page** (per `ckb-index-external`'s thin-page
|
|
convention) — treat the wiki page as the real source to verify against;
|
|
the connector page is just the pointer that got you there.
|
|
- **Nothing in the index is even plausibly relevant** — say the knowledge
|
|
base has nothing on this yet, and suggest `ckb-ingest` (for new raw
|
|
material) or `ckb-index-external` (for a connector-backed source) if
|
|
that seems like the actual gap. For durable gaps, record or propose a
|
|
`wiki/query-gaps.md` entry. Don't stretch a weak match into an answer
|
|
just to have one.
|
|
|
|
---
|
|
|
|
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
|
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|