davidjurgens/potato-skill

Tareas de anotación con Potato

Una tarea Potato es un archivo YAML de configuración más un archivo de datos. Construir una implica tres trabajos: decidir qué preguntar y cómo, escribirlo correctamente y ejecutarlo hasta que hayas visto a una persona pasar desde la pantalla de inicio de sesión hasta el final del estudio. El segundo trabajo es el que tiene un validador detrás, por lo que es tentador comenzar y terminar ahí. Pero es el que menos probabilidades tiene de ser donde el estudio falle.

Lee AGENTS.md en la raíz del proyecto si existe; contiene las convenciones del proyecto sobre esto.

Si fuiste invocado sin ninguna tarea descrita

Alguien escribió /potato-tasks y no hay un resumen en la conversación. No empieces a construir y no abras con "¿qué te gustaría hacer?" — un investigador que no ha usado Potato no puede responder eso de manera útil.

Pide una frase, propón un diseño a partir de ella, y luego confirma solo lo que tuviste que adivinar. references/interviewing.md es el banco de preguntas: la pregunta inicial, la propuesta de cuatro líneas, luego dos rondas de opción múltiple que cubren la modalidad, la unidad, el formato de respuesta, anotadores por ítem, control de calidad, el destino de exportación y quién puede iniciar sesión — luego una tercera ronda que ofrece los siete grupos de capacidades como un menú y profundiza solo en lo que se selecciona.

Hay dos cosas que enfatiza. Pregunta qué modalidad tienen los datos, cada vez: determina la visualización, la familia de esquemas y la clave por familia que indica dónde vive el contenido multimedia, y equivocarse es silencioso. Y no impongas fases — consent, training y prestudy son decisiones de protocolo, la mayoría de las tareas no necesitan ninguna, y un investigador que necesita una sabe que la necesita.

La regla general de construir con suposiciones declaradas en lugar de esperar sigue vigente; se aplica una vez que la entrevista tiene algo de lo que suponer. Sin nada en contexto, hacer cuatro preguntas estructuradas es más rápido para el investigador que cualquier suposición que puedas hacer.

Instalando Potato

La mayor parte de este skill utiliza el comando potato e importa los registros de Potato. Ninguno de los dos funciona si el paquete no está en el entorno en el que ejecutas los comandos.

potato --version || pip install potato-annotation

El recorrido del navegador en scripts/walk_task.py además necesita Playwright: pip install 'potato-annotation[preview]' && playwright install chromium.

Los scripts en este skill

Siete de los procedimientos a continuación son scripts en lugar de instrucciones, porque son lo suficientemente largos como para equivocarse manualmente y son lo que ejecutarás repetidamente. Viven junto a este archivo en scripts/.

Script	Qué hace
boot_and_check.py config.yaml -p 8000	Arranca, espera un 200, y nombra cada característica que está configurada pero no cargó nada
walk_task.py --url … --config … --task-dir .	Registra un anotador, recorre todo el estudio y verifica que las respuestas llegaron a user_state.json
estimate_effort.py config.yaml --rate 15	Ítems, anotadores necesarios, minutos cada uno, horas totales y costo
find_design.py --type span --with-instructions	Busca 440 diseños de tareas publicados en el Potato Showcase
handover.py config.yaml --confirm	Elimina las cuentas que creaste mientras probabas y escribe RUNNING.md
check_ui.py --url … --config config.yaml	Renderiza cada página e informa esquemas debajo del pliegue, medios vacíos, mosaicos de opciones vacíos, esquemas sin control para responder, respuestas que no recoge nada, qué dicen los widgets que salió mal, conflictos de atajos de teclado y esquemas que nunca aparecieron. --phase poststudy mide una página a la que el recorrido no puede llegar
study_status.py --url … --task-dir .	Progreso, ritmo por anotador, acuerdo y lo que parece incorrecto en un estudio en ejecución

Cada uno acepta --help, y boot_and_check, walk_task, check_ui y study_status aceptan --json cuando quieras actuar sobre el resultado en lugar de leerlo.

El bucle

potato validate config.yaml --strict               # estructura y claves desconocidas
potato preview config.yaml                         # lo que declara el formulario
potato preview config.yaml --screenshot out.png    # renderiza una página, informa errores del navegador
nohup potato start config.yaml -p 8000 > server.log 2>&1 &    # arranca y lee el log

Los primeros tres devuelven rápidamente. El cuarto nunca regresa; ejecútalo en segundo plano, consulta curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/ para un 200, y lee server.log.

potato --help lista estos bajo otros comandos, debajo de las banderas de start. Cada uno tiene su propia gramática, así que potato validate --help y potato preview --help son donde están sus opciones.

Cada paso detecta una clase diferente de fallo

Paso	Detecta	Ciego a
validate --strict	Claves requeridas faltantes, tipos incorrectos, claves desconocidas a 1–2 niveles	Archivos laterales, tipos de fase, cualquier cosa dentro de una entrada de esquema
preview	Qué esquemas y atajos de teclado declara la configuración	Si algo de eso se renderiza
preview --screenshot	Excepciones no capturadas, console.error, solicitudes fallidas en una página	Todo por debajo de 900px, cada widget condicional, cada otra fase
arranque + leer el log	Formatos de archivos laterales, ensamblaje de fases, inicialización de subsistemas	Cómo se ve
conducirlo en un navegador	El estudio real	—

Saltarse los dos últimos es cómo una tarea llega a producción que valida, se ve limpia en la captura de pantalla y pierde su fase de entrenamiento, sus comprobaciones de atención y un tercio de sus ítems.

Arráncalo temprano

El log de inicio es el verdadero validador. Es lo único que informa si las partes de la configuración que validate nunca abre realmente funcionaron:

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

Un arranque saludable en una tarea con entrenamiento y comprobaciones de atención dice Loaded 3 training instances y Loaded 2 attention check items, y no dice nada sobre fases. Cualquier otra cosa es una característica que está configurada y apagada.

Arranca tan pronto como la configuración se analice — antes de que la interfaz esté terminada, antes de que las instrucciones estén escritas. running-a-task.md tiene la receta para segundo plano, la verificación de disponibilidad, la tabla de líneas de log y qué archivos generados eliminar después de una edición.

Tres modos de fallo silenciosos

Habilitado no es ejecutándose. attention_checks.enabled: true con un archivo de ítems mal formado registra una advertencia, luego Loaded 0 attention check items, luego ejecuta todo el estudio con el control de calidad apagado. Verifica el conteo, no la configuración.

--strict no llega a todo. Verifica el nivel superior y un nivel dentro de la mayoría de los bloques. No verifica dentro de phases, surveyflow, quality_control, crowdsourcing, publish, automatic_assignment, ui, ui_config, o dentro de cualquier entrada de annotation_schemes o instance_display.fields. key_binding en lugar de key_value valida limpiamente y no hace nada. También lo hace un type: de fase que no existe.

La captura de pantalla es el viewport, no la página. --screenshot escribe 1280×900. En una tarea con un banner de instrucciones, eso es el banner y la mitad del ítem — ninguna de las preguntas. El consejo de "mira el PNG y verifica que el botón Siguiente esté sobre el pliegue" no se puede seguir solo con esta herramienta. Conduce un navegador y toma una captura de pantalla con full_page=True.

Averigua qué tienen ya

Un resumen más un archivo de datos es el caso común, no el único. Pregunta cuatro cosas antes de diseñar cualquier cosa, porque cada una tiene un comando detrás y cada una es costosa de descubrir después de que la configuración esté escrita:

Pregunta	Porque
¿En qué formato están los datos y dónde está el contenido multimedia?	Las transcripciones y los corpus de conversación tienen sus propios convertidores
¿Ya tienes anotaciones?	potato import lee catorce formatos y escribe un proyecto ejecutable
¿Qué tiene que salir al final?	Veintinueve formatos de exportación. Verifica el destino antes de que alguien anote
¿Quién lo ejecuta después de la entrega y por cuánto tiempo?	Decide el hosting, los inicios de sesión y la lista de permitidos

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 cubre los tres, incluyendo la decisión que más importa: si las anotaciones importadas son pre-anotaciones que un humano corrige, o trabajo --seed-user que marca el ítem como completado.

Resúmenes de tareas poco especificados

Lee references/asking-the-experimenter.md antes de escribir la configuración. Decide tú mismo cuando equivocarse sea barato; pregunta cuando sea caro, irreversible o no sea tuyo — la unidad de anotación, el presupuesto de anotadores, la redacción del consentimiento y cualquier cosa que involucre personas identificables.

Nunca esperes una respuesta. Construye con suposiciones declaradas, escribe las preguntas en QUESTIONS.md junto con algo que funcione, y di qué suposición revisarías primero.

Busca la función antes de construir una

Potato tiene más incorporado de lo que una referencia de configuración hace evidente. El error costoso no es un nombre de tipo inventado — la validación lo detecta. Es ensamblar manualmente algo que Potato ya hace.

references/modes-and-subsystems.md es la tabla de enrutamiento desde lo que un investigador dijo hasta el bloque que lo hace: QDA y libros de códigos, modo individual, salas, adjudicación, flujo de revisión, sesiones, pocket, aprendizaje activo, jueces, crowdsourcing, publicación, telemetría. Verifícalo antes de escribir un esquema que suene a una solución alternativa.

Comienza con los siete grupos — material, la respuesta, unidad, personas, confianza, ayuda del modelo, salida — que es el mismo mapa que la entrevista ofrece como menú. Ejecútalo contra el resumen como una lista de verificación: los grupos que un resumen nunca menciona son donde un investigador tiene más probabilidades de estar perdiendo algo que querría. Plantea como máximo dos de ellos, y solo cuando importen; el resto va a QUESTIONS.md.

El grupo que los investigadores pasan por alto más consistentemente es la respuesta. Piden radio y likert y se detienen, y soft_label, range_slider, semantic_differential, constant_sum y confidence nunca se consideran.

Diseñándolo

references/designing-a-task.md cubre las siete decisiones detrás de cada tarea: la unidad, las preguntas, el formato de respuesta, anotadores por ítem, orden de ítems, control de calidad y las fases a cada lado.

La tabla de enrutamiento cubre las solicitudes comunes y se detiene. Once tipos no se nombran en ningún lugar excepto en la referencia generada, por lo que nunca se consideran: multirate (diez valoraciones en una escala, no diez esquemas likert), hierarchical_multiselect (una taxonomía, colapsada, con búsqueda), select, soft_label (una distribución en lugar de una elección forzada), range_slider, semantic_differential, conjoint, card_sort, extractive_qa, multi_document_event, code_review. Cada uno tiene un ejemplo funcional y una fila en designing-a-task.md.

Dos que son fáciles de equivocar y costosos de descubrir tarde:

• El formato de respuesta decide la métrica de acuerdo. Potato la elige según el tipo de esquema. Una calificación de 1 a 5 almacenada como radio se puntúa como no ordenada, por lo que "1 vs 2" y "1 vs 5" cuentan igual. Eso es un error de medición, no uno cosmético. Tabla en references/assignment-and-agreement.md.
• num_annotators_per_item establece el objetivo, max_annotations_per_user establece lo que una persona ve realmente. Si no se establece, el límite es el número de ítems, por lo que a todos se les ofrece todo el corpus. Si se establece por debajo de eso, los anotadores simplemente se detienen temprano, sin nada que indique por qué. automatic_assignment.instance_per_annotator parece la clave para esto y no se lee en absoluto.

El registro de diseño y el costo

Dos archivos junto a la configuración, ninguno de los cuales puede contener la configuración:

• DESIGN.md — la unidad de anotación y por qué, por qué cada formato de respuesta, anotadores por ítem, para qué sirve el control de calidad y una lista separada y explícita de las elecciones que asumiste porque el resumen no lo decía. Ese último párrafo es lo que hace que el documento valga la pena abrir.
• QUESTIONS.md — lo que no pudiste decidir en absoluto. Nunca esperes una respuesta; entrega algo que funcione junto con la pregunta.

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

informa cuántos anotadores necesita el diseño, cuánto tiempo trabaja cada uno, horas totales y un costo. Ejecútalo antes de que se escriban las instrucciones; es el lugar más barato para detectar un diseño que nadie puede pagar.

references/recording-decisions.md tiene la plantilla de DESIGN.md y qué mueve la estimación.

Comienza desde un diseño publicado

Antes de escribir un esquema a partir de una lista de campos, busca uno que alguien ya haya ejecutado:

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

El Potato Showcase tiene 440 diseños de tareas de anotación, la mayoría construidos a partir de un artículo publicado, con conjuntos de etiquetas reales y redacción de preguntas real — y 281 de ellos llevan instrucciones escritas. Ninguno de ellos tiene un bloque phases, una página de consentimiento o una ronda de entrenamiento, así que toma las preguntas de allí y el estudio a su alrededor de worked-example.md. references/finding-a-design.md cubre qué cambiar antes de reutilizar uno.

Escribiendo las instrucciones

La configuración tiene un validador detrás. El texto que lee un anotador no lo tiene, y es de donde proviene la mayor parte del desacuerdo en un conjunto de datos terminado.

references/writing-guidelines.md cubre las cuatro superficies en las que puede vivir el texto dirigido al anotador (la fase instructions, el banner annotation_instructions, annotation_codebook_url y la description por esquema), qué debe contener una definición de etiqueta para resolver una discusión, reglas de desempate, ejemplos trabajados incluyendo los casos límite, e iterar las pautas a partir de los desacuerdos del piloto. examples/advanced/long-guidelines/ es un modelo funcional de todo ello.

Dos cosas para hacer bien sin leer más:

• El banner no es el libro de códigos. annotation_instructions está en cada página, mientras que el libro de códigos es un documento separado que los anotadores pueden consultar. El banner debe tener las instrucciones específicas de la tarea; el libro de códigos tiene las definiciones de las etiquetas.

• ...