adamjali/erklären

<essential_principles>

Wie dieser Skill funktioniert

Zwei Modi, automatisch nach Betreff geroutet (siehe Routing-Tabelle):

• Modus A – Repo / Konzept / Doku (der günstige Pfad): Recherche → Klonen (falls Repo) → Erkunden → Synthese → Ausgabe. Lockere parallele Agenten sind in Ordnung.
• Modus B – Live-Webprodukt / Wettbewerber / Datenprodukt / Algorithmus / Landschaft (der volle Umfang): Scout → Bestätigung → Workflow-gesteuerte Tiefenrecherche → Browser-Erfassung → Reverse-Engineering zu validiertem Code → Synthese. Lese @references/competitor-teardown.md und folge ihr.

Routing nach Betreff-Typ

Betreff	Signal	Modus	Ablauf
GitHub-Repo	github.com	A	Klonen + Explore-Agenten
Konzept / Technik	keine URL	A	Researcher-Agenten
Doku / statische Seite	URL, informativ	A	Researcher + WebFetch
Live-Produkt / App / SaaS / Wettbewerber	URL ist ein Produkt; "Wettbewerber/Teardown/vs uns/wie machen sie"	B	Browser + Workflow + Schema pro Betreff
Rechner / Schätzer / Prognose / Preisrechner / Ranking	eine Formel/ein Algorithmus zum Knacken	B	Live-Probe-Raster → ausführbare Referenzimplementierung → validieren
Gesamte Landschaft	"Finde alle anderen / jeden in diesem Bereich"	B	Namensraum-Entdeckung → Teardown der YES-Menge

Entscheidungsregel: Wenn eine URL SOWOHL ein Produkt ALS AUCH eine Dokumentation hat, standardmäßig B – der Scout-Durchlauf ist günstig und stuft auf A herab, wenn es nichts zu zerlegen gibt.

Ausführungsregeln

1. Das richtige Werkzeug für die Größe: Modus A = parallele Task/Agent-Aufrufe. Modus B = das Workflow-Tool (Pipelines, strukturierte Ausgabeschemata, Fortsetzung) bei 3+ Themen oder mehrphasiger Arbeit.
2. Erst fundieren, dann bestätigen: Modus B führt einen günstigen Scout-Durchlauf + ein Bestätigungsgate (Umfang + Erkundungsgrenze + Browser) durch, bevor der teure Tauchgang startet – es sei denn, der Benutzer hat bereits "voller Umfang / tief gehen / alles" gesagt.
3. Reverse Engineering zu ausführbarem, validiertem Code für jeden Rechner/jeden Algorithmus; Benchmark gegen die autoritative Grundwahrheit, nicht gegen die Behauptung des Wettbewerbers.
4. Visuell stark: Jedes wichtige Konzept erhält ein Diagramm oder eine Tabelle.
5. Zweifache Ausgabe: Executive Summary + Dateiindex in der Konversation anzeigen; das vollständige Dokumentationsset in ~/.claude/explanations/<Datum>_<Slug>/ speichern.
6. Widerstandsfähig: Umfangreiche Modus-B-Recherche läuft als Hintergrund-Workflow; Artefakte inkrementell persistieren; bei Abbruch fortsetzen (resumeFromRunId).
7. Aufräumen: Angebot, geklonte Repos / gespeicherte Dateien nach Abschluss zu löschen. </essential_principles>

<scope_boundary>

Erkundungsgrenze Modus B (tragend – vor jeder Live-Erkundung lesen)

Wettbewerbsanalyse ist legal und auf ÖFFENTLICHEN Oberflächen normal. Vollständige Regeln in @references/competitor-teardown.md. Die Invarianten:

• ERLAUBT: öffentliche Seiten/Assets, öffentliche OpenAPI//docs, öffentliche JS-Bundles, ein moderates, höfliches Raster (~15–40, niedrige Rate) normaler Benutzeranfragen an öffentliche Endpunkte zur Ableitung einer Formel, Header-Fingerprinting, WHOIS/DNS.
• NIEMALS: CAPTCHA/Bot-Herausforderungen umgehen, Authentifizierung umgehen, ganze Datensätze massenhaft erfassen (nur Stichproben), Stresstests durchführen oder admin/mutierende/zerstörende Endpunkte aufrufen (DOKUMENTIEREN, nicht aufrufen). Expositionen beobachten; niemals ausnutzen. Niemals echte Benutzerdaten in ein Wettbewerberformular eingeben. Im Zweifel nicht – und sagen, warum. </scope_boundary>

<intake_gate>

<no_context_handler> WENN $ARGUMENTS leer ist: → Verwende AskUserQuestion:

• header: "Erklären"
• question: "Was soll ich erklären?"
• options:
  • "GitHub-Repository" – Eine Codebasis von GitHub analysieren
  • "Website oder Dokumentation" – Eine Website, Doku oder API verstehen
  • "Wettbewerber / Live-Produkt / Landschaft" – Ein Live-Produkt zerlegen, einen Rechner reverse-engineeren oder einen gesamten Wettbewerbsraum kartieren (Modus B)
  • "Konzept oder Technologie" – Ein Konzept, Framework oder Werkzeug erklären

Danach springe zu context_analysis. </no_context_handler>

<context_analysis> Analysiere $ARGUMENTS, um zu extrahieren:

• Typ: GitHub-Repo, Website, Konzept oder anderes
• URL/Thema: Die spezifische Sache, die erklärt werden soll
• Implizites Ziel: Lernen zu nutzen? Bewerten? Architektur verstehen? Beitragen?

Typ automatisch erkennen:

• Enthält github.com → GitHub-Repo (Modus A)
• Modus-B-Signale → "Wettbewerber", "Teardown", "reverse-engineeren", "vs uns", "wie machen sie", "finde alle anderen" oder eine URL, die ein Produkt/App/Rechner ist → Modus B
• Enthält http (informativ/Doku) → Website (Modus A)
• Andernfalls → Konzept (Modus A) </context_analysis>

<initial_questions> Verwende AskUserQuestion nur für echte Lücken (max. 2–3 Fragen):

Ziel (falls unklar):

• "Was ist Ihr Ziel?" mit Optionen:
  • "Verstehen, wie es funktioniert" – Architektur, Ablauf, Implementierung
  • "Für die Einführung bewerten" – Vor-/Nachteile, Alternativen, Passung für meinen Anwendungsfall
  • "Lernen, es zu nutzen" – Einrichtung, API, Erste Schritte
  • "Lernen, beizutragen" – Codebase-Struktur, Entwicklungsworkflow

Fokus (falls breites Thema):

• "Gibt es einen spezifischen Fokus?" mit Optionen:
  • "Alles" – Vollständige umfassende Analyse
  • "Nur Architektur" – Hochrangige Struktur und Muster
  • "Bestimmte Funktion" – Ein bestimmter Aspekt (angeben)

Hintergrund (falls hilfreich):

• "Ihr technisches Niveau?" mit Optionen:
  • "Nicht-technisch" – Von Grundprinzipien mit Analogien erklären
  • "Technisch, aber neu in diesem Bereich" – Grundlagen überspringen, auf Spezifika fokussieren
  • "Experte" – Tief technisch, setze Wissen voraus </initial_questions>

<decision_gate> Nach Antworten verwende AskUserQuestion (Modus A):

• question: "Bereit für den Tauchgang?"
• options:
  • "Ja, los" – Mehrphasige Analyse beginnen
  • "Erst noch mehr Fragen" – Ich habe Klärungsbedarf
  • "Lass mich Kontext hinzufügen" – Ich möchte Details ergänzen

Modus B überschreibt dieses Gate mit B2 (Schnappschuss + Umfang + Erkundungsgrenze + los/Tiefe/Browser) – nicht beide fragen; B2 ist das einzige maßgebliche Gate für Teardowns. </decision_gate>

</intake_gate>

Modusauswahl

Führe <intake_gate> aus, route dann gemäß der Betreff-Typ-Tabelle. Modus B (Live-Produkt / Wettbewerber / Datenprodukt / Rechner / Landschaft) → lade @references/competitor-teardown.md und folge dessen Scout → Bestätigung → Tiefe → Synthese-Ablauf (Grundgerüst unten). Modus A (Repo / Konzept / Doku) → Phasen 1–7 unten.

Modus B – Live-Produkt / Wettbewerber / Datenprodukt-Teardown

Vollständiges Playbook in references/competitor-teardown.md. Grundgerüst:

• B0 Fundierung: Speicher + ~/.claude/explanations/ auf frühere Analysen prüfen; erweitern, nicht wiederholen.
• B1 Scout: Ein leichter passiver Recon-Agent pro Ziel (WebFetch + Header + WebSearch) → fundierter Schnappschuss + was einen Browser benötigt.
• B2 Bestätigungsgate: Schnappschuss + Umfang + Erkundungsgrenze (<scope_boundary>) präsentieren; AskUserQuestion für los/Tiefe/Browser – nur überspringen, wenn der Benutzer bereits "tief gehen / vollen Umfang" gesagt hat.
• B3 Tiefenrecon (Workflow): Ein strukturierter Agent pro Thema, alle teilen das Schema pro Thema (in der Referenz). Standardmäßig pipeline(); große Ausgaben auf Disk aufteilen.
• B4 Browser (Claude-in-Chrome): Netzwerk beim Laden erfassen, SPAs rendern, Schätzer live über ein Eingaberaster testen, Sicherheitsheader, Paywall/Auth-Kopie – innerhalb der Grenze (kein CAPTCHA/Auth-Bypass, keine mutierenden Endpunkte, niemals Benutzerdaten eingeben). Erfassungen während des Vorgangs persistieren.
• B5 Reverse Engineering: Jeder Rechner → lauffähige TypeScript-Referenzimplementierung → gegen das Live-Raster validieren → gegen autoritative Grundwahrheit benchmarken.
• B6 Namensraum (falls "irgendwelche anderen?"): DNS+curl+Suche nach Kandidatendomains, klassifizieren, Betreibercluster finden, defensive-Buy-Domains markieren, nur die wirklich unterschiedlichen YES-Mengen zerlegen.
• B7 Synthese: Synthese-Agenten aufteilen → DETAILED-<Slug>.md ×N + ESTIMATORS.md + COMPARISON.md (inkl. einem Datenintegritäts- + Betreibercluster-Abschnitt) + REPLICATION-BLUEPRINT.md + ARCHITECTURE.md + NAMESPACE.md + SOURCES-*.md + SUMMARY.md (Executive Summary + Dateiindex). Dann Phase 7 Ausgabe/Aufräumen.

---

Modus A – Repo / Konzept / Doku

Phase 1: Parallele Web-Recherche (5 Forschungsagenten)

ALLE in einer Nachricht starten:

Task(subagent_type="general-purpose", prompt="Recherchiere [THEMA]: Was ist es? Wer hat es gemacht? Wann? Warum?")
Task(subagent_type="general-purpose", prompt="Recherchiere [THEMA]: Technischer Stack, Architektur, Schlüsseltechnologien")
Task(subagent_type="general-purpose", prompt="Recherchiere [THEMA]: Artikel, Rezensionen, Community-Diskussionen, Meinungen")
Task(subagent_type="general-purpose", prompt="Recherchiere [THEMA]: Alternativen, Vergleiche, wann verwenden vs. nicht")
Task(subagent_type="general-purpose", prompt="Recherchiere [THEMA]: Dokumentation, Tutorials, Erste-Schritte-Anleitungen")

Phase 2: Repository klonen (falls GitHub)

REPO_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_$(basename [URL] .git)
git clone [URL] $REPO_DIR
cd $REPO_DIR

Phase 3: Parallele Codebase-Exploration (6 Explore-Agenten)

ALLE in einer Nachricht mit thoroughness="very thorough" starten:

Task(subagent_type="Explore", prompt="Architektur: Gesamtstruktur, Module, wie sie zusammenhängen")
Task(subagent_type="Explore", prompt="Einstiegspunkte: Hauptdateien, CLI, API-Endpunkte, wie es startet")
Task(subagent_type="Explore", prompt="Kernlogik: Schlüsselalgorithmen, Muster, Abstraktionen")
Task(subagent_type="Explore", prompt="Konfiguration: Einstellungen, Umgebung, Erweiterungspunkte")
Task(subagent_type="Explore", prompt="Abhängigkeiten: Schlüsselpakete, Integrationen, externe Dienste")
Task(subagent_type="Explore", prompt="Tests und Qualität: Testmuster, Abdeckung, CI/CD")

Phase 4: Parallele Claude-Code-Kontext (2–3 general-purpose-Agenten)

Wenn für Claude/AI/Agenten relevant:

Task(subagent_type="general-purpose", prompt="Erkläre relevante Claude-Code-Konzepte zum Verständnis davon")
Task(subagent_type="general-purpose", prompt="Vergleiche mit Claude-Werkzeugen/SDK, falls zutreffend")

Phase 5: Zwischenprüfung (falls komplex)

Verwende AskUserQuestion, wenn die Ergebnisse Komplexität offenbaren:

• "Ich habe [X] gefunden. Möchtest du dich auf etwas Bestimmtes konzentrieren?"
• Optionen basierend auf Entdeckungen

Phase 6: Synthese

Alle Ergebnisse in einer umfassenden Erklärung zusammenführen mit:

1. Eröffnungsanalogie (nicht-technischer Vergleich)
2. Was es ist (1–2 Sätze)
3. Architekturdiagramm (ASCII)
4. Wie es funktioniert (Schritt für Schritt mit Diagrammen)
5. Tabelle der Schlüsselkomponenten (Name, Zweck, Funktionsweise)
6. Was ist besonders (Alleinstellungsmerkmale)
7. Funktionsliste (was es kann)
8. Vergleichstabelle (vs. Alternativen)
9. Technischer Tiefgang (Implementierungsdetails)
10. Fallstricke und Überlegungen

Phase 7: Ausgabe

In der Konversation anzeigen

Vollformatierte Erklärung mit allen visuellen Elementen.

In Dateien speichern

OUTPUT_DIR=~/.claude/explanations/$(date +%Y%m%d_%H%M%S)_[Thema-Slug]
mkdir -p $OUTPUT_DIR

# Dateien speichern:
# $OUTPUT_DIR/SUMMARY.md - Kurzreferenz (30-Sekunden-Version)
# $OUTPUT_DIR/DETAILED.md - Vollständige Analyse
# $OUTPUT_DIR/ARCHITECTURE.md - Alle Diagramme
# $OUTPUT_DIR/COMPARISON.md - Alternativanalyse

Nachbereitung

Nach der Anzeige fragen:

• "Welchen Aspekt möchtest du tiefer erkunden?"
• "Hast du Fragen zu dem, was ich erklärt habe?"
• Folgeerklärung fördern

Aufräumen

Verwende AskUserQuestion für das Aufräumen (kombinieren, wenn beides zutrifft):

Wenn Repo geklont wurde:

• question: "Das geklonte Repository löschen?"
• options:
  • "Ja, löschen" – $REPO_DIR automatisch entfernen
  • "Nein, behalten" – Pfad anzeigen: "Repo behalten unter: $REPO_DIR"

Wenn ja: rm -rf $REPO_DIR Wenn nein: Pfad für manuellen Zugriff anzeigen

Immer (Erklärungsdateien):

• question: "Die gespeicherten Erklärungsdateien löschen?"
• options:
  • "Ja, löschen" – $OUTPUT_DIR automatisch entfernen
  • "Nein, behalten" – Pfad anzeigen: "Erklärungen gespeichert unter: $OUTPUT_DIR"

Wenn ja: rm -rf $OUTPUT_DIR Wenn nein: Pfad für manuellen Zugriff anzeigen

Kombinierte Frage (falls sowohl Repo als auch Dateien):

• question: "Analyse abgeschlossen. Was möchtest du aufräumen?"
• options:
  • "Beide löschen (Repo und Erklärungsdateien)"
  • "Nur Repo löschen, Erklärungen behalten"
  • "Nur Erklärungen löschen, Repo behalten"
  • "Alles behalten"

Löschungen basierend auf Auswahl ausführen, Pfade für alles Behaltene anzeigen.

<visual_formats>

Standard-Diagrammformate

Architektur:

┌─────────────┐     ┌─────────────┐
│  Komponente │────►│  Komponente │
└─────────────┘     └─────────────┘

Ablauf:

START → Schritt 1 → Schritt 2 → Entscheidung?
                                  ├─ Ja → Pfad A
                                  └─ Nein → Pfad B

Vergleichstabelle:

| Aspekt      | Option A | Option B | Gewinner |
|-------------|----------|----------|----------|
| Geschwindigkeit | Schnell   | Langsam  | A        |

Komponentenaufschlüsselung:

┌──────────────────────────────────────┐
│           Systemname                 │
├──────────────────────────────────────┤
│ ┌────────┐ ┌────────┐ ┌────────┐    │
│ │Modul A │ │Modul B │ │Modul C │    │
│ └───┬────┘ └───┬────┘ └───┬────┘    │
│     └──────────┴──────────┘         │
│              Gemeinsame Schicht      │
└──────────────────────────────────────┘

</visual_formats>

<success_criteria> Beide Modi:

• Vor Beginn klärende Fragen gestellt / fundiert; in den korrekten Modus geroutet
• Visuelle Diagramme für jedes wichtige Konzept erstellt; reproduzierbare technische Tiefe geliefert
• Executive Summary in der Konversation angezeigt UND das Dokumentationsset in Dateien gespeichert
• Nachbereitung + Aufräumen angeboten; die Wahl des Benutzers zum Behalten/Löschen respektiert

Modus B (Live-Produkt / Wettbewerber / Datenprodukt / Landschaft) zusätzlich:

• Scout-Durchlauf + Bestätigungsgate durchgeführt (oder explizites "tief gehen" respektiert) und die Erkundungsgrenze genannt
• Streng innerhalb der Grenze geblieben: kein CAPTCHA/Auth-Bypass, keine Massenerfassung, keine mutierenden/Admin-Endpunkte aufgerufen, niemals Benutzerdaten eingegeben; Expositionen beobachtet, nicht ausgenutzt
• Workflow-Tool mit geteiltem Schema pro Thema bei 3+ Themen/mehrphasiger Arbeit verwendet; Artefakte persistiert; widerstandsfähig gegen Abbrüche (Fortsetzung)
• Jeden Rechner live getestet und eine lauffähige Referenzimplementierung geliefert, validiert N/N gegen beobachtete Ausgaben, benchmarkt gegen autoritative Grundwahrheit
• Für Landschaften: den vollständigen Namensraum entdeckt, jeden klassifiziert, Betreibercluster gefunden, defensive-Buy-Domains markiert, nur die unterschiedlichen zerlegt
• Synthese enthält einen Datenintegritätsabschnitt + einen Operator-Clusterabschnitt

…

[aus Gründen der Kürze abgeschnitten] </success_criteria>