ckb/.agents/skills/ckb-index-external/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

4.7 KiB

ckb-index-external — edge cases

Reference material for the ckb-index-external skill. Read when a run hits an unusual situation the main steps don't cover.

  • No connector-backed libs/<name>/ exists — report that and explain how to add one; don't touch anything.
  • source.local.yaml doesn't exist yet for a source — treat as read-only; this is the correct default, not a misconfiguration worth flagging loudly. Mention once, briefly, how to become the admin (access: write in that file) if the user seems to expect a rebuild.
  • Everyone is read-only and nothing has ever been published — report that clearly rather than silently doing nothing; this is the one case worth flagging as a real gap (nobody can currently index this source).
  • Connector not authorized this session — report which one and how to authorize it (claude.ai connector settings / claude mcp / /mcp), skip that source, keep going with the rest. Never ask the user for tokens or callback URLs.
  • Fetching a published index (Step 3) fails or the remote is unreachable — report it and fall back to whatever's already cached locally in libs/<name>/ from a previous fetch, rather than blocking the whole run; don't let a transient network issue block a read-only user from seeing the last-known index.
  • Re-running against an already-indexed source — refresh existing document and entity/process pages in place (update tldr/last_updated/confidence/source_fingerprint/source_checked, add newly-seen mentioned_in edges); never duplicate a document's or entity's page, and carry every ## Notes section across untouched.
  • A document's fingerprint is unchanged since the last run — don't re-summarize it. Advance source_checked to today, leave last_updated, tldr, and confidence exactly as they were, and spend the run's budget on the documents that did change. On a large source this is most of them, and it is the difference between a re-index that costs a full pass and one that costs a listing.
  • A document's fingerprint changed — re-fetch and re-summarize it, and say so in the report. A changed fingerprint on a document some wiki page cites is worth calling out by name: that wiki page was built from a version of this document that no longer exists.
  • A previously-indexed document is no longer found at the source — don't delete its page. Update its tldr with a note ("No longer found at source as of YYYY-MM-DD") and set retention: low, so the existing ckb-lint retention sweep archives it naturally on a later pass — no new archival mechanism needed. Leave any entity pages that cite it alone; the citation is still historically accurate even if the document itself is gone.
  • An extracted entity already has a full page in wiki/entities/ — keep this connector-side page thin (evidence/mentioned_in pointers only, resource: set to the wiki page) rather than re-deriving everything the wiki page already says; that duplication is exactly what the cascade design is meant to avoid.
  • A document is dense with names/topics and extracting every one would produce dozens of near-duplicate pages — extract what's clearly named and substantively discussed (not every passing mention), and prefer updating an existing entity page's "Mentioned in" list over creating a marginal new one. Don't force artificial granularity just to maximize page count.
  • A document yields no extractable entity beyond itself — that's fine; its Step 5 document page is the only page it produces. Not every document needs to feed Step 6.
  • A source is very large — cap what gets fully fetched/summarized in one run and explicitly report what was skipped (e.g. "42 of ~300 documents summarized this pass — re-run to continue"). Never silently truncate while implying full coverage.
  • Write access but publishing (Step 8) conflicts with a newer version someone else already pushed — this is why Step 3 (fetch) always runs first, even for write-access users: rebuild on top of the latest fetched state rather than blindly overwriting it. If a real conflict still shows up at publish time, report it rather than force-pushing over it.
  • libs/<name>/ has both real content files and a source.yaml — ambiguous and out of scope for this skill to resolve; report it and stop for that folder (this is the same case ckb-lint's external-source config check flags).
  • source.yaml is missing connector or location — report it as malformed and skip that source; don't guess at intent.

Licensed under the Apache License, Version 2.0 — see LICENSE at the repository root, or http://www.apache.org/licenses/LICENSE-2.0.