ckb/wiki/graph/index.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

2.6 KiB

Graph

Edge list and relationship data for the knowledge graph, keyed by entity page.

edges.json holds typed relationships between pages. Created on the first ingest that extracts entities.

Edge vocabulary

Each verb exists because it answers a question retrieval actually gets asked. If a proposed edge doesn't answer one of these, it doesn't belong in the graph — put it in prose on the page instead.

Verb Question it answers Written by
part_of Where does this live? What is it a piece of? ckb-ingest
uses What does this reach for at runtime? ckb-ingest, ckb-index-external
depends_on What breaks if I change this? ckb-ingest
produces Where does this output come from? ckb-ingest
configures What changes this thing's behaviour? ckb-ingest
validates What checks, tests, or judges this? ckb-ingest
implements What contract must this honour? ckb-ingest
caused Why did this happen? ckb-ingest
contradicts What disagrees with this, unresolved? ckb-ingest, ckb-lint
supersedes What replaced this, and what did it replace? ckb-ingest, ckb-decide, ckb-lint
decided_by Who made this call? ckb-decide
affects What does this decision constrain? ckb-decide
has_expertise_in Who can answer questions on this? ckb-ingest
owns Who is responsible for this? ckb-ingest
mentioned_in Which source document discusses this? ckb-index-external (lib indexes only)

An installed module may write these same verbs from its own skills; its README says which. The vocabulary itself does not change on install.

Conventions:

  • One direction per relationship. part_of, supersedes, depends_on, and uses are canonical; don't also record the inverse (contains, superseded_by, …) as a second edge. Frontmatter carries the inverse where a page needs to state it (superseded_by:), and traversal reads edges both ways regardless.
  • Evidence, not inference. has_expertise_in and owns are recorded only from demonstrated evidence — someone attending a meeting is not expertise, and a job title is not ownership. The same applies to every other verb: an absent edge beats a fabricated one.
  • In-degree is a retrieval signal. How many edges point at a page is a rough measure of how central it is, and ckb-retrieve fuses it as one ranked list among several. That only works if edges are recorded honestly; padding the graph degrades search rather than improving it.

(No edges recorded yet — populated on the next ingest.)