anniebelleb/narrated-data-lesson

Erzählte Daten-Lektion

Erstellt eine Lektion wie das Referenzbeispiel („Mit wem wir unseren Tag verbringen, nach Alter“): ein erzähltes Video, das auf einem Live-Diagramm abläuft, sowie einen Explore-Tab, in dem Lernende mit den Daten spielen können. Eine Lektion entspricht einem Ordner mit index.html, lesson.json, data.json, video.json (Storyboard), Sprachaufnahme und optionaler Hintergrundmusik.

Zuerst lesen: references/design-rules.md (genehmigtes Aussehen, Bewegung und Betonungsregeln; exakt befolgen) und references/user-guidance.md (wie man mit dem Nutzer arbeitet).

Die Pfade unten sind relativ zum Ordner dieser Fähigkeit (${CLAUDE_SKILL_DIR}).

Mit wem Sie arbeiten

Gehen Sie davon aus, dass der Nutzer nicht technisch ist. Sprechen Sie klar, Schritt für Schritt, und sagen Sie ihm genau, worauf er klicken muss, wenn eine Aktion erforderlich ist (Herunterladen einer Datei, Anmelden bei ElevenLabs, Genehmigung eines Skripts). Bitten Sie ihn niemals, Code oder JSON zu bearbeiten. Verwenden Sie die Schritt-für-Schritt-Anleitungen in references/user-guidance.md.

Der Arbeitsablauf (mit Checkpoints und Selbstprüfungen)

Führen Sie die Selbstprüfung am Ende jedes Schrittes durch. Fahren Sie bei einem FEHLER nicht fort.

1. Daten beschaffen

• Akzeptieren Sie einen Link, eine Datei oder ein PDF. Wenn ein Link blockiert ist (Websites blockieren oft automatisierte Downloads), führen Sie den Nutzer durch den Download in seinem Browser und das Teilen der Datei.
• Profilieren Sie sie: python3 scripts/profile_data.py <Datei-oder-URL>.

2. Passt es? (dem Nutzer immer mitteilen)

Lesen Sie die Bewertungen des Profilers und references/chart-chooser.md, und teilen Sie dem Nutzer dann in einfacher Sprache mit:

• Passt: „Das funktioniert als ___ weil ___.“ Nennen Sie die Lernfrage, die es beantwortet.
• Passt teilweise: was funktioniert, was fehlt und der Zielkonflikt.
• Passt nicht: Sagen Sie es klar, erklären Sie warum und beschreiben Sie, welche Daten funktionieren würden. Erzwingen Sie es nicht.

✋ Checkpoint 1: Diagrammtyp und Erzählwinkel

Schlagen Sie den Diagrammtyp, die Hauptlernfrage und 4–6 Handlungsstränge vor (die Dinge, die der Erzähler hervorheben wird), die jeweils an eine Zahl gebunden sind, die Sie berechnen werden. Warten Sie auf die Zustimmung des Nutzers.

3. Daten formen

• Starten Sie den Lektionsordner: python3 scripts/new_lesson.py --chart <Typ> --out <Ordner>.
• Schreiben Sie ein kleines, wiederholbar ausführbares Skript (im Lektionsordner), das die Quelle in data.json im Format des Diagramms (references/data-formats.md) und in facts.json umwandelt: jede Zahl, die der Erzähler sagen wird, berechnet aus den Quelldaten, mit Angabe, wie sie gesprochen wird.
• Selbstprüfung: python3 scripts/check_lesson.py <Ordner>; überprüfen Sie außerdem stichprobenartig 2–3 Werte manuell anhand der Quelle (öffnen Sie die Rohdatei und suchen Sie sie). Geben Sie an, was Sie überprüft haben.

4. Die Geschichte schreiben

• Schreiben Sie video.json (Szenen, Handlungsstränge, Cues) gemäß references/storyboard.md und dem Handlungsbogen in design-rules §1 (Einleitungshaken → Wie man das Diagramm liest → Handlungsstränge → Zusammenfassung → Reflexion → „Du bist dran“).
• Schreiben Sie das Erzählskript im ElevenLabs-Stil (references/narration.md) in narration/script.txt. Jede Behauptung muss mit facts.json übereinstimmen; vermeiden Sie Übertreibungen (design-rules §8).
• Füllen Sie lesson.json aus: Titel, Vorspann, Schlüssellabel, Gruppenbeschreibungen, Notizen, Quellen.

✋ Checkpoint 2: Skript genehmigen

Zeigen Sie das Skript als Klartext an. Bieten Sie Optionen an, wenn der Nutzer danach fragt; wenden Sie keine Änderungen an, die er nicht genehmigt hat.

5. Vorschau (vor jeder Aufnahme)

• Stille Vorschau: python3 scripts/estimate_timing.py <Ordner>/video.json --out <Ordner>/narration/narration.words.json danach python3 scripts/time_storyboard.py <Ordner>/video.json <Ordner>/narration/narration.words.json.
• Bereitstellen und öffnen: python3 scripts/devserver.py 8123 (vom Ordner über der Lektion aus), dann http://localhost:8123/<Lektion>/.
• Selbstprüfung (Browser): Befolgen Sie references/self-checks.md: Screenshots bei jedem Handlungsstrang, nichts überlappt, keine Konsolenfehler, jedes benannte Element wird bei seinem Wort hervorgehoben.

6. Erzählung und Musik (benötigt das ElevenLabs-Konto des Nutzers)

• Führen Sie den Nutzer durch die Anmeldung (user-guidance.md → ElevenLabs). Einstellungen: Stimme Quentin – Erzähler und Pädagoge, Eleven v4, Stabilität ≈ 80%, Englisch; das gesamte Skript in einem Durchlauf. Speichern als narration/narration.mp3.
• Kein ElevenLabs? Bieten Sie den kostenlosen Platzhalter an: python3 scripts/placeholder_voice.py <Ordner> (Mac).
• Wörter zeitlich abstimmen: python3 scripts/align_narration.py <Ordner>/narration/narration.mp3 --out <Ordner>/narration/narration.words.json, dann erneut time_storyboard.py. Ziel ist ≥ 99 % der Wörter abgeglichen.
• Musik (optional, ElevenLabs Music, instrumental, ruhig, ~2 Min.): vorbereiten mit prep_music.py; wenn das Video länger ist als der Titel, mit find_loop.py + extend_music.py verlängern (niemals enden oder unter dem Erzähler loopen lassen).
• Selbstprüfung: check_lesson.py (Audiolängen, Fakten) + eine vollständige Wiedergabe im Browser.

✋ Checkpoint 3: Gemeinsam überprüfen

Führen Sie den Nutzer durch die fertige Lektion: worauf er achten soll, wie er Explore ausprobiert. Nehmen Sie die gewünschten Änderungen vor und führen Sie die Selbstprüfungen nach jeder Änderung erneut durch.

7. Veröffentlichen (optional)

Führen Sie den Nutzer durch GitHub Pages oder einen anderen statischen Host (user-guidance.md → Veröffentlichung). Der Lektionsordner ist in sich geschlossen.

Selbstprüfungsregeln (immer)

• Führen Sie scripts/check_lesson.py nach den Schritten 3, 4, 5, 6 und nach jeder Überarbeitung aus.
• Überprüfen Sie nach jeder visuellen Änderung im Browser: Machen Sie Screenshots zu den erzählten Zeitpunkten und vergleichen Sie sie mit dem Storyboard. Geben Sie an, was Sie überprüft haben.
• Berechnen Sie jede erzählte Zahl aus den Quelldaten neu; geben Sie niemals eine Zahl aus dem Gedächtnis ein.
• Wenn etwas fehlschlägt, beheben Sie es und überprüfen Sie es erneut, bevor Sie dem Nutzer mitteilen, dass es fertig ist.

Referenzdateien

Datei	Verwendung
references/design-rules.md	Aussehen, Bewegung, Betonung, Erzählung, Synchronisation, Musik, Datenintegrität
references/chart-chooser.md	Welches Diagramm für welche Frage; Eignungskriterien
references/data-formats.md	Die vier data.json-Formate
references/storyboard.md	video.json: Szenen, Handlungsstränge, Cues pro Diagrammtyp, facts.json
references/narration.md	Skriptstil, ElevenLabs-Einstellungen, Timing, Musik
references/self-checks.md	Was in jedem Schritt zu überprüfen ist
references/user-guidance.md	Einfache Schritt-für-Schritt-Anleitungen für den Nutzer
references/chart-interface.md	Hinzufügen eines neuen Diagrammtyps