`knowledge-layer/references/wiki-principles.md`

65 lines
# Wiki Principles — a layer you keep vs. one you abandon

A knowledge layer earns its keep only if it stays trustworthy as it grows. These
are the disciplines that separate a wiki agents rely on from one that rots into
noise and gets abandoned. Read this before a consolidation pass or when the
layer feels stale.

## The principles

1. **Provenance or it didn't happen.** Every claim links to a source. An
   unfalsifiable fact can't be checked, updated, or retired — it becomes a
   liability. `kl_status.py` flags entries with no `sources:`.

2. **Surface contradictions, never resolve them silently.** When sources
   disagree, keep both and log it. A layer that quietly picks a winner trains
   agents to speak with false certainty — the exact failure this pattern exists
   to prevent.

3. **Compile incrementally.** Recompile only what changed (`kl_scan.py` tells
   you what). Full recompiles are for schema migrations, not routine updates —
   they're expensive and they churn stable entries.

4. **One entity per entry; narrow beats broad.** A sharp, small entry is easy to
   keep correct. A sprawling page accumulates drift and duplication. Just as a
   narrow-scope *agent* outperforms a vague one, a narrow-scope *entry* stays
   truer than a catch-all.

5. **Structure is the index.** Typed folders + tags + `[[wikilinks]]` are the
   retrieval mechanism. No vectors, no RAG — the shape of the layer is what makes
   `kl_query.py` work. Invest in the schema; let it evolve only when a real new
   category appears.

6. **Summary-first.** Every entry opens with a one-line `**Summary:**`. Agents
   read summaries to orient and drill into detail only when needed — this keeps
   context loads small and cheap.

7. **Read-first, write-back.** Agents load the relevant entries BEFORE acting
   (so they wake up with full context) and write durable decisions BACK after
   (so the layer compounds). A layer that's only ever read goes stale; one that's
   only ever written becomes a junk drawer. Both directions, every task.

8. **Consolidate on a cadence.** Periodically: merge duplicate entities, prune
   dead cross-refs, re-summarize bloated entries, and clear resolved
   contradictions. Run `kl_status.py`; treat every flag as a to-do. Curation is
   the maintenance cost — pay it or the layer decays.

## Curation is a human job
The LLM compiles; a human decides *what is worth ingesting*. Garbage sources
produce a confident garbage wiki. Keep `sources/` curated — primary material
over second-hand summaries, signal over volume.

## When to do a consolidation pass
- `kl_status.py` shows orphan cross-refs, no-provenance entries, or a growing
  contradiction backlog.
- Entry count in one folder balloons (likely duplicates or too-broad entries).
- Before onboarding a new agent to the layer — a clean layer teaches clean habits.

## Why no RAG / vector DB
The Karpathy insight: for a curated, human-sized knowledge base, compiling
sources once into a structured wiki the LLM maintains beats re-retrieving raw
chunks on every query. You get summaries, cross-references, and contradiction
handling that a similarity search can't give you — and zero infrastructure. If a
layer genuinely outgrows this (hundreds of thousands of entries), that's the
signal to add retrieval tooling on top, not to abandon the structure.