d3group/d3-explainer

D3 Explainer (interaktives HTML, für die Autoren selbst)

<skill-dir> bezeichnet in diesem Skill das eigene Basisverzeichnis, das Claude Code anzeigt, wenn das Skill geladen wird (installiert als Plugin: ${CLAUDE_PLUGIN_ROOT}/skills/d3-explainer; manuell kopiert: ~/.claude/skills/d3-explainer). Ersetzen Sie den tatsächlichen Pfad in jedem Befehl. <wording-dir> bezeichnet <skill-dir>/../d3-scientific-wording, das gemeinsame Formulierungsskill, das jedes D3-Plugin mitbringt.

Eine einzige Offline-HTML-Datei, die ein Forschungsprojekt für diejenigen erklärt, die es schreiben: was die Frage ist, welche Lücke es schließt, wie die Kernidee funktioniert, wie jede Ableitung abläuft und warum, wo alles im Code lebt, was die Belege zeigen und was noch offen ist. Interaktive Grafiken tragen die Intuition bei; der Text bleibt nahe an den Quellen und gibt dies an.

Der Leser ist der Autor und seine Koautoren. Das entscheidet über fast alles unten:

• Sie kennen das Fachgebiet. Überspringen Sie Lehrbuchhintergrund, es sei denn, deren Notizen zeigen, dass es eine Schwachstelle ist.
• Sie wollen verstehen, daher schlägt Ehrlichkeit Politur: Annahmen, Meinungsverschiedenheiten zwischen Paper und Code und offene Fragen erhalten einen eigenen Abschnitt, und Interpretationen werden als solche gekennzeichnet.
• Sie werden Behauptungen mit ihren eigenen Dateien abgleichen, daher verweist jede substanzielle Behauptung auf ihre Quelle, und der Build überprüft, dass der Verweis existiert.
• Ausführlich ist in Ordnung, erschöpfend nicht. Tiefe, die nur manche Leser wünschen, kommt in eingeklappte Blöcke. „Jedes Detail“ geschieht nur, wenn der Benutzer danach fragt, und dann auch nur für den Teil, den er nennt.

Alle Python-Aufrufe erfolgen über uv (uv run, uv run --with <pkg>); niemals pip, niemals globale Installationen.

Referenzdateien (bei Bedarf laden)

Datei	Laden wenn
references/scanning.md	Phase 1: Ein Repository mit Token-Budget lesen, Eingabestufen, Vault / Recall / NotebookLM, frühere Erklärseiten
references/content-design.md	Phase 2 und 3: Abschnittsgliederung, Tiefenbudgets, wie die Lücke und Ableitungen dargestellt werden, ehrliches Inventar, was spezifisch für die Erklärseiten-Formulierung ist (die Regeln selbst: d3-scientific-wording)
references/components.md	Phase 3: Das HTML-Vokabular, Quellen-Chips, Build-Anweisungen, explainer.toml, die D3X JavaScript-API
references/visualization.md	Phase 2 und 3: Entwurf interaktiver Grafiken, die lehren; Musterkatalog; Fallstricke
references/review.md	Phase 4: Die zwei Prüfprompts, Token-Regeln, die Schleife
assets/example/	Ein kleines Repository mit einer fertigen Erklärseite. Lesen Sie assets/example/explainer/sections/*.html einmal, um die Arbeitsmuster jeder Komponente zu verstehen. Kopieren Sie es niemals in ein Benutzerprojekt.

Schritt 0: Einmal fragen

Falls der Benutzer es nicht bereits gesagt hat, fragen Sie diese in einer Nachricht und dann nicht noch einmal:

Umfang. Das gesamte Projekt oder ein Teil (ein Modell, eine Ableitung, eine Pipeline)? Tiefe. focus (eine Idee oder eine Ableitung: 1 bis 3 Abschnitte, eine oder zwei Grafiken, ca. 5 min), overview (4 bis 6 Abschnitte, ca. 10 bis 15 min Lesedauer), standard (Standard: 7 bis 10 Abschnitte, 4 bis 8 interaktive Grafiken, 1 bis 3 Ableitungen, 20 bis 35 min) oder deep (bis zu 14 Abschnitte). „Deep auf X“ bedeutet Standard plus einen Deep-Dive-Abschnitt zu X. Prüfung. light: automatisierte Prüfungen plus eigener Zahlencheck, fast keine zusätzlichen Token. single: ein Prüfagent prüft sowohl Korrektheit als auch Grafiken, eine Runde, ca. 50 bis 70k Token. standard: zwei Prüfagenten parallel (Korrektheit zu Ihren Quellen; Grafiken und Interaktion), eine Runde, zusammen ca. 100 bis 150k Token. Die Kosten eines Prüfers bestehen hauptsächlich aus einer festen Grundgebühr und hängen kaum von der Projektgröße ab, daher folgt meine Empfehlung der Tiefe: focus light, overview single, standard und deep die Zwei-Agenten-Prüfung. full: die zwei Agenten wiederholen, bis jede Bewertung 9 von 10 ist, begrenzt auf drei Runden, zwei- bis dreimal die Kosten von standard. Formulierung. ste (Standard: Simplified Technical English nach ASD-STE100, maximal 25 Wörter pro Satz, aktive Stimme, eine Bedeutung pro Wort; am einfachsten für Koautoren, die Englisch als Zweitsprache lesen) oder standard (die wissenschaftliche Formulierung der Gruppe ohne die STE-Grenzen).

„schnell“, „keine Prüfung“, „günstig“ oder „wenig Token“ bedeutet light. „gründlich“ bedeutet full. „nur diese Ableitung“, „nur X erklären“, „kurz halten“ bedeuten focus. „einfach“, „STE“ oder nichts gesagt bedeutet Formulierung ste; „normale Formulierung“, „Paper-Stil“ oder „kein STE“ bedeutet standard. Nichts gesagt bedeutet Tiefe standard und die für die Tiefe empfohlene Prüfung.

Wenn niemand antworten kann (ein Batch- oder Agentenlauf): nehmen Sie die Standardwerte, entscheiden Sie jeden Punkt, nach dem dieses Skill fragen würde, notieren Sie jede Entscheidung in Abschnitt 0 von brief.md und fahren Sie fort. Der Brief ist dann der Ort, an dem der Autor sehen kann, was für ihn entschieden wurde.

Arbeitsablauf

Geben Sie an jedem Phasenübergang eine einzeilige Statusmeldung mit Zeitstempel aus, wie die anderen D3-Skills: [HH:MM:SS] PHASE: ....

Phase 1: Das Projekt kartieren (günstig lesen, in der richtigen Reihenfolge)

uv run <skill-dir>/scripts/scan.py            # vom Repository-Root; fügen Sie --out explainer/suchprotokoll.md hinzu, um es zu behalten

Der Scan meldet die Eingabestufe (A: Code und Paper, B: nur Paper, C: nur Code, D: nur PDF, E: nur Notizen), wann die Orientierungsdokumente, das Paper und jeder Code-Ordner zuletzt geändert wurden (ein veraltetes CLAUDE.md oder ein verworfener Ansatz zeigt sich hier), die Paper-Gliederung mit seinen Gleichungsbezeichnern, die größten Code-Module mit Symbolnamen und Zeilennummern, einbettbare Ergebnisdateien, das Vault mit den eigenen Notizen des Autors nach Ordnern, frühere Erklärseiten und eine Token-Schätzung für jedes Orientierungsdokument, Paper, Abschnittsdatei, Code-Modul und jede Notiz. Geben Sie INPUT TIER: X aus und lassen Sie den Benutzer überschreiben.

Lesen Sie dann in dieser Reihenfolge und stoppen Sie, wenn der Brief geschrieben werden kann. Details und Budgets befinden sich in references/scanning.md.

1. Orientierungsdokumente (CLAUDE.md, README, Spezifikation oder Analysenotizen im Stammverzeichnis).
2. Das Paper: Zusammenfassung, Einleitung, Beitragserklärung, dann die Modell- und Methodenabschnitte. Überfliegen Sie die Ergebnisse nach den wichtigsten Zahlen.
3. Frühere Erklärseiten, die der Scan gefunden hat: die Gliederung (scan.py --explainer <datei>), dann einen Abschnitt vollständig für den Ton (--section N). Sie zeigen, was der Autor bereits versteht und welche Stimme er mag. Bauen Sie darauf auf; wiederholen Sie sie nicht.
4. Vault: Übersichts-, Konzept-, Lücken-, Entscheidungs- und Offene-Fragen-Notizen, ausgewählt nach Titel. Nicht die Literatursammlung.
5. Code: nur die Module, die die Kernidee umsetzen, gefunden über die Symboltabelle. Bei einer großen Codebasis (über etwa 40 Dateien oder 8.000 Zeilen) senden Sie einen Explore-Unteragenten, um die Paper-zu-Code-Zuordnung zu erstellen, und behalten Sie dessen Schlussfolgerung, nicht die Dateien.

Optionale Anreicherung, nur angeboten, wenn die Lücke oder die Projekthistorie im Repository dünn ist: das recall-Skill (was wurde entschieden und wann) oder NotebookLM (was die Literatur sagt). Gleiches Protokoll wie in d3-abstract. Wenn der Scan einen Literaturordner, ein Vault mit importierten Quellen oder ein NotebookLM-Notizbuch gefunden hat, bieten Sie in derselben Frage ein Themenprofil von d3-scientific-wording an (Schritt 1b): es zeigt, welchen Begriff und welche Schreibweise die Literatur für jedes Konzept verwendet, was die Notationstabelle und die Begriffstabelle anlegt. Geben Sie aus: ENRICHMENT: skipped | recall | notebooklm | both [+ wording profile].

Phase 2: Inhaltsbrief, genehmigt vor jeglichem HTML

uv run <skill-dir>/scripts/init.py --depth standard --review standard   # erstellt ./explainer: explainer.toml, brief.md, sections/, d3x/
#   mehrere Paper im Repository: fügen Sie --paper <ordner> hinzu         Erklärseite woanders: init.py <verz> --repo <repo-root>

Speicherort: <repo>/explainer/, im Stammverzeichnis des äußeren Repositorys (nicht innerhalb des Paper-Submoduls: Overleaf hat keine Verwendung dafür). Bestätigen Sie den Speicherort in derselben Nachricht wie den Brief.

Füllen Sie explainer/brief.md: das Projekt in zwei Sätzen, was der Leser danach können soll, gelesene und bewusst nicht gelesene Quellen, die Lücke, der Abschnittsplan, die Ableitungen, das ehrliche Inventar und was absichtlich weggelassen wurde, sowie die Formulierungszusammenfassung unter einer ## Wording-Überschrift (Genre Erklärseite, Leser die Koautoren, Fachgebiet, die gewählte Formulierungsart und eine Begriffstabelle für die Konstrukte und Symbole des Projekts). Der Abschnittsplan hat eine Zeile pro Abschnitt und, für jede interaktive Grafik, ihren Knopf-zu-Einsicht-Satz: „Bewegen von X zeigt, dass Y“. Eine Grafik ohne einen solchen Satz ist Dekoration und wird hier gestrichen, nicht nachdem sie gebaut wurde.

Zeigen Sie den Brief in kompakter Form im Chat und holen Sie die Genehmigung ein. Dies ist der eine obligatorische Kontrollpunkt: er kostet ein paar hundert Token und verhindert, dass die falschen 6.000 Wörter geschrieben werden. Schreiben Sie keine Abschnitte davor.

Phase 3: Schreiben, ein Abschnitt nach dem anderen

Rufen Sie d3-scientific-wording vor dem ersten Abschnitt auf (Skill-Tool: d3-scientific-wording:d3-scientific-wording; wenn es nicht aufgeführt ist, lesen Sie <wording-dir>/SKILL.md), mit dem Brief aus brief.md. Lesen Sie im ste-Modus auch <wording-dir>/references/ste.md. Laden Sie references/components.md und references/visualization.md und überfliegen Sie die Beispielabschnitte einmal; sie sind in STE geschrieben.

• Eine Datei pro Abschnitt: explainer/sections/NN-slug.html, genau ein <section id=... data-nav=... data-kicker=...> pro Datei. Der Build nummeriert sie und erstellt die Navigation.
• Nach jedem Abschnitt bauen, damit Fehler lokal bleiben: uv run explainer/d3x/build.py --draft (TODO-Markierungen und Links zu noch nicht geschriebenen Abschnitten geben nur eine Warnung)
• Reihenfolge innerhalb eines Kernidee-Abschnitts: einfacher Satz, interaktive Grafik, formale Aussage, Ableitung, wo es im Code lebt. Intuition zuerst, Algebra danach.
• Lassen Sie das Repository sprechen, anstatt es neu zu tippen. <div class="eq" data-label="eq:prob"></div> zieht die Gleichung aus der .tex-Datei des Papers (mit ihrer Nummer, falls eine .aux-Datei existiert). <pre class="code" data-src="src/model.py" data-lines="88-104"></pre> zieht die echten Zeilen. Beides ist günstiger als Tippen und kann nicht von der Quelle abweichen.
• Verweisen Sie mit Chips auf Quellen: [[paper:eq:prob]], [[code:src/model.py:88 def solve]], [[vault:Notizname]], [[result:results/table.csv]] und [[reading]] für Ihre eigene Interpretation. Der Build schlägt bei einer Datei, Zeile, einem Symbol, Bezeichner oder einer Notiz fehl, die nicht existiert; ein Vault-Chip gibt nur eine Warnung aus, solange kein Vault in explainer.toml konfiguriert ist. Ein fehlgeschlagener Chip ist ein Hinweis auf Ihr Verständnis: korrigieren Sie die Behauptung, löschen Sie den Chip nicht.
• Interaktive Grafiken zeigen in der Reihenfolge der Präferenz: die Ergebnisdateien des Repositorys; Zahlen, die vom eigenen Code des Repositorys auf einem Gitternetz berechnet wurden (ein kleines explainer/data/make_data.py, siehe visualization.md); oder die echte, im Browser in Spielzeuggröße neu implementierte Formel, deklariert als toy: true, was ein sichtbares Abzeichen „illustratives Spielzeug“ darauf setzt. Standardwerte entsprechen den Einstellungen im Paper. Zahlen werden aus Dateien eingebettet, niemals aus dem Gedächtnis getippt.
• Jede Bildunterschrift beginnt mit {fig} (der Build nummeriert Grafiken; verweisen Sie auf eine als {fig:figure-id}) und sagt, was man ausprobieren und was man beachten soll.

Phase 4: Überprüfen

uv run explainer/d3x/build.py                  # kein --draft: TODO-Markierungen schlagen jetzt fehl; gibt Wörter pro Abschnitt gegen das Tiefenbudget aus
uv run explainer/d3x/check.py --shots          # Headless-Browser: bewegt jedes Steuerelement, zieht jeden Griff, durchläuft jede Ableitung

check.py muss mit 0 error(s) enden. Überprüfen Sie dann die Formulierung der Abschnitte (lassen Sie --ste im standard-Modus weg); beheben Sie jeden Fehler und entscheiden Sie über jede Warnung:

uv run <wording-dir>/scripts/check_wording.py explainer/sections/*.html --genre explainer --ste

Es fängt, was das Lesen der Quelle nicht kann: NaN in einem Pfad, ein Steuerelement, das nichts ändert, eine Formel, die MathJax nicht rendern kann, ein abgeschnittenes Label an einem Schieberegler-Extremwert, Seitenüberlauf bei Telefonbreite. Sein erster Lauf auf einem Rechner kann einmal nach einem Browser fragen: uv run --with playwright playwright install chromium (es fällt auf ein installiertes Chrome oder Edge zurück).

Sehen Sie sich zwei oder drei der Screenshots in explainer/review/shots/ selbst an. Überprüfen Sie dann mit der gewählten Tiefe; Prompts und Token-Regeln befinden sich in references/review.md:

• single: ein schreibgeschützter Prüfer mit dem zusammengeführten Prompt aus references/review.md, der beide Pakete, check.md und die Screenshots in einer Runde liest. Dann überprüfen und anwenden wie unten.
• light: keine Prüfagenten. Führen Sie selbst einen Zahlencheck durch: jede Zahl im Text, die KPI-Kacheln und die Grafik-Standardwerte gegen das Paper oder die zitierte Ergebnisdatei. Dann stoppen.
• standard: zwei schreibgeschützte Prüfer parallel, eine Runde. Jeder Build schreibt zwei Pakete in explainer/review/: fidelity-packet.md (der Text der Erklärseite mit Zeilennummern, die Ableitungsschritte mit ihren Gründen und für jeden Chip die zitierte Gleichung oder Codezeilen als Beleg) und figures-packet.md (Bildunterschrift und Skript jeder Grafik). Der Korrektheitsprüfer überprüft Ableitungen, Zahlen, Lückenbehauptungen und die Formulierung (der Kaltstart und die Regeln von d3-scientific-wording) aus dem ersten; der Erfahrungsprüfer überprüft, dass jede Grafik ihren Knopf-zu-Einsicht-Satz aus dem zweiten lehrt, plus check.md und die Screenshots. Keiner muss das Repository durchstreifen, was die Prüfung günstig hält. Bearbeiten Sie keine Abschnittsdateien, während sie laufen. Überprüfen Sie dann jeden Blockierer und jede Hauptsache selbst, wenden Sie sie an, bauen Sie neu, führen Sie check.py erneut aus. Ein zweiter Blick erfolgt nur bei einem Blockierer, nur durch den Prüfer, der ihn gemeldet hat, nur auf die geänderten Dateien.
• full: die gleichen zwei Prüfer, in einer Schleife, bis jede Kategorie 9 oder besser ist, begrenzt auf drei Runden; übergeben Sie dann die verbleibenden Punkte an den Benutzer.

Phase 5: Ausliefern

Geben Sie den Pfad explainer/dist/<name>.html an (eine Datei, funktioniert offline, per E-Mail versendbar), die verwendete Prüftiefe und die zusammengeführte Ergebnistabelle mit dem, was behoben wurde. Erwähnen Sie: n öffnet die Notationsleiste, Ableitungen schreiten mit „Nächster Schritt“ fort, Chips verlinken auf GitHub-Permalinks beim erstellten Commit, wenn das Remote auf GitHub ist. Bieten Sie an, eine Kopie des HTML in das Vault zu legen, falls das Repository eines hat, wo die früheren Erklärseiten des Autors leben. Stellen Sie die Wasserzeichenfrage von d3-scientific-wording (Schritt 5) einmal; bei Zustimmung bereinigen Sie explainer/sections/*.html (niemals die erstellte Datei, die MathJax und Schriftarten einbettet) und bauen Sie neu. Bieten Sie an, explainer/ zu committen (das erstellte Verzeichnis liegt in .gitignore).

Sprachspezifische Ausnahmen

Dieses Skill ist auf Englisch definiert. Wenn der Benutzer eine Erklärseite in einer anderen Sprache wünscht, verwenden Sie die brief.md- und Abschnittsvorlagen auf Englisch, schreiben Sie die Abschnitte aber in der Zielsprache. Die interaktiven Grafiken (Knopf-Labels, Tooltips) müssen in dieser Sprache sein. Das d3-scientific-wording-Skill wirkt sich nur auf den englischen Text aus.

Fehlerbehandlung: Das Reparaturmuster

Wenn ein Build oder eine Prüfung fehlschlägt:

1. Lesen Sie die Fehlerausgabe vollständig.
2. Wenn auf eine Datei verwiesen wird, die nicht existiert, korrigieren Sie den Chip oder erstellen Sie die Datei.
3. Wenn eine Grafik keinen Knopf-zu-Einsicht-Satz hat, fügen Sie einen hinzu oder entfernen Sie die Grafik.
4. Wenn eine Ableitung einen mathematischen Fehler hat, korrigieren Sie die Formel.
5. Wenn die Formulierung gegen die STE-Regeln verstößt (nur im ste-Modus), schreiben Sie den Satz um, um die Regel einzuhalten.

Wenden Sie niemals eine Korrektur an, ohne die zugrunde liegende Behauptung gegen die Quelle zu überprüfen.

Abhängigkeiten und benötigte Umgebung

• Python 3.10+ mit uv
• Playwright (für Prüfungen mit check.py)
• Ein Repository, das Folgendes enthalten kann: Paper-LaTeX-Quellen (.tex-Dateien), Code (beliebige Sprache), Ergebnisdateien (CSV, JSON, NumPy-Arrays)

Fazit

Der D3 Explainer ist ein Werkzeug für Forscher, die ihr eigenes Projekt tief verstehen möchten, und zwar durch eine einzige, interaktive HTML-Datei. Der Fokus liegt auf Korrektheit, Quellentreue und Interaktivität, wobei die Leser – die Autoren selbst – im Mittelpunkt stehen.

---

D3 Explainer: Bauen, was Sie verstehen wollen – interaktiv, quellgebunden und für Ihr Team geschrieben.