hierarchical-rag

---

name: hierarchical-rag description: Expert guide for building, maintaining, and querying a Hierarchical RAG (DIGEST/RAW) knowledge structure for LLM context management. Use this skill when a user wants to: (1) create a new DIGEST/RAW folder structure for a project, (2) add new documents to an existing RAW layer and generate/update the corresponding digests, (3) query a project's knowledge base using the two-tier lookup strategy, (4) optimize token usage by routing queries through the right layer, (5) restructure existing documentation into a hierarchical context system. Triggers on: hierarchical RAG, DIGEST/RAW, context compression, knowledge distillation, digest erstellen, RAW aktualisieren, Kontext optimieren, token sparen, Wissensstruktur, context engineering, summary index, two-tier context.

Hierarchical RAG

Strukturiere Projektwissen in zwei Schichten, damit das LLM immer im richtigen Layer arbeitet und unnötige Token-Verbrennung vermieden wird.

Kernkonzept

DIGEST/   ← Komprimiertes Wissen (Standard-Arbeitslayer)
  00_catalog.md       → Einstiegspunkt / Navigations-Index
  glossary.md         → Begriffe & Abkürzungen
  decisions.md        → Dokumentierte Einschränkungen & Entscheide
  10_topics/          → Themenübergreifende Zusammenfassungen
  20_folders/         → Folder-level Digests (ein File pro RAW-Ordner)

RAW/      ← Originaldokumente (nur bei Bedarf)
  01_Ordner/
  02_Ordner/
  ...

Faustregeln:

• DIGEST zuerst — 80-90% aller Anfragen können allein mit dem Digest beantwortet werden
• RAW nur auf Demand — Wenn eine präzise Passage, ein exaktes Datum oder ein vollständiges Dokument benötigt wird
• Niemals RAW indizieren ohne Digest-Update — Neues Dokument = neuer/aktualisierter Digest-Eintrag

---

Query-Routing: Welchen Layer verwenden?

Signal in der Anfrage	Layer
"Was ist X?" / Begriffserklärung	glossary.md
"Welche Themen gibt es zu...?"	10_topics/
"Was ist in Ordner X drin?"	20_folders/
"Welche Einschränkungen/Entscheide?"	decisions.md
"Zeige mir das genaue Dokument..."	RAW/
"Exaktes Zitat aus Kapitel X"	RAW/
"Alle Details zu Prozess Y"	RAW/ nur wenn Topic-Summary nicht reicht

---

Workflows

Neues Dokument in RAW hinzufügen → Digest aktualisieren

1. Dokument in den passenden RAW/Ordner-Pfad ablegen
2. 20_folders/<ordner>.digest.md aktualisieren:
   - Dateiname + kurze Beschreibung hinzufügen
3. Prüfen ob 10_topics/<topic>.md berührt wird → dort ergänzen
4. Neue Begriffe in glossary.md eintragen
5. 00_catalog.md Statistiken bei Bedarf anpassen

Neuen RAW-Ordner anlegen → Vollständiger Digest aufbauen

Siehe references/setup-workflow.md für den vollständigen Schritt-für-Schritt-Prozess.

Bestehende Struktur analysieren

1. 00_catalog.md lesen → Überblick & Statistiken
2. 20_folders/ scannen → Was ist wo?
3. 10_topics/ lesen → fachliche Gruppierung
4. Bei Bedarf: RAW für Detailanalyse öffnen

---

Digest-Qualitätsstandards

20_folders/<ordner>.digest.md

# <Ordner-Name> Digest

| Datei | Beschreibung | Schlüsselinfo |
|-------|-------------|---------------|
| datei.pdf | Kurzbeschreibung | Version, Datum, Scope |

10_topics/<topic>.md

# <Topic>

## Übersicht
[2-3 Sätze: Was ist das Thema, warum ist es relevant]

## Schlüsseldokumente
- `RAW/<pfad>` — Kurzbeschreibung

00_catalog.md

# Context Catalog

| Metrik | Wert |
|--------|------|
| Markdown files | X |
| Reduktion | X% |

## Quick Navigation
...Folder-Tabelle + Topic-Links...

---

Token-Effizienz messen

Ziel: ≥ 60% Reduktion gegenüber direkter RAW-Indizierung.

Schicht	Typische Grösse
00_catalog.md	~1-2 KB
Ein Topic-File	~5-15 KB
Ein Folder-Digest	~10-30 KB
Ein RAW-Dokument	50-500+ KB

Wenn der Digest eines Topics grösser als das grösste RAW-Dokument ist → Digest ist zu detailliert, kürzen.

---

Freshness Gate — RAG aktuell halten

Bei jedem Digest-Zugriff: Prüfe _sources.md ob die Quellen noch innerhalb ihres TTL liegen.

🔒 Sicherheit: _sources.md enthält interne URLs und ist via **/_sources.md in .gitignore ausgeschlossen. Niemals committen!

_sources.md prüfen → TTL OK? → Ja → Digest direkt verwenden
                              → Nein → Quelle prüfen → Geändert? → RAW + Digest updaten

Kernregeln:

• Max 3 Freshness-Checks pro Anfrage
• Stale Digest > kein Digest
• Manuell-Quellen: User fragen statt automatisch prüfen

Vollständiges Konzept: references/freshness-gate.md

---

Best Practices & externe Ressourcen

Für vertiefte Theorie und aktuelle Entwicklungen: references/best-practices.md