jasonericsiegel/human-feedback

Menschliches Feedback (Human Feedback)

Verwandelt jede HTML-Seite in eine Seite, auf der der Benutzer Kommentare hinterlassen kann: links eine Gliederung, rechts neben den zugehörigen Textteilen die Notizen und einen Kopierknopf: Feedback kopieren (wenn leer), N Notizen kopieren (vor dem ersten Kopieren), danach N neue Notizen kopieren oder Erneut kopieren. Der Benutzer fügt den kopierten Text in den Chat ein; Sie wenden ihn an. Jeder Tastendruck wird im Browser des Benutzers gespeichert.

Diese Version sendet keine Nutzungszahlen.

• Claude Code und Codex können diese Datei beide laden. allowed-tools ist ein Claude-Code-Feld; Codex ignoriert es.
• $SKILL_DIR bezeichnet den Ordner, aus dem diese SKILL.md geladen wurde (z. B. ~/.claude/skills/human-feedback oder ~/.codex/skills/human-feedback); schreiben Sie diesen wörtlichen Pfad in Befehle. Jeder Shell-Aufruf erfolgt in einer neuen Shell.
• In einer Codex-Sandbox öffnet add_notes.py die Seite über show.py, das Chrome über AppleScript steuert und möglicherweise eine Zustimmung erfordert: Fragen Sie danach, anstatt Schritt 3 zu überspringen.
• Was die Seite des Benutzers in jedem Schritt zeigt (Ihr Cursor, die Eröffnung jeder Runde, Empfangen und Erledigt) steht in references/what-the-user-sees.md: Lesen Sie es, wenn der Benutzer fragt, wie sich die Seite verhält.

Wann Sie es verwenden sollten

• Sie bitten den Benutzer, von Ihnen erstellte Arbeiten (einen Bericht, einen Plan, einen Entwurf, einen Mockup, Optionen, vorgeschlagene Regeln) zu überprüfen, zu genehmigen oder auszuwählen, oder er bittet darum, sie zu überprüfen → platzieren Sie sie hier auf einer Seite, ohne dass darum gebeten werden muss.
• Die Arbeit liegt noch nicht als Seite vor → bauen Sie daraus einfaches HTML und behalten Sie die Originaldatei als Quelle.
• Eine eigenständige Frage, die keine Überprüfungsseite benötigt, bleibt im Chat.
• Beantworten Sie die Fragen des Benutzers in Notizen. Verwenden Sie --reply für die Notiz, die die Frage stellt, auch wenn sie gleichzeitig eine Änderung fordert. Platzieren Sie die Änderungen, längere Erklärungen und Ihre eigenen Überprüfungsfragen im relevanten Teil der Seite. Verwenden Sie --ask oder --again für eine Sprechblase mit Ihrer eigenen Frage nur, wenn der Benutzer danach fragt.
• Sobald eine Seite für die Notizen des Benutzers bereit ist, und in jeder späteren Runde: Wenn inbox-for-human in Ihrer Liste der verfügbaren Fähigkeiten ist (unter seinem Namen, mit oder ohne Plugin-Präfix), laden Sie es mit dem Skill-Tool (in Codex öffnen Sie die SKILL.md, auf die seine Fähigkeitenliste verweist) und stellen Sie die Seite in die Warteschlange. Wenn nicht, sagen Sie einmal: „Wurde ohne die inbox-for-human-Fähigkeit ausgeführt, die diese Seite auf einer Überprüfungsliste halten würde.“

Erste Verwendung

Vor der ersten Seite in einer Einrichtung führen Sie python3 "$SKILL_DIR/scripts/self_check.py" aus und geben seine Nachricht in einfachen Worten weiter. Führen Sie es nicht erneut aus, nachdem es bestanden wurde; das Skript merkt sich eine bestandene Prüfung. --force führt es bei Bedarf erneut aus.

Wenn Sie hier überhaupt keine Befehle ausführen können, versuchen Sie es nicht. Sagen Sie genau: „human-feedback kann in diesem Modus nicht funktionieren, weil ich hier nicht mit Dateien auf Ihrem Computer arbeiten kann. Öffnen Sie in der Claude-Desktop-App den Code-Tab und wählen Sie eine lokale Sitzung. Wechseln Sie in der ChatGPT-Desktop-App zu Codex und lassen Sie es auf Lokal.“

Exit 2 oder diese Nachricht bedeutet: Stopp – versuchen Sie nicht, eine Seite zu erstellen. Exit 1 gibt eine Datei aus, die der Benutzer selbst öffnen kann, um sie zu überprüfen.

1. Markieren Sie die Teile

Setzen Sie data-note auf jeden Teil, zu dem der Benutzer als Einheit einen Kommentar abgeben kann: eine Karte, einen Abschnitt, eine Option, eine Tabellenzeile. Bezeichnungen stammen von der ersten Überschrift des Teils, daher reicht ein nacktes data-note normalerweise aus. Ein Teil ohne Überschrift oder dessen Überschrift einer anderen wiederholt, erhält eine eigene Bezeichnung: data-note="Option B · Ruhig". Bezeichnungen müssen auf der Seite eindeutig sein.

Eine Seite, die ihre Teile aus einem eigenen Skript bezieht, erhält ebenfalls Notizen zu diesen, solange das Skript sie sofort zeichnet und nicht bei einem späteren Ereignis wie DOMContentLoaded oder einem Klick. Kopieren Sie sie nicht in das HTML; die Zählung in Schritt 2 umfasst nur die dort geschriebenen Teile.

Markieren Sie den Teil um eine lokale Seite, die in einem <iframe> angezeigt wird. Schritt 2 taggt die eingerahmte Seite, sodass ihre Worte Kommentar, Bearbeiten und Hervorheben anbieten. Die Überprüfungsseite speichert das Feedback und benennt die eingerahmte Quelle im kopierten Edit.

Markieren Sie niemals Text, den der Benutzer ausfüllen oder umschreiben soll, und bitten Sie den Benutzer niemals, die Seite zu bearbeiten: Der Benutzer schreibt jede Zeile selbst um, wenn er möchte, mit Bearbeiten im Pop-up, das ein Klick oder eine Auswahl aufruft (⌘Z macht eine Bearbeitung rückgängig). Stellen Sie stattdessen Fragen (Schritt 6).

Bauen Sie keine eigenen Kommentarfelder, Eingabefelder oder Kopierknöpfe. Die Ebene erledigt das alles.

Die Gliederung links ist bereits die Navigation der Seite: Sie listet jeden Teil auf, zeigt Abschnittsüberschriften außerhalb von Teilen als Beschriftungen an, markiert den aktuell sichtbaren Teil und springt zu einem Teil ohne die eigene obere Leiste der Seite. Bevor Sie der Seite eine eigene Navigation geben (Abschnitts-Tabs, ein Inhaltsverzeichnis, Sprunglinks, einen Schritt-Zähler mit Vorwärts und Zurück), beurteilen Sie, was für den Benutzer am einfachsten ist, damit der Benutzer nie zwei Wege für eine Sache hat:

• Es würde nur die Gliederung wiederholen → lassen Sie es weg. Benennen Sie die Teile und Abschnittsüberschriften so, wie es die Knöpfe getan hätten.
• Es tut etwas, das die Gliederung nicht kann (einen Hell/Dunkel-Schalter, einen Filter, Vor- und Zurück-Knöpfe, die durch die eine Seite Teil für Teil scrollen) → behalten Sie nur diesen Teil davon.
• Es zeigt Teile in Tabs oder anderen versteckten Panels → machen Sie es zu einer einzigen scrollbaren Seite. Der Benutzer hat nach Tabs gefragt → markieren Sie sie und schreiben Sie nichts weiter: eine role="tablist" aus <button role="tab" aria-controls="…">, die jeweils ein role="tabpanel" benennen, dann data-note-Teile innerhalb der Panels wie gewohnt. Die Ebene wechselt die Panels, zeichnet eine einfache fixierte Leiste, listet jeden Tab in der Gliederung als eine Ebene seiner Hierarchie, wo er auf der Seite sitzt, behält den offenen Tab über Neuladungen und Versionen hinweg, öffnet einen Tab für eine Gliederungszeile, einen Schritt oder einen #-Link hinein und hält einen Thread, bis sein Tab geöffnet wird. Eine Seite mit eigenem Tab-Skript behält es, und eine Tabliste mit einer class behält das eigene Styling der Seite.
• Jede Seite erhält ab der zweiten Runde Versionen (Schritt 5) → binden Sie die ← und → Tasten nicht; der Versionsschritt verwendet sie.

Einsteckpunkte für jede Seite, die die Ebene hostet (eine von einer anderen Fähigkeit oder von Hand erstellte Seite):

• data-note-Teile versorgen die Gliederung und die Notizenspalte wie oben.
• data-notes-layer wird auf <html> gesetzt, sobald die Ebene gezeichnet wurde, und fehlt auf einer Seite ohne sie. Eine Host-Seite verwendet es, um ihre eigene Gliederung oder eine Zeile auszublenden, die nur ohne die Ebene Sinn ergibt, damit der Benutzer nie zwei sieht: html[data-notes-layer] .its-outline { display: none; }. Nichts schaltet die Ebene aus, also bleibt die Markierung. Verlassen Sie sich auf nichts anderes, was die Ebene hinzufügt.

2. Notizen einschalten

python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude"

Es fügt ein Tag kurz vor </body> ein, gibt die Runden- und Teilanzahl aus und öffnet die Seite über show.py. Wiederholungen, --next-round und die Folgerunde einer neuen Version öffnen sie ebenfalls; --new-version allein, --received und --converged tun dies nicht. Wenn das Öffnen fehlschlägt, bleibt die Seite bereit und die Ausgabe gibt den Grund und den Befehl an, sie von Hand zu öffnen. In der ersten Runde wird auch ein kleiner Stil in den Kopf der Seite eingefügt, der die Seite versteckt hält, bis die Ebene sie zeichnet. Ein erneutes Ausführen ersetzt das Tag, also führen Sie es nach dem Umschreiben der Seite erneut aus. Eine Warnung über fehlende Teile oder eine doppelte Bezeichnung → beheben Sie die Markierungen und führen Sie es erneut aus.

• --hold: Bereiten Sie die Seite vor, ohne sie zu öffnen, während Sie sie erstellen oder überprüfen, oder wenn der Benutzer nur einen Link wünscht (Schritt 3).

• --pictures off: Deaktivieren Sie Bildanhänge für eine Seite, die mit anderen Personen geteilt wird, oder für eine öffentliche Version; spätere Läufe behalten die Einstellung.

• --agent: Ihr Name, wie die Leute ihn kennen. Claude Code gibt Claude weiter, Codex gibt Codex, jeder andere Agent seinen eigenen Produktnamen. Ein Cursor, der diesen Namen und Ihr Logo trägt, tut Ihren Teil auf ihrer Seite: Er tippt Ihre Nachrichten und klickt in den Zuständen ihrer Notizenleiste (Empfangen und Aktualisieren in Schritt 4, Erledigt in Schritt 8). Spätere Läufe behalten den Namen, also geben Sie ihn beim ersten Mal weiter.

• --helper "<name>" und --owns "<name>:[Teilbezeichnung]": Ein anderer Agent hat Teile der Seite erstellt (ein von Ihnen gesendeter Unteragent, Codex, jeder, der nicht Sie sind). Benennen Sie jeden Helfer einmal, wie die Leute ihn kennen, und jeden von ihm erstellten Teil mit --owns, die Bezeichnung wie in der Gliederung; beide wiederholen sich, maximal drei Helfer. Sie bleiben der Leiter (--agent). Auf der Seite tut der Cursor jedes Agenten nur das, was ihm gehört. Spätere Läufe behalten sie; ein Lauf mit einem der Flags ersetzt sie; eine neue Version beginnt ohne, also geben Sie sie in ihrer Folgerunde erneut weiter, wenn ihre Teile noch ihnen gehören. Sie haben alles selbst erstellt → lassen Sie beide weg.

  python3 "$SKILL_DIR/scripts/add_notes.py" <page.html> --agent "Claude" --helper "Codex" --owns "Codex:[Option B · Ruhig]"
  

• --workspace <verz>: Ihr Arbeitsbereich (der Projektordner, in dem Sie arbeiten). Jeder Lauf erstellt <verz>/human-feedback/attachments/, falls es fehlt, mit einer Markierungsdatei in human-feedback/; die Seite speichert die Bilder, die der Benutzer anhängt, dort, nachdem der Benutzer diesen human-feedback-Ordner einmal in Chrome ausgewählt hat, und die Eingabeaufforderungen der Seite nennen Sie („Im Arbeitsbereichsordner von Claude wählen Sie den human-feedback-Unterordner aus…“). Ohne: das Repository der Seite, andernfalls das Repository Ihres aktuellen Verzeichnisses, andernfalls das aktuelle Verzeichnis. Spätere Läufe behalten den Ordner, den das Tag benennt.

• Die Seite wird über http bereitgestellt (sie verwendet fetch, Module oder ../-Ressourcen) → fügen Sie --copy hinzu, das human-feedback.js neben der Seite platziert. Spätere Läufe, Umschreibungen und neue Versionen behalten es und geben dies an.

• Fügen Sie human-feedback.js niemals in die Seite ein oder lesen Sie es: Das Tag ist alles, was die Seite braucht.

• Platzieren Sie Fragen zur Seite in dem Teil, den sie betreffen (Schritt 6).

Erscheinungsbild

• Standardmäßig dem Systemerscheinungsbild folgen. Bieten Sie Auto, Hell und Dunkel an, wenn das zu überprüfende Material Prosa in den gemeinsamen Lesestilen ist oder wenn der Benutzer nach der Steuerung fragt. Lassen Sie es bei anderen Überprüfungen aus.
• Wenn Sie die Steuerung anbieten, verwenden Sie --appearance page, wenn die Lesespalte bereits beide Farbschemata hat und Sie beide überprüfen können. Verwenden Sie sie auf derselben Seite wieder. Verwenden Sie für eine Seite mit einem unabhängigen Thema, ohne getestetes Farbschema oder deren Erscheinungsbild Teil der Überprüfung ist, --appearance sidebars, um nur die Gliederung und Notizen umzuschalten. Behalten Sie Screenshots und Einbettungen bei.
• Im CSS der Lesespalte sind html[data-notes-layer="light"] und html[data-notes-layer="dark"] die expliziten Auswahlmöglichkeiten. Behalten Sie die System-Medienabfrage für Auto und wenn die Seite ohne die Ebene geöffnet wird. Die Auswahl des Benutzers bleibt für diese Überprüfung über mehrere Runden hinweg erhalten. Andere Überprüfungen beginnen mit Auto.
• Eine erneute Ausführung oder eine mit --new-version kopierte Version behält die Einstellung. Übergeben Sie --appearance off, um die Steuerung zu entfernen, oder übergeben Sie die gewünschte Einstellung erneut, wenn Sie die Datei von Grund auf neu erstellen.

3. Anzeigen

Für jede Art von Überprüfung in jeder Runde:

• Sobald die Überprüfung bereit ist, öffnen Sie sie in jeder Runde im Browser des Benutzers. Der Öffner verwendet den vorhandenen Tab in Chrome wieder, wenn er eine frühere Runde dort findet. Verwenden Sie --hold, während Sie die Seite erstellen oder überprüfen, oder wenn der Benutzer explizit nur nach einem Link fragt.
• Für eine lokale Überprüfung beenden Sie mit add_notes.py ohne --hold. Neue Überprüfungen in einem dedizierten Ordner, dessen Ressourcen in diesem Ordner leben, verwenden für alle Runden eine lokale Webadresse, sodass der Browser seinen Seitenzoom und seine Notizen behält. Behalten Sie die Runden und ihre Ressourcen in diesem Ordner oder seinen Unterordnern und verwenden Sie relative Ressourcenpfade. Verlinken Sie die Überprüfungsadresse, die der Öffner ausgibt.
• Für eine bereits über HTTP bereitgestellte Seite bereiten Sie mit --hold --copy vor und führen Sie show.py <lokale page.html> --preview-url <HTTP-URL der neuen Runde> aus. Behalten Sie denselben Vorschauserver über die Runden hinweg, damit der Öffner den vorhandenen Tab finden und der Browser die Notizen des Benutzers behalten kann.
• Fügen Sie den Link zur Seite in jeder Runde in Ihre Antwort ein. Verwenden Sie das Link-Format Ihres Projekts mit dem Ergebnis des Öffners, um anzugeben, wo sich die Seite befindet. Wenn der Öffner fehlschlägt oder angibt, dass die Seite geschlossen bleibt, sagen Sie dies und geben Sie den Link an.
• Eine Seite, deren frühere Runden oder Versionen der Benutzer über file:// geöffnet hat → zeigen Sie sie weiterhin über file:// an (show.py auf ihrem Pfad) und geben Sie keinen Localhost-Link, selbst wenn das Projekt einen verlangt: Der Browser behält die Antworten des Benutzers pro Adresse, daher zeigt eine Localhost-Kopie keine davon und öffnet Threads, die sie geschlossen haben, erneut. Sagen Sie in der Antwort, warum es keinen Link gibt.

Tun Sie dies nur, sobald die Seite für ihre Notizen bereit ist.

Führen Sie add_notes.py ohne --hold aus, sobald die Seite für ihre Notizen bereit ist. Vervollständigen Sie zuerst den Seiteninhalt und markieren Sie jeden Teil. Übergeben Sie alle erledigten Markierungen und alle vom Benutzer angeforderten Sprechblasen in diesem Lauf (Schritt 5 Folgerunde für eine neue Version).

Eine Korrektur, von der Sie dem Benutzer mitgeteilt haben, dass sie unterwegs ist, hält auch die nächste Version zurück. Zeigen Sie sie erst, wenn diese Korrektur live ist.

Für eine Überprüfung bereiten Sie sie mit --hold vor, überprüfen Sie sie dann selbst (oder lassen Sie einen Unteragenten einen Screenshot davon machen) bei eingeschalteter Notizenebene, da die Ebene die Seite schmaler macht, und beheben Sie, was Sie finden. Ihre Nachrichten (Fragen, Antworten) erscheinen nur, wenn der Tab den Fokus hat, und ein kopfloser Browser fokussiert ihn nie, es sei denn, die Fokus-Emulation ist eingeschaltet (tests/harness.mjs schaltet sie ein). Ohne diese überprüfen Sie die Nachrichten stattdessen in den Daten des Tags, und die Seite selbst bleibt hinter ihrem Öffnungsbildschirm leer: Fotografieren Sie sie mit shoot_page.py aus reading-page-formats, das eine nackte Kopie ohne das Tag und seinen Halte-Stil aufnimmt und dann löscht. Diese nackte Kopie füllt das gesamte Fenster, aber auf ihrem Bildschirm nehmen die Notizenspalten etwa 375px auf jeder Seite ein (gemessen bei 2560 Breite, 2026-11-01). Fotografieren Sie sie daher auch mit dieser schmaleren Breite und beheben Sie jeglichen Umbruch oder Überlauf, bevor Sie sie zeigen. Eine nackte Kopie kann nicht zeigen, dass die Spalten die Seite abdecken. Laden Sie daher auch die gehaltene Seite mit eingeschalteter Ebene und überprüfen Sie, ob document.querySelector('h1').getBoundingClientRect().left rechts vom Rand der Gliederung liegt; das erste Textelement reicht auf einer Seite ohne h1. Öffnen Sie die Seite erst dann mit dem obigen lokalen oder HTTP-Befehl. Teilen Sie dem Benutzer mit, dass sie für seine Notizen bereit ist, wo sie ist (die Zeile, die der Öffner ausgibt), und den kopierten Text einzufügen, den die Kopierfunktion liefert. Wenn Sie Fragen gestellt oder Antworten hinterlassen haben, geben Sie an, wie viele auf der Seite warten.

Sobald eine Seite angezeigt wird, beschränken Sie den Chat auf die Bereitschaftszeile, den Link und alles, was das Öffnen der Seite oder eine erforderliche Zeile einer anderen Fähigkeit verhindert hat. Platzieren Sie Änderungen, Erkenntnisse, Quellen, Einschränkungen, Überprüfungen und Fragen in den Teilen, die sie betreffen. Verwenden Sie die eigenen „Weitere Informationen“ der Seite für Quellen und Details, wenn sie eine solche hat.

Eine von Ihnen eingerahmte Seite trägt ebenfalls den Rahmentag, sodass sie beim eigenständigen Öffnen die Notizenspalten zeigt und zusammengedrückt wird. Eine Überprüfung meldet dann falsche Defekte. Überprüfen Sie sie stattdessen anhand einer nackten Kopie in Ihrem Notizblock: Entfernen Sie das Halte-Styling, das im Tag enthalten ist, laden Sie es in einem Browser, fotografieren Sie es in voller Breite und beheben Sie Probleme. Überprüfen Sie es auch in voller Breite, mit dem Tag und mit der Ebene, um sicherzustellen, dass die Spalten die Seite richtig abdecken. Öffnen Sie die Seite dann mit dem lokalen oder HTTP-Befehl oben. Teilen Sie dem Benutzer mit, dass sie für seine Notizen bereit ist, wo sie ist, und den kopierten Text einzufügen.

4. Empfangen

5. Versionen

6. Fragen

7. Konvergenz

8. Erledigt

Referenzen

add_notes.py und show.py werden vom Skill-Mechanismus im scripts/-Ordner gefunden, der sich neben dieser Datei befindet. Alle anderen referenzierten Dateien sind ebenfalls vorhanden.

Lesen Sie references/what-the-user-sees.md für einen detaillierten Überblick über das Verhalten der Seite aus Benutzersicht.

tests/harness.mjs ist ein Test-Harnisch, der die Fokus-Emulation für kopfloses Testen bereitstellt.