ckb/.agents/skills/ckb-retrieve/references/edge-cases.md
Michał Kopeć 7863115b74 Template 1.10.0: slim skills, review fixes, docs/, tests, retrieval script
- 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>
2026-09-24 20:45:09 +02:00

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>.*