yapi777/create-doc

Create-doc — Erstellt eine Gliederung zum Übergeben an die Folien-Fähigkeit

Liest Forschungsnotizen (Ausführungsprotokolle .md, Ergebnis-CSVs, Abbildungen, Code) und schreibt eine Gliederung in Markdown, in der für jede Folie festgelegt ist: Was gesagt wird, mit welchem Layout gezeigt wird, was darauf steht und was gesprochen wird.

Abnehmer ist die Fähigkeit progress-report-deck (im selben Plugin research-slides, im Nachbarordner ${CLAUDE_SKILL_DIR}/../progress-report-deck/). Die Ausgabe dieser Fähigkeit wird so erstellt, dass progress-report-deck jede ##-Überschrift als eine Folie betrachtet und in eine Vorlage einfügt. Bevor mit der Arbeit begonnen wird, muss ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md gelesen werden, um zu prüfen, ob die unten stehenden 'Absprachen mit der Folien-Fähigkeit' noch aktuell sind. (Wenn sich die Regeln dort geändert haben, wird an die dortigen Regeln angepasst.) Falls keine Abweichungen gefunden werden, kann nach diesen Absprachen verfahren werden.

Das Benutzerprofil ~/.claude/yapi-skills/profile.md (Name, Forschungsbereich, hauptsächliches Publikum, eigene Regeln) wird zuerst gelesen, falls vorhanden. Eigene Regeln (Farbschema, minimale Schriftgröße etc.) haben Vorrang vor den untenstehenden Absprachen und werden in den Abschnitt „Über dieses Dokument“ der Gliederung übernommen.

Eine Beispielvorlage für die Gliederung befindet sich in references/template.md. Im Zweifelsfall wird diese Vorlage zur Formatierung verwendet.

Absprachen mit der Folien-Fähigkeit (basierend auf den Regeln von progress-report-deck)

Die Gliederung muss diese Regeln einhalten. Andernfalls könnten bei der Folienerstellung Folien gelöscht oder neu erstellt werden.

Kategorie	Absprache	Grund (Regeln von progress-report-deck)
Überschriften	Ein ## = eine Folie. Auch für Ergänzungen wird ## ausschließlich für Folien verwendet. Abschnittswechsel werden mit # markiert.	Der Entwurf liest ## als Folien.
Grundgerüst	Reihenfolge: Titel → Heutige Agenda (Inhaltsverzeichnis) → Forschungshintergrund (1/2)(2/2) → Forschungsziel (diesmaliges Teilziel) → Inhalt → Zusammenfassung & offene Fragen → Vielen Dank für Ihre Aufmerksamkeit	Feste Vorlage des Templates
Forschungshintergrund	Wenn er sich seit dem letzten Mal nicht geändert hat, wird „Unverändert (wie im Basismaterial)“ geschrieben, ohne den Inhalt auszuführen.	Der Hintergrund bleibt in der Regel unverändert.
Diesmaliges Teilziel	Auf der Forschungsziel-Folie muss zwingend der Text „Diesmaliges Teilziel“ (1–2 Zeilen) stehen.	Die andere Fähigkeit fragt dies jedes Mal beim Benutzer ab. Es soll vorab festgelegt werden.
Folienanzahl	Die finale Anzahl wird angegeben (damit die andere Fähigkeit nicht mehr zusammenführen oder teilen muss).	Bei vielen ## schlägt die andere Fähigkeit eine Zusammenführung vor.
Layout-Typ	Jede Inhaltsfolie erhält einen Layout-Typ (siehe Tabelle unten).	Beim Einfügen von Aufzählungspunkten wird sonst „untere Hälfte leer“ bemängelt.
Farbzuordnung	Es gibt nur zwei Farbbedeutungen: Blau = Vorschlag, Lösung, Schlussfolgerung, Hauptwert; Orange = Bisherige Methode, Problem, Hinweis, Warnung. Es wird keine dritte Farbe pro Methode zugewiesen. In Tabellen wird die Hauptzeile als „hervorgehoben in Hellblau“ markiert.	Das Theme verwendet nur Blau #156082 und Orange #E97132.
Textmenge	Die Kernaussage maximal 30 Zeichen (japanische Vollbreite) (passt in eine Zeile bei 18pt). Auch ein Aufzählungspunkt max. ~30 Zeichen. Maximal 3 Zeilen pro Panel. Bei längerem Text wird eine Abbildung oder Tabelle verwendet, oder die Folie wird geteilt.	Schriftgröße muss mindestens 16pt sein; Verkleinern und Zusammenquetschen ist nicht erlaubt.
Schriftgröße	Keine Anweisungen wie „kleiner“ oder „Fußnote in kleiner Schrift“. Auch Fußnoten werden in 16pt gehalten (max. 1 Zeile).	Schrift <16pt ist verboten.
Formeln	In $...$ (LaTeX-Notation) schreiben und „Formel (OMML)“ angeben.	Formeln werden in OMML gesetzt.
Abbildungen	Als PNG in images/ im Ausgabeordner angeben (z. B. images/<Name>.png). Falls nur PDF vorhanden, in PNG konvertieren und einfügen. Keine Pfade wie ../ oder Pfade innerhalb des Repositorys verwenden. Beachten, dass das Bild in ein 4:3-Folienformat passen muss (z. B. zwei breite Bilder vertikal anordnen).	In pptx werden PNGs eingefügt. Folien sind 4:3. Die Folien werden möglicherweise in einem anderen Ordner oder auf einem anderen Gerät erstellt, sodass außerhalb des Ordners liegende Pfade nicht sichtbar sind.
Schemaskizzen	Für Dinge ohne Bilddatei, die aber grafisch dargestellt werden sollen (Prozessablauf, Zeitstrahl, Vergleich alt/neu), wird der Typ und die Zeichenweise konkret beschrieben.	Die andere Fähigkeit muss dann nicht beim Benutzer nachfragen, wie das Bild behandelt werden soll.
Notizen	Der Sprechtext wird in die „Notizen“ geschrieben. Nicht auf die Folie selbst.	—
Ergänzungen	Backup-Folien für die Fragerunde werden nach „Vielen Dank für Ihre Aufmerksamkeit“ eingefügt.	Der Abschluss ist das Ende des Hauptteils.

Verfügbare Layout-Typen (basierend auf Beispielen in assets/template.pptx von progress-report-deck):

Typ	Verwendung	Beispiel in template.pptx
Chip + Panel (Problem → Lösung)	„Bisheriges Problem → Heutige Lösung“, „Hinweis → Antwort“	S.7, S.11
Nummern-Badge + Panel	Aufzählung von nummerierten Punkten (Vorteile, Schritte) ①②③	S.8-9
Before/After-Schema	Vergleich bisherige Methode (links, orangener Rahmen) und vorgeschlagene Methode (rechts, blauer Rahmen) mit Pfeil dazwischen	S.10
Zeitstrahl-Schema	Zeitlicher Ablauf eines Prozesses (durchgezogene/gestrichelte Boxen + Verbinder)	S.12
2-spaltiger Chip + Panel + unterer Balken	Vergleich zweier Methoden/Einstellungen nebeneinander, inkl. Formel	S.13
Tabelle + vollbreiter Balken	Ergebnistabelle mit darunterliegendem Balken „Was daraus abzulesen ist“ (eine Hauptzeile wird dunkelblau hervorgehoben)	S.14
KPI-Kacheln (2×2)	Vier Werte oder Schlussfolgerungen groß darstellen	S.15
Checkliste (✓)	Aufzählung von geprüften oder erledigten Punkten	S.16
Rahmen-Box, 2-stufig	Zusammenfassung / Ausblick	S.17
Bild + vollbreiter Balken	Vorhandenes Bild groß einfügen, darunter einen Balken mit dem abzulesenden Inhalt	(S.14 mit Bild statt Tabelle)

Das Inhaltsverzeichnis (heutige Agenda) erhält keinen Layout-Typ (einfache Aufzählung, nur Schlüsselwörter fett, keine Farbe).

Vorgehensweise

1. Anforderungen erfragen (AskUserQuestion, gebündelt in einer Anfrage)

Was bereits aus dem Gespräch oder der Aufgabenstellung klar ist, wird nicht erfragt. Nur Unklares wird erfragt.

• Art und Dauer des Vortrags: Fortschrittsbericht / Seminar / Konferenz. Faustregel: 1 Inhaltsfolie ≈ 1 Minute (bei 15 Minuten ca. 10 Inhaltsfolien + 5–6 für das Grundgerüst)
• Publikum: Labormitglieder / Konferenz / fachfremde Zuhörer. Der erforderliche Wissensstand ändert sich.
• Einzuschließende Randinformationen (Mehrfachauswahl): Motivation/Hintergrund, Vergleichsexperimente, Fehleranalyse, Methodenentwicklung, Auswirkungen von Bugfixes etc. Die Optionen werden aus den in den Aufzeichnungen gefundenen Themen abgeleitet.
• Forschungshintergrund unverändert oder nicht: Falls Änderungen zum vorherigen Material nötig sind, wird der neue Inhalt genannt.

Wenn der Benutzer in Freitext antwortet und nicht die angebotenen Optionen wählt, wird dies ebenfalls als Anforderung behandelt (z. B. „Füge auch noch XXX als Aufhänger hinzu“).

2. Material sammeln (nur lesen, keine erneute Durchführung von Experimenten)

• Folien-Fähigkeit: ${CLAUDE_SKILL_DIR}/../progress-report-deck/SKILL.md (Überprüfung der obigen Absprachen)
• Protokolle: Ausführungsprotokoll_*.md, *Ergebnis*.md, README.md, Strategiedokumente etc. Die neuesten zuerst lesen.
• Zahlenwerte: summary/*.csv, Tabellen in *.md. Die im Vortrag zu verwendenden Zahlen werden zwingend von hier übernommen.
• Abbildungen: Mit ls nach vorhandenen PNGs suchen. Abbildungen mit japanischen Labels werden bevorzugt. Der ursprüngliche Pfad einer verwendeten Abbildung wird notiert (für Schritt 4 in images/ kopieren und als Quelle angeben).
• Konfigurationswerte: Hyperparameter, Konstanten, Modellarchitektur (für Backup-Folien) werden nicht aus den Protokoll-MDs, sondern aus den tatsächlichen Code-Werten entnommen (Konstanten, argparse-Standardwerte, zur Laufzeit gespeicherte Konfig-JSONs). Bei Abweichungen zwischen Protokoll und Code gilt der Code als richtig; der Benutzer wird darüber informiert.

3. Gliederung festlegen

Angepasst an die Vorlage von progress-report-deck:

1. Titel
2. Heutige Agenda (Inhaltsverzeichnis; kurze Auflistung der Inhaltsfolien-Titel)
3. Forschungshintergrund (1/2)
4. Forschungshintergrund (2/2)
5. Forschungsziel (Ziel + diesmaliges Teilziel)
6. ∼ Inhaltsfolien
7. Zusammenfassung & offene Fragen
8. Vielen Dank für Ihre Aufmerksamkeit
9. Backup-Folien (für die Fragerunde)

Die Inhaltsfolien folgen in etwa diesem Ablauf (je nach Anzahl anpassen):

1. Motivation / Problem (Warum wurde das gemacht?) → Chip + Panel
2. Inhalt & Vorteile des Vorschlags/der Änderung → Before/After-Schema oder Nummern-Badge + Panel
3. Detail der Methode (Prozessablauf) → Zeitstrahl-Schema
4. Korrektheitsnachweis / Verifikation → Checkliste
5. Bestimmung der Parameter → KPI-Kacheln oder Tabelle + Balken
6. Versuchseinstellungen (Daten, Vergleichsmethoden, Metriken) → 2-Spalten oder Tabelle + Balken
7. Ergebnisse (1 Folie pro Kernaussage) → Tabelle + Balken, Bild + Balken
8. Kosten / Einschränkungen → Tabelle + Balken oder KPI-Kacheln

Es werden zwingend Backup-Folien (für die Fragerunde) erstellt. Diese sind nicht in der Vortragszeit enthalten.

• Detaillierte Einstellungen (Modell, Optimierer, Konstanten als Tabelle)
• Daten- / Simulationskonfiguration
• Details zu Vergleichsmethoden (Formeln mit OMML-Angabe)
• Exakte Definition der Metriken
• Vollständige Ergebnistabelle (z. B. Parametersuche)
• Erwartete Fragen und Antwortvorschläge (ca. 8 Stück): Diese werden nicht als Folie erstellt, sondern als #-Abschnitt am Ende der Gliederung (als Handzettel für den Vortragenden). Bevorzugt werden Fragen, die Schwachstellen aufdecken: „Ist der Unterschied nicht zu klein?“, „Kann man das aus einem einzelnen Durchlauf sagen?“, „Warum wurde genau dieser Vergleichsgegenstand gewählt?“, „Wie hoch sind die Rechenkosten?“, „Was ist die Grundlage für die unbelegte Behauptung?“.

4. Schreiben (in einem Ordner ausgeben)

Die Folien werden mit progress-report-deck möglicherweise in einem anderen Ordner oder auf einem anderen Gerät (z. B. einem PC mit PowerPoint) erstellt. Daher werden die Gliederung und die benötigten Bilder in einem Ordner zusammengefasst ausgegeben, sodass nur dieser Ordner benötigt wird, um die Folien zu erstellen.

Foliendokument-<Datum>/
├── Foliendokument-<Datum>.md   ← Gliederung
└── images/
    ├── speed_sweep.png
    └── ...

• Ordnername und Dateiname der .md-Datei werden auf Foliendokument-<Datum> vereinheitlicht (z. B. Foliendokument-2026-10-15/). Das Datum ist das Erstellungsdatum im Format YYYY-MM-DD. Falls am selben Tag mehrere Dokumente für verschiedene Vorträge erstellt werden, wird dem Datum ein kurzer Identifikator angehängt (z. B. Foliendokument-2026-10-15-Seminar/). Vorhandene Ordner werden nicht überschrieben. Der Ordner wird direkt im Projektstammverzeichnis erstellt.
• Bilder: Alle in der Gliederung verwendeten Bilder werden in images/ kopiert (nicht verschoben – die Originaldateien bleiben unberührt).
  • Der Dateiname bleibt der ursprüngliche. Bei Namenskonflikten oder unverständlichen Namen (z. B. fig1.png) wird ein aussagekräftiger Name aus alphanumerischen Zeichen vergeben (z. B. velocity_field_f195.png). Keine Leerzeichen verwenden.
  • Falls nur ein PDF vorhanden ist, wird es in PNG konvertiert und eingefügt (z. B. pdftoppm -png -r 200 -singlefile input.pdf images/name oder mit PyMuPDF bei 200 dpi).
  • In der Gliederung wird mit images/<Name>.png darauf verwiesen.
  • Der ursprüngliche Pfad wird im Abschnitt „Quellen“ als images/xxx.png ← ursprünglicher Pfad notiert (damit die Grafik später bei Bedarf neu erstellt werden kann).
• Schemaskizzen (für die keine Bilddatei existiert) werden nicht als Bild erstellt, sondern in der Gliederung wird die Zeichenweise beschrieben.

Im einleitenden Abschnitt „Über dieses Dokument“ (als #-Abschnitt, keine Folie) werden Anweisungen für progress-report-deck notiert:

• Art, Länge, Anzahl der Folien, Publikum des Vortrags
• Format jeder Folie (siehe unten)
• Zahlenwerte dürfen nicht verändert oder gerundet werden.
• progress-report-deck muss mit diesem Ordner als Arbeitsordner ausgeführt werden. Die Bilder befinden sich im images/-Unterordner und werden mit images/<Name>.png referenziert. Es werden keine neuen Bilder erstellt (Schemaskizzen werden wie angegeben gezeichnet).
• Schreibregeln für Methodennamen, Farbzuordnung (Blau = Vorschlag, Orange = Bisherige Methode/Vergleichsmethode)
• Ob der Forschungshintergrund unverändert bleibt oder nicht

Format jeder Folie:

## Folie N — <Titel>

- **Typ**: <Layout-Typ (einer aus der obigen Tabelle)>
- **Kernaussage**: <Ein Satz, max. 30 Zeichen. Die wichtigste Aussage dieser Folie>
- **Text**: <Aufzählung. Ein Punkt max. ~30 Zeichen, max. 3–4 Punkte>
- **Tabelle** / **Bild**: <Tabelle in Markdown mit Angabe der hervorzuhebenden Zeilen/Spalten. Bild als `relativer/Pfad.png` (Art des Bildes)>
- **Formel (OMML)**: <falls vorhanden in $...$>
- **Notizen**: <Sprechtext. Wird nicht auf die Folie geschrieben>

Schreibregeln:

• Die Kernaussage enthält die Schlussfolgerung. Nicht „Ergebnis ①“, „Über XXX“, „Zeigt XXX“, sondern „Je höher die Geschwindigkeit, desto größer der Unterschied“. Keine Höflichkeitsfloskeln am Ende.
• Bewertende Wörter werden durch Zahlen belegt. Wenn „deutlich“, „effektiv“, „überlegen“ geschrieben wird, müssen auf derselben Folie Vergleichsobjekt, Metrik und Anzahl der Durchläufe stehen. „Gleichwertig“ und „garantiert“ sind oft übertrieben (besser „annähernd gleichwertig“, „bestätigt“).
• Typische KI-Formulierungen (äußerst, bahnbrechend, ermöglicht es [zu], nahtlos etc.) werden vermieden. Eine Liste mit Ersetzungen findet sich in ${CLAUDE_SKILL_DIR}/../progress-report-deck/references/ai-smell-lexicon.md.
• Aufzählungspunkte im Text sind ein Satz pro Punkt (zwei Sätze, die durch „。“ verbunden sind, werden getrennt).
• Nicht überprüfte Behauptungen werden als solche gekennzeichnet. Erwartete Eigenschaften und experimentell gezeigte Sachverhalte werden nicht vermischt. Im Text der entsprechenden Folie oder im Balken wird eine Zeile eingefügt; im Abschnitt „Zusammenfassung & offene Fragen“ wird dies unter „Zukünftige Arbeiten“ aufgeführt.
• Bedingungen für einen fairen Vergleich (z. B. „Konvergierte Einstellungen verwendet“) werden in einer einzeiligen Fußnote notiert. Ausführliche Erklärungen der Historie werden nur geschrieben, wenn der Benutzer dies explizit wünscht.
• Ausführliche Erklärungen, die nicht auf die Folie passen, werden in die Notizen oder auf Backup-Folien verschoben. Der Fließtext wird nicht verlängert.
• Am Ende wird eine Tabelle „Quellen“ (Inhalt → Datei) als #-Abschnitt angehängt.

5. Validierung (zwingend erforderlich)

1. Automatischer Zahlenabgleich: Alle Dezimalzahlen aus der Gliederung werden mit einem regulären Ausdruck extrahiert und mit den Werten in den Quell-MDs/CSVs abgeglichen (CSV-Werte auf 4 bzw. 2 Nachkommastellen gerundet). Nicht gefundene Werte werden einzeln überprüft: Handelt es sich um eine selbst berechnete Differenz, einen Übertragungsfehler oder inkonsistentes Runden? Das Abgleichsskript wird im Scratchpad abgelegt.
2. Vollständigkeit des Ordners: Alle Bildverweise in der Gliederung zeigen auf PNGs im images/-Unterordner, und diese Dateien existieren tatsächlich. Es gibt keine Verweise auf ../ oder absolute Pfade oder Pfade innerhalb des Repositorys. Umgekehrt gibt es keine unnötigen Dateien in images/, die nicht referenziert werden. Die Gesamtgröße des Ordners wird ebenfalls gemeldet.
3. Bildinhalte: Text, der etwas über ein Bild aussagt (z. B. „Bei XXX am größten“), wird durch tatsächliches Öffnen des Bildes überprüft.
4. Automatische Regelprüfung: Die Anzahl der ## stimmt mit der erwarteten Folienanzahl überein, jede Folie (außer den Gerüstfolien) hat einen „Typ“-Eintrag, es gibt keine Anweisungen für eine dritte Farbe. Die Länge der Kernaussagen (max. 30 Zeichen), ob die Aussage eine Schlussfolgerung ist, typische KI-Floskeln und inkonsistente Schreibweisen werden mit dem Prüfskript der Folien-Fähigkeit untersucht:

   python "${CLAUDE_SKILL_DIR}/../progress-report-deck/scripts/check_deck.py" --text "<Gliederung.md>" > check_doc.txt
   

   Die Ausgabe wird mit Read gelesen; alle WARN-Einträge werden korrigiert (sofern es sich nicht um eine fachlich korrekte Formulierung handelt). Wenn die letzte Zeile nicht DONE: … lautet, ist die Prüfung fehlgeschlagen – dies wird nicht als „0 Fehler“ gewertet. Falls das Skript nicht gefunden wird, wird dieser Punkt manuell überprüft.
5. Folienanzahl: Es wird gezählt, ob der Hauptteil innerhalb der geforderten Anzahl liegt.

6. Bericht erstatten

• Zeile 1: Angenommener Leser (z. B. „Angenommener Leser: Fähigkeit progress-report-deck (dahinter: Zuhörer des Laborseminars)“)
• Pfad und Inhalt des Ausgabeordners (1 MD-Datei + Anzahl der Bilder + Gesamtgröße)
• Gliederung (jede Folie in einer Zeile) und Inhalt der Backup-Folien
• Ergebnisse der Validierung (Anzahl der abgeglichenen Zahlen, Bildprüfung, Regelcheck)
• Punkte, die der Benutzer vor dem Vortrag wissen sollte: Nicht überprüfte Behauptungen, anfällige Zahlenwerte und warum, von wann und von welchem Code die verwendeten Ergebnisse stammen
• Nächster Schritt: Dem Benutzer mitteilen, dass die Folienerstellung durch Ausführen von progress-report-deck in diesem Ordner erfolgen kann (bei einem anderen Gerät nach dem Kopieren des gesamten Ordners). Der Transport (USB, Box/OneDrive, ZIP usw.) obliegt dem Benutzer.
• Es wird kein Commit durchgeführt (nur auf Wunsch).