ki-praxis/docs/kb/PROTOCOL.md

Knowledgebase — Progressive Disclosure Protocol

Flughöhe: L0 · Stand: 2026-08-23
Gilt für Autoren-Agents am Buch-Repo. Nicht Teil des PDF-Manuskripts.

Zweck

docs/kb ist der Semantic-Maps-Layer: Fakten, Landkarten, Kapitel-Distillate und Verweise — nicht Rules, nicht Episodic, nicht Prozeduren.

KB zuerst: Nach always-on Rules ist INDEX.md die erste Informationsquelle für Fakten, Routing und „wo steht das?“. Kapitel, Skills und Pipeline nur nach Link (L3).

Was	Wo	Beispiel
Rules (immer/verboten/Default)	Root-AGENTS.md + .grok/rules/*.md	Karpathy-Skills, kladde.md, Vendor-Agnostik, Ton
Semantic Maps	docs/kb (diese Datei + INDEX)	Kapitelliste, Distillate, SoT-Tabelle
Episodic (Task-Stand)	HANDOFF-buch.md	aktueller Slice, Dirty-Queue
Episodic-Archiv	HANDOFF-archiv.md	SHA-Index (kein Default-Load; keine Wellen-Essays)
Procedural	.grok/skills/, .grok/commands/, just …	Lektorat-Loop, PDF-Bau
Detail / SoT	Kapitel, rules, skills-Body, abbildungen.md …	Full-Read nur bei Need

Select-Protokoll (verbindlich)

1. Task lesen → Scope wählen (eine Domain)
2. AGENTS.md + .grok/rules/*.md   — Rules (immer; Grok lädt sie)
3. docs/kb/INDEX.md               — erste Informationsquelle: Task-Router oder 1 Domain
4. HANDOFF-buch.md                — nur wenn Session fortsetzen / unfertig (nicht das Archiv)
5. docs/kb/<domain>/INDEX.md      — Topic wählen
6. L2-Card                        — nur wenn Decision/Edit das braucht
7. L3-SoT full-read               — nur die betroffenen Datei(en)
8. Stop. Nie den ganzen docs/kb-Tree oder 01–24 „zur Sicherheit“ laden

Tool-Results: Select am Call, Isolate über Explore-Subs, nur Hand-back in den Parent (AGENTS.md Parent-Context; Skill parent-context). Rohdumps nicht ins Haupt-Window.

Flughöhen

Level	Artefakt	Token-Haltung
L0	AGENTS.md, .grok/rules/*.md (Grok lädt beides immer), docs/kb/INDEX.md	schlank, session-start
L1	docs/kb/<domain>/INDEX.md	eine Domain
L2	Topic-Cards in der Domain	1–3 Karten, nicht alle
L3	SoT (Kapitel, Skill-Body, Pipeline-Reference, …)	gezielt, nach Link aus L2

Handoff ist nicht L0-Pflicht. Nur laden, wenn die Session fortgesetzt wird oder der Slice unfertig ist.

Grok-Load (nicht verhandelbar):

• Immer: Root-AGENTS.md + jede Datei in .grok/rules/*.md + globale Home-Rules
• On demand: Skills (nur description bis Activation), docs/kb L1–L3, Kapitel
• Darum: alles Schwere, das nicht jede Session braucht, gehört in Skills/references oder docs/kb — niemals nach .grok/rules/.

Eine Ebene Verweise: L2 → L3-Pfad. Keine Ketten A→B→C→D.

Write-Back

Rolle	Darf	Review
Agent	L2-Karten vorschlagen/aktualisieren (Fakten-Drift); Domain-INDEX-Zeile	Mensch skimmed bei Richtlinien
Agent	Handoff/Progress flüssig	ja — Owner
Agent	nicht ungeprüft Root-AGENTS.md-Rules umschreiben	immer Mensch bei Rules
Mensch	Merge Semantic/Procedural; Archive	Peer bei großen Richtlinien

Regel: Bei Konflikt gewinnt die L3-Source of Truth, nicht die Kurzfassung in L2. L2 anpassen oder als verdächtig markieren.

Freshness

• Veraltetes Autoritäres ist schlimmer als fehlendes — L2-Karten mit Stand: und kurzem Freshness-Hinweis.
• Nach Migration (Kapitel-Rename, just-Target, Skill-Rename): dieselbe Session L1/L2 und ggf. AGENTS.md mitziehen.
• Erledigte episodische Fakten → HANDOFF-archiv.md (eine SHA-Index-Zeile + Tip), nicht in L2 und nicht im Live-Handoff lassen.
• Stabile Ja/Nein → docs/kb/00-projekt/entscheidungslog.md. Content-Lücken → residual-map.md.
• Tote Karten → docs/kb/archive/ + aus Domain-INDEX entfernen (nicht im Default-Select).

Anti-Patterns

Vermeiden	Stattdessen
Permanent Load der ganzen KB	nur INDEX → 1 Domain
Tool-Rohdumps im Parent	grep/read mit Cap; Zone B → Explore + Hand-back
Kapitel-Text nach docs/kb kopieren	Kurzfassung + L3-Link
Task-Stand in L2	HANDOFF-buch.md (schlank)
Handoff-Chronik im Live-Handoff	HANDOFF-archiv.md
Runbook als L2-Essay	Skill / just / Command
Blind-RAG übers Repo	Agentic Search am HEAD + diese Maps
Verweisketten	L2 → eine SoT-Datei
Zweiten Tree unter knowledge/ pflegen	knowledge/INDEX.md ist Redirect

Card-Skelett (L2)

# <Thema>

> Flughöhe: L2 · Domain: <…> · Stand: YYYY-MM-DD

## In 3 Sätzen
…

## Wann laden
- …

## Fakten / Regeln (kurz)
- …

## Source of Truth (L3)
| Thema | Pfad |
|-------|------|
| … | `…` |

## Nicht hier
- …

## Freshness
- …