- 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>
4.7 KiB
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.yamldoesn'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: writein 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-seenmentioned_inedges); never duplicate a document's or entity's page, and carry every## Notessection across untouched. - A document's fingerprint is unchanged since the last run — don't
re-summarize it. Advance
source_checkedto today, leavelast_updated,tldr, andconfidenceexactly 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
tldrwith a note ("No longer found at source as of YYYY-MM-DD") and setretention: low, so the existingckb-lintretention 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_inpointers 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 asource.yaml— ambiguous and out of scope for this skill to resolve; report it and stop for that folder (this is the same caseckb-lint's external-source config check flags).source.yamlis missingconnectororlocation— 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.