- 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>
79 lines
4.7 KiB
Markdown
79 lines
4.7 KiB
Markdown
# 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](../../../LICENSE)
|
|
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|