davidjurgens/potato-skill

Potato-Annotationsaufgaben

Eine Potato-Aufgabe besteht aus einer YAML-Konfiguration und einer Datendatei. Das Erstellen einer solchen Aufgabe umfasst drei Schritte: Entscheiden, was und wie abgefragt werden soll, es korrekt aufschreiben und es solange ausführen, bis jemand vom Anmeldebildschirm bis zum Ende der Studie beobachtet wurde. Der zweite Schritt ist derjenige, der von einem Validator begleitet wird, weshalb es verlockend ist, genau dort zu beginnen und aufzuhören. Es ist jedoch der Schritt, der am wenigsten wahrscheinlich der Ort ist, an dem die Studie scheitert.

Lesen Sie AGENTS.md im Projektstammverzeichnis, falls vorhanden – es enthält Projektspezifische Konventionen, die über diesen Anweisungen stehen.

Wenn Sie ohne Aufgabenbeschreibung aufgerufen wurden

Jemand hat /potato-tasks eingegeben und es gibt keine Aufgabenbeschreibung im Gespräch. Beginnen Sie nicht mit dem Bauen und eröffnen Sie das Gespräch nicht mit „Was möchten Sie erstellen?“ – ein Forscher, der Potato nicht verwendet hat, kann das nicht sinnvoll beantworten.

Fragen Sie nach einem Satz, schlagen Sie ein Design daraus vor und bestätigen Sie nur das, was Sie erraten mussten. references/interviewing.md ist die Fragenbank: die einleitende Frage, der Vorschlag in vier Zeilen, dann zwei Runden mit Multiple-Choice-Fragen zu Modalität, Einheit, Antwortformat, Annotatoren pro Element, Qualitätskontrolle, Exportziel und wer sich anmelden darf – dann eine dritte Runde, die die sieben Fähigkeitscluster als Menü anbietet und nur das vertieft, was angekreuzt wird.

Zwei Dinge sind besonders wichtig. Fragen Sie jedes Mal nach der Modalität der Daten: Sie bestimmt die Darstellung, die Schemafamilie und den pro-Familie-Schlüssel, der angibt, wo die Medien leben. Ein Fehler hier bleibt still. Und drängen Sie keine Phasen auf – consent, training und prestudy sind Protokollentscheidungen; die meisten Aufgaben benötigen keine, und ein Forscher, der eine benötigt, weiß, dass er sie braucht.

Die grundsätzliche Regel, mit getroffenen Annahmen zu bauen, anstatt zu warten, gilt weiterhin – sie greift, sobald das Interview eine Grundlage für die Annahmen bietet. Wenn überhaupt kein Kontext vorhanden ist, ist das Stellen von vier strukturierten Fragen für den Forscher schneller als jede Vermutung, die Sie anstellen könnten.

Potato installieren

Der Großteil dieser Fähigkeit steuert das potato-Kommando und importiert die Registries von Potato. Beides funktioniert nicht, wenn das Paket nicht in der Umgebung installiert ist, in der Sie die Befehle ausführen.

potato --version || pip install potato-annotation

Der Browser-Durchlauf in scripts/walk_task.py benötigt zusätzlich Playwright: pip install 'potato-annotation[preview]' && playwright install chromium.

Die Skripte dieser Fähigkeit

Sieben der folgenden Verfahren sind Skripte und keine Anweisungen, da sie zu lang sind, um sie von Hand korrekt auszuführen, und sie werden immer wieder verwendet werden. Sie befinden sich neben dieser Datei im Verzeichnis scripts/.

Skript	Was es tut
boot_and_check.py config.yaml -p 8000	Startet, wartet auf einen 200-Status und benennt jedes Feature, das konfiguriert ist, aber nichts geladen hat
walk_task.py --url … --config … --task-dir .	Registriert einen Annotator, durchläuft die gesamte Studie und prüft, ob die Antworten in user_state.json gelandet sind
estimate_effort.py config.yaml --rate 15	Elemente, benötigte Annotatoren, Minuten pro Element, Gesamtstunden und Kosten
find_design.py --type span --with-instructions	Durchsucht 440 veröffentlichte Aufgabendesigns in der Potato-Showcase
handover.py config.yaml --confirm	Entfernt die während des Testens erstellten Konten und schreibt RUNNING.md
check_ui.py --url … --config config.yaml	Rendert jede Seite und meldet Schemata unterhalb der Bildlaufleiste, leere Medien, leere Auswahlkacheln, Schemata ohne Steuerelemente zur Beantwortung, leere Antworten, was die Widgets als Fehler anzeigen, Tastaturkonflikte und nie angezeigte Schemata. --phase poststudy misst eine Seite, die der Durchlauf nicht erreichen kann
study_status.py --url … --task-dir .	Fortschritt, Tempo pro Annotator, Übereinstimmung und was bei einer laufenden Studie falsch aussieht

Jedes Skript versteht --help, und boot_and_check, walk_task, check_ui und study_status akzeptieren --json, wenn Sie auf das Ergebnis reagieren möchten, anstatt es zu lesen.

Die Schleife

potato validate config.yaml --strict               # Struktur und unbekannte Schlüssel
potato preview config.yaml                         # Was das Formular deklariert
potato preview config.yaml --screenshot out.png    # Eine Seite rendern, Browser-Fehler melden
nohup potato start config.yaml -p 8000 > server.log 2>&1 &    # Starten und Log lesen

Die ersten drei Befehle kehren schnell zurück. Der vierte kehrt nie zurück – führen Sie ihn im Hintergrund aus, prüfen Sie mit curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/ auf einen 200-Status und lesen Sie server.log.

potato --help listet diese unter anderen Befehlen auf, unterhalb der start-Flags. Jeder Befehl hat seine eigene Grammatik, daher sind potato validate --help und potato preview --help die Quellen für ihre Optionen.

Jeder Schritt fängt eine andere Fehlerklasse ab

Schritt	Fängt ein	Blind für
validate --strict	Fehlende erforderliche Schlüssel, falsche Typen, unbekannte Schlüssel auf 1–2 Ebenen	Seitendateien, Phasentypen, alles innerhalb eines Schemaeintrags
preview	Welche Schemata und Tastenkombinationen die Konfiguration deklariert	Ob etwas davon gerendert wird
preview --screenshot	Unbehandelte Ausnahmen, console.error, fehlgeschlagene Anfragen auf einer Seite	Alles unter 900 Pixel, jedes bedingte Widget, jede andere Phase
Starten + Log lesen	Formate der Seitendateien, Phasenzusammenstellung, Subsysteminitialisierung	Wie es aussieht
Im Browser ausführen	Die eigentliche Studie	–

Das Überspringen der letzten beiden Schritte führt dazu, dass eine Aufgabe ausgeliefert wird, die validiert, saubere Screenshots liefert, aber ihre Trainingsphase, ihre Aufmerksamkeitsprüfungen und ein Drittel ihrer Elemente verliert.

Frühzeitig starten

Das Startprotokoll ist der eigentliche Validator. Es ist die einzige Stelle, die meldet, ob die Teile der Konfiguration, die validate nie öffnet, tatsächlich funktioniert haben:

grep -E "ERROR|Traceback|Loaded [0-9]+|phase|missing required" server.log

Ein gesunder Start mit einer Aufgabe, die Training und Aufmerksamkeitsprüfungen umfasst, zeigt Loaded 3 training instances und Loaded 2 attention check items und sagt nichts über Phasen aus. Alles andere ist ein Feature, das konfiguriert und deaktiviert ist.

Starten Sie, sobald die Konfiguration geparst ist – bevor die Benutzeroberfläche fertig ist, bevor die Anweisungen geschrieben sind. running-a-task.md enthält das Rezept für den Hintergrundbetrieb, die Bereitschaftsprüfung, die Logzeilentabelle und welche generierten Dateien nach einer Bearbeitung gelöscht werden müssen.

Drei stille Fehlermodi

Aktiviert bedeutet nicht aktiv. attention_checks.enabled: true mit einer fehlerhaften Elementedatei protokolliert eine Warnung, dann Loaded 0 attention check items, dann läuft die gesamte Studie ohne Qualitätskontrolle. Prüfen Sie die Anzahl, nicht die Konfiguration.

--strict erreicht nicht alles. Es prüft die oberste Ebene und eine Ebene in die meisten Blöcke hinein. Es prüft nicht innerhalb von phases, surveyflow, quality_control, crowdsourcing, publish, automatic_assignment, ui, ui_config oder innerhalb eines Eintrags von annotation_schemes oder instance_display.fields. key_binding anstelle von key_value validiert sauber und tut nichts. Gleiches gilt für einen Phasen-type:, der nicht existiert.

Der Screenshot ist der Viewport, nicht die Seite. --screenshot schreibt 1280×900. Bei einer Aufgabe mit einem Anweisungsbanner ist das der Banner und die Hälfte des Elements – keine der Fragen. Der Ratschlag, „Schauen Sie sich das PNG an und prüfen Sie, ob die Schaltfläche „Weiter“ über der Falz liegt“, kann mit diesem Tool allein nicht befolgt werden. Führen Sie einen Browser aus und erstellen Sie einen Screenshot mit full_page=True.

Herausfinden, was sie bereits haben

Eine Aufgabenbeschreibung plus eine Datendatei ist der häufigste Fall, aber nicht der einzige. Fragen Sie vier Dinge, bevor Sie etwas entwerfen, denn dahinter steckt jeweils ein Befehl, und es ist teuer, die Antwort erst zu entdecken, nachdem die Konfiguration geschrieben ist:

Frage	Grund
In welchem Format liegen die Daten vor und wo sind die Medien?	Transkripte und Gesprächskorpora haben ihre eigenen Konverter
Haben Sie bereits Annotationen?	potato import liest vierzehn Formate und schreibt ein ausführbares Projekt
Was muss am Ende herauskommen?	Neunundzwanzig Exportformate. Prüfen Sie das Zielformat bevor jemand annotiert
Wer führt die Studie nach der Übergabe aus und wie lange?	Entscheidet über Hosting, Logins und die Whitelist

potato import --list-formats                      # coco, cvat, labelme, labelbox, via, …
potato transcripts interviews/ -r --dry-run       # whisper, srt, vtt, textgrid, eaf, …
potato convokit reddit-corpus-small --unit conversation --emit-config

references/importing-existing-work.md behandelt alle drei, einschließlich der wichtigsten Entscheidung: ob importierte Annotationen Voranmerkungen sind, die ein Mensch korrigiert, oder --seed-user-Arbeit, die das Element als erledigt markiert.

Unvollständige Aufgabenbeschreibungen

Lesen Sie references/asking-the-experimenter.md, bevor Sie die Konfiguration schreiben. Entscheiden Sie selbst, wenn ein Fehler billig ist; fragen Sie, wenn er teuer, irreversibel oder nicht Ihre Entscheidung ist – die Annotations einheit, das Annotatorenbudget, der Einwilligungstext und alles, was identifizierbare Personen betrifft.

Warten Sie niemals auf eine Antwort. Bauen Sie mit getroffenen Annahmen, schreiben Sie die Fragen in QUESTIONS.md und liefern Sie etwas Lauffähiges. Sagen Sie, welche Annahme Sie zuerst überdenken würden.

Suchen Sie nach dem Feature, bevor Sie eines selbst bauen

Potato bietet mehr integrierte Funktionen, als eine Konfigurationsreferenz vermuten lässt. Der teure Fehler ist nicht ein erfundener Typname – die Validierung fängt das ab. Es ist das händische Zusammenbauen von etwas, das Potato bereits kann.

references/modes-and-subsystems.md ist die Routingtabelle von dem, was ein Forscher gesagt hat, zu dem Block, der es umsetzt: QDA und Codebücher, Einzelmodus, Räume, Adjudikation, Überprüfungsworkflow, Sitzungen, Pocket, aktives Lernen, Richter, Crowdsourcing, Veröffentlichung, Telemetrie. Prüfen Sie es, bevor Sie ein Schema schreiben, das wie ein Workaround klingt.

Es beginnt mit den sieben Clustern – Material, die Antwort, Einheit, Personen, Vertrauen, maschinelle Hilfe, Ausgabe – die dieselbe Karte ist, die das Interview als Menü anbietet. Gehen Sie es als Checkliste gegen die Aufgabenbeschreibung durch: Die Cluster, die eine Aufgabenbeschreibung nie erwähnt, sind die, bei denen ein Forscher am wahrscheinlichsten etwas verpasst, das er wollen würde. Heben Sie höchstens zwei davon hervor, und nur dort, wo sie relevant sind; der Rest kommt in QUESTIONS.md.

Der Cluster, den Forscher am zuverlässigsten übersehen, ist die Antwort. Sie fragen nach radio und likert und hören auf, und soft_label, range_slider, semantic_differential, constant_sum und confidence werden nie erreicht.

Entwerfen

references/designing-a-task.md behandelt die sieben Entscheidungen hinter jeder Aufgabe: die Einheit, die Fragen, das Antwortformat, Annotatoren pro Element, Elementreihenfolge, Qualitätskontrolle und die Phasen davor und danach.

Die Routingtabelle deckt die häufigen Anfragen ab und hört dort auf. Elf Typen werden nirgendwo außer in der generierten Referenz genannt, daher werden sie nie erreicht: multirate (zehn Bewertungen auf einer Skala, nicht zehn likert-Schemata), hierarchical_multiselect (eine Taxonomie, ausgeblendet, mit Suche), select, soft_label (eine Verteilung statt einer erzwungenen Wahl), range_slider, semantic_differential, conjoint, card_sort, extractive_qa, multi_document_event, code_review. Jeder hat ein funktionierendes Beispiel und eine Zeile in designing-a-task.md.

Zwei, die leicht falsch verstanden werden und teuer spät zu entdecken sind:

• Das Antwortformat entscheidet über die Übereinstimmungsmetrik. Potato wählt sie basierend auf der Schemaart. Eine 1–5-Bewertung, die als radio gespeichert wird, wird als ungeordnet bewertet, daher zählen „1 vs 2“ und „1 vs 5“ gleich. Das ist ein Messfehler, kein kosmetischer. Tabelle in references/assignment-and-agreement.md.
• num_annotators_per_item setzt das Ziel, max_annotations_per_user bestimmt, was eine Person tatsächlich sieht. Ohne Angabe ist die Obergrenze die Anzahl der Elemente, also wird jedem der gesamte Korpus angeboten. Wenn Sie sie darunter setzen, hören die Annotatoren einfach früh auf, ohne ersichtlichen Grund. automatic_assignment.instance_per_annotator sieht nach dem Schlüssel dafür aus, wird aber überhaupt nicht gelesen.

Der Designbericht und die Kosten

Zwei Dateien neben der Konfiguration, die die Konfiguration nicht enthalten kann:

• DESIGN.md — die Annotations einheit und warum, warum jedes Antwortformat, Annotatoren pro Element, wofür die Qualitätskontrolle dient, und eine separate, explizite Liste der Entscheidungen, die Sie angenommen haben, weil die Aufgabenbeschreibung es nicht sagte. Der letzte Absatz macht das Dokument wertvoll.
• QUESTIONS.md — was Sie überhaupt nicht entscheiden konnten. Warten Sie niemals auf eine Antwort; liefern Sie etwas Lauffähiges zusammen mit der Frage.

python .claude/skills/potato-tasks/scripts/estimate_effort.py config.yaml --rate 15

Berichtet, wie viele Annotatoren das Design benötigt, wie lange jeder arbeitet, Gesamtstunden und Kosten. Führen Sie es aus, bevor die Anweisungen geschrieben werden – es ist der günstigste Ort, um ein Design zu identifizieren, das sich niemand leisten kann.

references/recording-decisions.md enthält die Vorlage für DESIGN.md und was die Schätzung verändert.

Starten Sie von einem veröffentlichten Design

Bevor Sie ein Schema aus einer Feldliste schreiben, suchen Sie nach einem, das jemand bereits verwendet hat:

python .claude/skills/potato-tasks/scripts/find_design.py --query "stance" --with-instructions
python .claude/skills/potato-tasks/scripts/find_design.py --show text/argumentation-stance/argument-quality

Die Potato-Showcase umfasst 440 Annotationsaufgabendesigns, die meisten basierend auf einer veröffentlichten Arbeit, mit echten Labelsätzen und echten Frageformulierungen – und 281 davon enthalten schriftliche Anweisungen. Keines davon hat einen phases-Block, eine Einwilligungsseite oder eine Trainingsrunde. Nehmen Sie also die Fragen von dort und die Studie darum herum aus worked-example.md. references/finding-a-design.md behandelt, was geändert werden muss, bevor eines wiederverwendet wird.

Die Anweisungen schreiben

Die Konfiguration hat einen Validator. Der Text, den ein Annotator liest, hat keinen, und hier entsteht der größte Teil der Uneinigkeit in einem fertigen Datensatz.

references/writing-guidelines.md behandelt die vier Oberflächen, auf denen an annotator gerichteter Text leben kann (die instructions-Phase, das annotation_instructions-Banner, annotation_codebook_url und die pro-Schema-Beschreibung), was eine Labeldefinition enthalten muss, um eine Argumentation zu klären, Stichentscheid-Regeln, ausgearbeitete Beispiele einschließlich der Grenzfälle, und die Iteration der Richtlinien aus den Unstimmigkeiten des Piloten. examples/advanced/long-guidelines/ ist ein funktionierendes Modell für all das.

Zwei Dinge, die Sie richtig machen sollten, ohne weiterzulesen:

• Das Banner ist nicht das Codebuch. annotation_instructions steht auf jeder Seite

…

[gekürzt für die Übersetzung]