CommunityCodierung & Entwicklunggithub.com

sheets-to-playbook

Verwandle einen Ordner mit Fotos von ausgefüllten Papier-Arbeitsblättern eines Workshops (sowie ggf. Fotos von Commitment-Karten-Stubs und optionalen Sprachnotizen) in einen Entwurf einer Playbook-Website, überprüfe jede Zeile anhand der Fotos und veröffentliche sie.

Was ist sheets-to-playbook?

Diese Fähigkeit ist ein spezialisierter Workflow zur Erstellung eines Playbook-Ergebnis-Websites aus eingescannten oder fotografierten Papier-Arbeitsblättern, wie sie in Workshops oder Community-Sessions verwendet werden. Sie ist für Entwickler-Tools wie Claude Code, Cursor oder Codex konzipiert und automatisiert den gesamten Prozess von der Fotoaufbereitung, Transkription, Verifikation bis hin zur Veröffentlichung. Besonders nützlich in zeitkritischen Szenarien (z.B. direkt nach einem Workshop), da sie strikt darauf achtet, keine Informationen zu erfinden: Jede Zeile auf der finalen Website muss auf ein Foto oder eine Sprachnotiz zurückverfolgbar sein. Die Fähigkeit unterstützt mehrere Plattformen (CLI-basiert) und nutzt lokale Whisper-Spracherkennung zur Transkription von Sprachnotizen. Sie bietet Werkzeuge zur Kollisionserkennung (zwei Tabellen auf einem Foto), zur Markierung unscharfer oder mehrdeutiger Stellen und zur Überprüfung der Vollständigkeit. Der Workflow ist in sechs klare Phasen unterteilt (Vorbereitung, Beschriftung, Transkription, Playbook-Schreiben, Verifikation/Review, Veröffentlichung) und endet mit einer statischen HTML-Website, die überall bereitgestellt werden kann.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Chris-Keene/sheets-to-playbook/tree/HEAD/.claude/skills/sheets-to-playbook

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Sheets to Playbook

Repo: Der Ordner, der ingest/ingest.py enthält (das aktuelle Projekt, falls Claude Code im Klon geöffnet wurde). Alle folgenden Pfade sind relativ dazu. Lies ingest/RAW_FORMAT.md vor Phase 3: Es enthält das Transkriptionsformat und die Regeln zum Schreiben des Playbooks.

Das Ziel ist Geschwindigkeit am Tag ohne etwas zu erfinden. Jede Zeile auf der Website muss auf ein Foto oder eine Sprachnotiz zurückzuführen sein; ingest.py verify setzt dies durch.

Sage dem Benutzer in ein oder zwei Zeilen, was du in jeder Phase tust. Die unten angegebenen Phasen-Zeiten sind grobe Richtwerte für etwa ein Dutzend Tische.

Vor dem Tag sollte playbook.config.json die Organisatoren nennen und die Webadresse des Playbooks angeben (der QR-Code auf der Commitment-Karte zeigt dorthin). Wenn es noch die neutralen Standardwerte enthält, sage dies, aber fahre fort: Die Einstellungen ändern nur Namen und Farben, nie den Inhalt. --config <datei> bei verify, draft und publish wählt eine andere Einstellungsdatei aus.

1. Vorbereiten (1 bis 2 Minuten)

python3 ingest/ingest.py prepare "<ordner>"
python3 ingest/ingest.py transcribe      # nur, wenn der Ordner Sprachnotizen enthält; im Hintergrund ausführen

prepare erstellt einen neuen Durchlauf unter runs/ (und setzt runs/latest darauf): Fotos aufrecht gedreht, HEIC konvertiert, ein Schärfewert pro Foto, 2×2-Kacheln für genaues Lesen, Kontaktblätter in contact/ und Sprachnotizen in 16 kHz WAV konvertiert. transcribe verwendet lokales Whisper (small.en, offline nach dem ersten Herunterladen) und errät die Tabelle jeder Notiz anhand des Anfangs "Tabelle sieben…".

Ein zweiter Stapel (weitere Fotos oder die Karten, nachdem die erste Hälfte läuft): python3 ingest/ingest.py prepare "<ordner>" --into <durchlauf> fügt sie zum selben Durchlauf hinzu. Neue IDs setzen die Nummerierung fort (P022…), Labels und Rohdateien bleiben erhalten, und bereits im Durchlauf vorhandene Dateien werden übersprungen. Beschrifte dann nur die neuen IDs.

2. Beschriften und Abdeckung prüfen (etwa 5 Minuten; zuerst erledigen, das ist zeitkritisch)

Sieh dir jedes Kontaktblatt (contact/sheet-*.jpg) an und, wenn eine Vorschau unklar ist, das Foto in view/. Schreibe labels.json im Durchlauf-Ordner:

{"photos": {"P001": {"table": 7, "sheet": "S2"}, "P014": {"kind": "stubs"}, "P020": {"kind": "other", "note": "Foto des Raums"}},
 "audio":  {"A01": {"table": 7, "by": "speech"}}}
  • Jedes Blatt trägt einen gedruckten Code in der unteren Ecke (S1, S2, S3, SS) und gedruckte Überschriften; die Tischnummer ist handschriftlich vom Tischleiter eingetragen, oben rechts im Kreis und neben dem Code (S2 · Tisch 7). Die Standard-Überschriften des Kits: S1 "Wo hakt es bei der Unterstützung?", S2 "Was hat geholfen oder nicht?", S3 "Was könnten Leute jetzt ausprobieren, und wie bleibt es hängen?", SS das Seitenblatt "Was Gutes gehört? Schreib es hier auf." (Zitate · Fragen · Ressourcen). Wenn die Organisatoren die Fragen geändert haben, richte dich nach dem gedruckten Code. Wenn der Kreis und die Ecke unterschiedliche Angaben machen, entscheiden Stiftfarbe und Inhalt: Prüfe die anderen Blätter des Tisches.
  • Behalte alle Audio-Labels, die transcribe bereits eingefügt hat, nachdem du sie anhand der ersten Zeile des Transkripts überprüft hast.
  • Zwei verschiedene Blätter mit demselben Code und derselben Tischnummer (status listet alle Blätter mit mehr als einem Foto auf: diese prüfen): Wenn die Länder und Inhalte sich überschneiden, handelt es sich um einen Tisch, der zwei Exemplare verwendet hat; beschrifte beide mit der Nummer und der Leser transkribiert beide. Wenn es eindeutig zwei Tische sind, gib dem zweiten eine freie Nummer ab 91, füge "note": "schrieb 22; zweiter Tisch" hinzu und informiere den Benutzer. Beide Tische können "der zweite" sein: Wähle einen aus und beschreibe beide in den Notizen (Branche, Stiftfarbe), damit die Prüfung sie unterscheiden kann.
  • Eine Nahaufnahme ohne sichtbare Tischnummer (nur das Strichkästchen, z.B.): Beschrifte sie mit dem passenden Blatt und füge "note": "Tisch abgeleitet aus <was passte>" hinzu.
  • Zwei Blätter auf einem Foto (nebeneinander geheftet): Beschrifte es mit "sheet": ["S2", "S3"], sodass status es für beide zählt, und erwähne dies in einer note, damit der Leser weiß, welche Hälfte welche ist.
  • prepare kann ein Foto, das im Rahmen auf dem Kopf steht, nicht drehen (es gibt kein Rotations-Flag zum Auslesen). Leser kommen damit zurecht, aber erwähne es in einer note. Kartenfotos haben einen niedrigeren Schärfewert als Blätter (einfache Karte, dünner Stift), also überprüfe eine UNSCHARFE? Karte in view/, bevor du um eine erneute Aufnahme bittest.

Führe dann python3 ingest/ingest.py status aus (füge --tables <n> hinzu, wenn es nicht 12 Tische waren) und informiere den Benutzer sofort über fehlende oder unscharfe Blätter. Die Kontaktblätter kennzeichnen auch NIEDRIGE AUFLÖSUNG (über einen Messenger weitergeleitet: in Ordnung, wenn die Schrift groß ist) und DUNKEL (meist gut lesbar): Erwähne sie, aber sie erfordern keine erneuten Aufnahmen. Idealerweise findet diese Prüfung statt, während die Blätter noch an der Wand hängen und erneut fotografiert werden können.

3. Jeden Tisch transkribieren (parallel, etwa 5 bis 10 Minuten)

Starte einen Unter-Agenten pro Tisch (Agent-Tool, general-purpose, im Hintergrund, alle in einer Nachricht), sowie einen für Karten-Stubs, falls vorhanden. Stufe das Modell nicht herab: Die Handschrifterkennung ist hier entscheidend. Jeder Prompt muss eigenständig sein und enthalten:

  • Den absoluten Repo-Pfad, den Durchlauf-Ordner, die Tischnummer, seine Foto-IDs (view/<id>.jpg und die in manifest.json aufgeführten Kacheln) und ggf. den Pfad zum Sprachnotiz-Transkript.
  • "Lies ingest/RAW_FORMAT.md, Phase 1, und befolge es genau. Schreibe raw/T<nn>.json im Durchlauf-Ordner, führe dann python3 ingest/ingest.py verify --run <durchlauf> aus und behebe jeden Fehler, den es zu deiner Datei meldet. Antworte mit einer kurzen Zusammenfassung: Einträge pro Blatt, jeder unclear-Eintrag und jedes durchgestrichene Wort, das du ausgelassen hast."
  • Für Stubs: Schreibe raw/commitments.json wie am Ende von Phase 1 beschrieben, inklusive der optionalen Zeilen für Name und Organisation der Karte genau wie geschrieben, und befolge die dortigen Kartenregeln (nicht zerrissene Karten, Abzeichnungen, eine Karte auf zwei Fotos).

Während sie laufen, lies selbst die Sprachnotiz-Transkripte (falls vorhanden), um den Raum vor dem Schreiben zu kennen.

4. Das Playbook schreiben (etwa 10 bis 15 Minuten)

Befolge Phase 2 von RAW_FORMAT.md. Schreibe <durchlauf>/session.json mit meta.status: "draft". Starte meta aus examples/session-template.json und fülle die eigenen Details des Events (Event-Name, Datum, Veranstaltungsort) basierend auf den Angaben des Benutzers ein; setze people auf die tatsächliche Teilnehmerzahl, falls bekannt. Rate nie: Lasse ein Feld so, wie es in der Vorlage ist, und liste es für den Benutzer auf.

5. Verifizieren, korrigieren, das Überprüfungspaket erstellen

python3 ingest/ingest.py verify --links
python3 ingest/ingest.py draft            # <durchlauf>/playbook-draft.html: gestrichelte Kästchen = Lücken, Tags = Quellen
python3 ingest/ingest.py review           # <durchlauf>/review.html: jeder Eintrag neben seinen Fotos

Behebe jeden Fehler (eine nicht zurückverfolgbare Zeile, ein abweichendes Zitat, einen verbliebenen Namen) und führe es erneut aus, bis verify besteht. Warnungen sind für die menschliche Überprüfung: Melde sie, überdecke sie nicht.

Gib dem Benutzer dann die Überprüfungszusammenfassung: die Herausforderungen und welche Tabellen zusammengeführt wurden, jede unclear-Lesung mit ihrer Foto-ID, jedes durchgestrichene Wort, das ein Leser ausgelassen hat, ungenutzte Rohdaten-Einträge, Link-Probleme und alles, bei dem du dir nicht sicher warst, wie du es gruppieren sollst. review.html zeigt die Notizen jedes Lesers und die "Wer ist an diesem Tisch?"-Auszählung unter jedem Tisch. Öffne review.html und playbook-draft.html für sie.

Viele unsichere Wörter? Die Überprüfungs-App ist schneller als das vollständige Lesen von review.html von oben nach unten: python3 tools/review/make_review.py --run <durchlauf> erstellt <durchlauf>/review/index.html, eine Karte pro unsicherer Lesung mit einer Nahaufnahme der Handschrift. Der Benutzer bestätigt oder korrigiert jede, speichert eine Entscheidungsdatei, und python3 tools/review/apply_review.py --run <durchlauf> <entscheidungen.json> schreibt die Lesungen zurück in die Rohdateien und session.json. Führe danach verify und draft erneut aus. Fragen, die kein unsicheres Wort betreffen (ein Häkchen, das ein Durchstreichen sein könnte, ob zwei Tische zusammengeführt werden sollen, ob eine Ressource benannt werden soll), kommen in <durchlauf>/review/extra.json als Prüfungen und Entscheidungen bevor du die App baust; apply_review.py listet die Antworten in <durchlauf>/review/to-action.md auf, damit du darauf reagieren kannst. Siehe tools/review/README.md.

6. Veröffentlichen (nachdem ein Mensch den Entwurf geprüft hat)

Wende die Korrekturen der Prüfer auf session.json an, setze meta.status auf "final", dann:

python3 ingest/ingest.py publish --links  # weigert sich, wenn etwas nicht zurückverfolgbar oder ein Abschnitt leer ist

Dies schreibt data/session.json und playbook/index.html. Der Ordner playbook/ ist eine statische Website: Sie irgendwo bereitzustellen ist ein separater Schritt, frage also zuerst. Jeder Link auf der Seite wird im Skript verarbeitet, sodass sie auch direkt von der Festplatte geöffnet funktioniert.

Niemals

  • Inhalte aus Allgemeinwissen hinzufügen, selbst "hilfreichen" Kontext. Leer ist besser als erfunden.
  • Ein Wort stillschweigend raten: Verwende [?wort] oder [unleserlich] und liste es auf.
  • Den Namen einer Person oder ihres Arbeitgebers auf der veröffentlichten Seite nennen, außer dem eigenen Namen und der Organisation einer Commitment-Karte, die die Person selbst geschrieben hat (verify prüft diese anhand der Karte).
  • Ohne bestandenen verify-Durchlauf und menschliche Durchsicht des Entwurfs veröffentlichen.

Danach

Fotos und Sprachnotizen können Namen und Gesichter enthalten. Sobald das Playbook final ist, erinnere den Benutzer daran, runs/*/audio, die Quellfotos und Sprachnotizen sowie alles andere, was die Organisatoren vereinbart haben nicht zu behalten, zu löschen.

Verwandte Skills