davidjurgens/potato-skill

Tâches d'annotation Potato

Une tâche Potato est un fichier de configuration YAML plus un fichier de données. La construire implique trois phases : décider quoi demander et comment, l'écrire correctement, et l'exécuter jusqu'à avoir vu une personne passer de l'écran de connexion à la fin de l'étude. La deuxième phase est la seule pour laquelle il existe un validateur, ce qui la rend tentante comme point de départ et d'arrêt. C'est pourtant la moins susceptible d'être à l'origine des problèmes de l'étude.

Lisez AGENTS.md à la racine du projet s'il existe : il contient les conventions du projet par-dessus ce document.

Si vous avez été invoqué sans tâche décrite

Quelqu'un a tapé /potato-tasks et il n'y a pas de consigne dans la conversation. Ne commencez pas à construire, et n'ouvrez pas par « que voulez-vous créer ? » — un chercheur qui n'a pas utilisé Potato ne peut pas répondre utilement.

Demandez une phrase, proposez une conception à partir de celle-ci, puis confirmez uniquement ce que vous avez dû deviner. references/interviewing.md est la banque de questions : la demande d'ouverture, la proposition en quatre lignes, puis deux séries de questions à choix multiples couvrant la modalité, l'unité, le format de réponse, les annotateurs par élément, le contrôle qualité, la cible d'exportation et qui peut se connecter — puis une troisième série qui propose les sept groupes de capacités sous forme de menu et n'approfondit que ce qui est sélectionné.

Le document insiste sur deux points. Demandez toujours quelle est la modalité des données : elle détermine l'affichage, la famille de schémas et la clé par famille qui indique où se trouve le média, et une erreur à ce niveau est silencieuse. Et n'imposez pas de phases — consent, training et prestudy sont des choix de protocole, la plupart des tâches n'en ont pas besoin, et un chercheur qui en a besoin le sait.

La règle constante de construire avec des hypothèses énoncées plutôt que d'attendre reste valable — elle s'applique dès que l'entretien a quelque chose sur quoi faire des hypothèses. Sans rien dans le contexte, poser quatre questions structurées est plus rapide pour le chercheur que n'importe quelle supposition que vous pourriez faire.

Installation de Potato

Cette compétence utilise principalement la commande potato et importe les registres de Potato. Rien de tout cela ne fonctionne si le paquet n'est pas dans l'environnement où vous exécutez les commandes.

potato --version || pip install potato-annotation

La navigation par navigateur dans scripts/walk_task.py nécessite également Playwright : pip install 'potato-annotation[preview]' && playwright install chromium.

Les scripts de cette compétence

Sept des procédures ci-dessous sont des scripts plutôt que des instructions, car elles sont suffisamment longues pour être mal exécutées manuellement et vous les exécuterez fréquemment. Ils se trouvent à côté de ce fichier dans scripts/.

Script	Ce qu'il fait
boot_and_check.py config.yaml -p 8000	Démarre, attend un code 200, et liste chaque fonctionnalité configurée mais qui n'a rien chargé
walk_task.py --url … --config … --task-dir .	Enregistre un annotateur, parcourt toute l'étude, et vérifie que les réponses ont bien abouti dans user_state.json
estimate_effort.py config.yaml --rate 15	Éléments, annotateurs nécessaires, minutes par élément, heures totales et coût
find_design.py --type span --with-instructions	Recherche 440 designs de tâches publiés dans la Potato Showcase
handover.py config.yaml --confirm	Supprime les comptes que vous avez créés pendant les tests et écrit RUNNING.md
check_ui.py --url … --config config.yaml	Affiche chaque page et signale les schémas en dessous du pli, les médias vides, les tuiles de choix vides, les schémas sans contrôle pour répondre, les réponses que rien ne collecte, ce que les widgets disent avoir échoué, les conflits de raccourcis clavier et les schémas qui ne sont jamais apparus. --phase poststudy mesure une page que la navigation ne peut pas atteindre
study_status.py --url … --task-dir .	Progression, rythme par annotateur, accord, et ce qui semble anormal sur une étude en cours

Chacun accepte --help, et boot_and_check, walk_task, check_ui et study_status acceptent --json lorsque vous voulez agir sur le résultat plutôt que de le lire.

La boucle

potato validate config.yaml --strict               # structure et clés inconnues
potato preview config.yaml                         # ce que le formulaire déclare
potato preview config.yaml --screenshot out.png    # affiche une page, signale les erreurs du navigateur
nohup potato start config.yaml -p 8000 > server.log 2>&1 &    # démarre et lit le journal

Les trois premières commandes renvoient une réponse rapidement. La quatrième ne renvoie jamais rien — lancez-la en arrière-plan, interrogez curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/ pour un code 200, et lisez server.log.

potato --help liste ces commandes sous autres commandes, en dessous des options de start. Chacune a sa propre grammaire, donc potato validate --help et potato preview --help sont les endroits où trouver leurs options.

Chaque étape détecte une classe différente d'échec

Étape	Détecte	Aveugle à
validate --strict	Clés obligatoires manquantes, mauvais types, clés inconnues à 1–2 niveaux	Fichiers latéraux, types de phases, tout ce qui se trouve à l'intérieur d'une entrée de schéma
preview	Quels schémas et raccourcis clavier la configuration déclare	Si quelque chose s'affiche réellement
preview --screenshot	Exceptions non capturées, console.error, requêtes échouées sur une page	Tout ce qui est en dessous de 900px, tout widget conditionnel, toute autre phase
démarrage + lecture du journal	Formats de fichiers latéraux, assemblage des phases, initialisation des sous-systèmes	À quoi cela ressemble
navigation dans un navigateur	L'étude réelle	—

Sauter les deux dernières étapes, c'est livrer une tâche qui valide, dont la capture d'écran est propre, mais qui perd sa phase d'entraînement, ses contrôles d'attention et un tiers de ses éléments.

Démarrez tôt

Le journal de démarrage est le véritable validateur. C'est le seul élément qui signale si les parties de la configuration que validate n'ouvre jamais ont fonctionné :

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

Un démarrage sain sur une tâche avec entraînement et contrôles d'attention affiche Loaded 3 training instances et Loaded 2 attention check items, et ne dit rien à propos des phases. Tout le reste est une fonctionnalité configurée mais désactivée.

Démarrez dès que la configuration est analysée — avant que l'interface soit terminée, avant que les instructions soient écrites. running-a-task.md contient la recette pour lancer en arrière-plan, la vérification de l'état de préparation, le tableau des lignes de journal et les fichiers générés à supprimer après une modification.

Trois modes d'échec silencieux

Activé ne signifie pas en cours d'exécution. attention_checks.enabled: true avec un fichier d'éléments malformé enregistre un avertissement, puis Loaded 0 attention check items, puis exécute toute l'étude sans contrôle qualité. Vérifiez le compteur, pas la configuration.

--strict n'atteint pas tout. Il vérifie le niveau supérieur et un niveau dans la plupart des blocs. Il ne vérifie pas à l'intérieur de phases, surveyflow, quality_control, crowdsourcing, publish, automatic_assignment, ui, ui_config, ni à l'intérieur d'une entrée de annotation_schemes ou instance_display.fields. key_binding au lieu de key_value valide proprement et ne fait rien. De même pour un type: de phase qui n'existe pas.

La capture d'écran est la zone visible, pas la page. --screenshot écrit 1280×900. Sur une tâche avec une bannière d'instructions, c'est la bannière et la moitié de l'élément — aucune des questions. Le conseil « regardez le PNG et vérifiez que le bouton Suivant est au-dessus du pli » ne peut pas être suivi avec cet outil seul. Naviguez dans un navigateur et capturez la page entière avec full_page=True.

Découvrez ce qu'ils ont déjà

Un brief plus un fichier de données est le cas courant, mais pas le seul. Posez quatre questions avant de concevoir quoi que ce soit, car chacune a une commande derrière elle et chacune est coûteuse à découvrir après que la configuration est écrite :

Question	Raison
Quel est le format des données, et où sont les médias ?	Les transcriptions et les corpus de conversation ont leurs propres convertisseurs
Avez-vous déjà des annotations ?	potato import lit quatorze formats et écrit un projet exécutable
Que doit-il ressortir à la fin ?	Vingt-neuf formats d'exportation. Vérifiez la cible avant que quiconque annote
Qui gère l'étude après la passation, et pour combien de temps ?	Détermine l'hébergement, les connexions et la liste d'autorisation

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 couvre les trois, y compris la décision la plus importante : si les annotations importées sont des pré-annotations qu'un humain corrige, ou un travail --seed-user qui marque l'élément comme terminé.

Briefs sous-spécifiés

Lisez references/asking-the-experimenter.md avant d'écrire la configuration. Décidez par vous-même quand se tromper est peu coûteux ; demandez quand c'est coûteux, irréversible ou que cela ne vous appartient pas — l'unité d'annotation, le budget annotateur, la formulation du consentement, et tout ce qui implique des personnes identifiables.

N'attendez jamais une réponse. Construisez avec des hypothèses énoncées, écrivez les questions dans QUESTIONS.md à côté de quelque chose qui fonctionne, et dites quelle hypothèse vous réviseriez en premier.

Cherchez la fonctionnalité avant d'en créer une

Potato a plus de fonctionnalités intégrées que ce qu'une référence de configuration ne laisse paraître. L'erreur coûteuse n'est pas un nom de type inventé — la validation le détecte. C'est d'assembler manuellement quelque chose que Potato fait déjà.

references/modes-and-subsystems.md est la table de routage de ce qu'un chercheur a dit au bloc qui le fait : QDA et codebooks, mode solo, salles, adjudication, workflow de révision, sessions, pocket, apprentissage actif, juges, crowdsourcing, publication, télémétrie. Consultez-la avant d'écrire un schéma qui ressemble à un contournement.

Elle s'ouvre sur les sept groupes — matériel, la réponse, l'unité, les personnes, la confiance, l'aide du modèle, la sortie — qui est la même carte que l'entretien propose comme menu. Utilisez-la comme une liste de contrôle par rapport au brief : les groupes qu'un brief ne mentionne jamais sont ceux où un chercheur est le plus susceptible de manquer quelque chose qu'il voudrait. Soulevez au maximum deux d'entre eux, et seulement là où ils comptent ; le reste va dans QUESTIONS.md.

Le groupe que les chercheurs oublient le plus souvent est la réponse. Ils demandent radio et likert et s'arrêtent là, et soft_label, range_slider, semantic_differential, constant_sum et confidence ne sont jamais abordés.

Concevoir la tâche

references/designing-a-task.md couvre les sept décisions derrière chaque tâche : l'unité, les questions, le format de réponse, les annotateurs par élément, l'ordre des éléments, le contrôle qualité, et les phases de chaque côté.

La table de routage couvre les demandes courantes et s'arrête là. Onze types ne sont nommés nulle part ailleurs que dans la référence générée, donc ils ne sont jamais abordés : multirate (dix évaluations sur une seule échelle, pas dix schémas likert), hierarchical_multiselect (une taxonomie, réduite, avec recherche), select, soft_label (une distribution plutôt qu'un choix forcé), range_slider, semantic_differential, conjoint, card_sort, extractive_qa, multi_document_event, code_review. Chacun a un exemple fonctionnel et une ligne dans designing-a-task.md.

Deux points faciles à mal comprendre et coûteux à découvrir tard :

• Le format de réponse détermine la métrique d'accord. Potato la choisit en fonction du type de schéma. Une évaluation de 1 à 5 stockée comme radio est notée comme non ordonnée, donc « 1 vs 2 » et « 1 vs 5 » comptent de la même manière. C'est une erreur de mesure, pas une erreur cosmétique. Tableau dans references/assignment-and-agreement.md.
• num_annotators_per_item définit la cible, max_annotations_per_user définit ce qu'une personne voit réellement. Si non défini, le plafond est le nombre d'éléments, donc tout le monde se voit proposer l'ensemble du corpus. Si défini en dessous de ce nombre, les annotateurs s'arrêtent simplement plus tôt, sans rien pour expliquer pourquoi. automatic_assignment.instance_per_annotator ressemble à la clé pour cela et n'est pas du tout lue.

Le compte rendu de conception et le coût

Deux fichiers à côté de la configuration, ni l'un ni l'autre ne pouvant être contenus dans la configuration :

• DESIGN.md — l'unité d'annotation et pourquoi, pourquoi chaque format de réponse, les annotateurs par élément, à quoi sert le contrôle qualité, et une liste séparée et explicite des choix que vous avez supposés parce que le brief ne les mentionnait pas. Ce dernier paragraphe est ce qui rend le document utile.
• QUESTIONS.md — ce que vous n'avez pas pu décider du tout. N'attendez jamais une réponse ; livrez quelque chose qui fonctionne à côté de la question.

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

indique le nombre d'annotateurs dont la conception a besoin, combien de temps chacun travaille, les heures totales et un coût. Exécutez-le avant que les instructions soient rédigées — c'est l'endroit le moins coûteux pour détecter une conception que personne ne peut se permettre.

references/recording-decisions.md contient le modèle DESIGN.md et ce qui modifie l'estimation.

Partez d'une conception publiée

Avant d'écrire un schéma à partir d'une liste de champs, cherchez-en un que quelqu'un a déjà exécuté :

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

La Potato Showcase contient 440 designs de tâches d'annotation, la plupart construits à partir d'un article publié, avec de vrais ensembles d'étiquettes et un vrai libellé de question — et 281 d'entre eux contiennent des instructions écrites. Aucun d'eux n'a de bloc phases, de page de consentement ou de phase d'entraînement, alors prenez les questions de là et l'étude autour d'eux à partir de worked-example.md. references/finding-a-design.md couvre ce qu'il faut modifier avant de réutiliser un design.

Rédaction des instructions

La configuration a un validateur derrière elle. Le texte que lit un annotateur n'en a pas, et c'est la source de la plupart des désaccords dans un jeu de données final.

references/writing-guidelines.md couvre les quatre surfaces sur lesquelles le texte destiné à l'annotateur peut se trouver (la phase instructions, la bannière annotation_instructions, annotation_codebook_url, et la description par schéma), ce qu'une définition d'étiquette doit contenir pour trancher un argument, les règles de départage, les exemples travaillés, y compris les cas limites, et l'itération des consignes à partir des désaccords du pilote. examples/advanced/long-guidelines/ est un modèle fonctionnel de tout cela.

Deux choses à faire correctement sans lire plus loin :

• La bannière n'est pas le codebook. annotation_instructions se trouve sur chaque page, mais est généralement trop court pour un véritable codebook. Le codebook est un document séparé, lié par annotation_codebook_url, que l'annotateur peut consulter tout en annotant.
• Les instructions sont testées, pas seulement écrites. La seule façon de savoir si les instructions sont claires est de regarder quelqu'un les utiliser. Le script walk_task peut être exécuté avec un annotateur simulé, mais le vrai test est de regarder un humain.

Exécution d'un test pilote

scripts/walk_task.py simule un annotateur parcourant l'ensemble de l'étude et vérifie que les réponses sont enregistrées. Mais un pilote avec un humain réel trouvera des problèmes qu'aucun script ne peut détecter. references/piloting.md couvre comment recruter des pilotes, quoi regarder, et comment itérer sur la conception en fonction des retours.

Déploiement

scripts/handover.py config.yaml --confirm supprime les comptes de test et écrit RUNNING.md avec les instructions pour l'équipe qui gérera l'étude. references/deploying.md couvre les options d'hébergement (serveur local, serveur cloud, Docker), la configuration des comptes utilisateur, et la surveillance de l'étude en cours.

Références

• references/interviewing.md — Comment interviewer un chercheur pour comprendre son besoin
• references/asking-the-experimenter.md — Questions à poser avant de concevoir
• references/designing-a-task.md — Les sept décisions de conception
• references/modes-and-subsystems.md — Fonctionnalités intégrées de Potato par groupe
• references/finding-a-design.md — Comment trouver et adapter un design existant
• references/writing-guidelines.md — Rédaction des instructions pour les annotateurs
• references/importing-existing-work.md — Import de données et d'annotations existantes
• references/assignment-and-agreement.md — Métriques d'assignation et d'accord
• references/recording-decisions.md — Modèle pour DESIGN.md et QUESTIONS.md
• references/piloting.md — Exécution de tests pilotes
• references/deploying.md — Options de déploiement
• examples/advanced/long-guidelines/ — Exemple de codebook complet