davidjurgens/potato-skill

Tarefas de anotação Potato

Uma tarefa Potato é um arquivo YAML de configuração mais um arquivo de dados. Construir uma envolve três trabalhos: decidir o que perguntar e como, escrever isso corretamente e executar até que você tenha observado uma pessoa ir da tela de login ao final do estudo. O segundo trabalho é o que tem um validador por trás, e é por isso que é tentador começar e parar por aí. É o menos provável de ser onde o estudo quebra.

Leia AGENTS.md na raiz do projeto, se existir — ele carrega convenções do projeto sobre estas instruções.

Se você foi invocado sem nenhuma tarefa descrita

Alguém digitou /potato-tasks e não há briefing na conversa. Não comece a construir e não abra com "o que você gostaria de fazer?" — um pesquisador que não usou Potato não consegue responder isso de forma útil.

Peça uma frase, proponha um design a partir dela e confirme apenas o que você teve que adivinhar. references/interviewing.md é o banco de perguntas: a pergunta inicial, a proposta de quatro linhas, depois duas rodadas de múltipla escolha cobrindo a modalidade, a unidade, o formato de resposta, anotadores por item, controle de qualidade, o destino da exportação e quem pode fazer login — depois uma terceira rodada que oferece os sete clusters de capacidade como um menu e aprofunda apenas no que for selecionado.

Duas coisas que são enfáticas. Pergunte sempre qual é a modalidade dos dados: ela decide a exibição, a família de esquemas e a chave por família que diz onde a mídia está, e errar isso é silencioso. E não force fases — consent, training e prestudy são decisões de protocolo, a maioria das tarefas não quer nenhuma delas, e um pesquisador que precisa de uma sabe que precisa.

A regra geral de construir com suposições declaradas em vez de esperar ainda vale — ela se aplica uma vez que a entrevista tem algo para supor. Sem nada no contexto, fazer quatro perguntas estruturadas é mais rápido para o pesquisador do que qualquer palpite que você possa fazer.

Instalando Potato

A maior parte desta habilidade usa o comando potato e importa os registros do Potato. Nenhum deles funciona se o pacote não estiver no ambiente onde você está executando os comandos.

potato --version || pip install potato-annotation

O passeio pelo navegador em scripts/walk_task.py também precisa do Playwright: pip install 'potato-annotation[preview]' && playwright install chromium.

Os scripts nesta habilidade

Sete dos procedimentos abaixo são scripts em vez de instruções, porque são longos demais para serem feitos manualmente e são o que você executará repetidamente. Eles estão ao lado deste arquivo em scripts/.

Script	O que faz
boot_and_check.py config.yaml -p 8000	Inicia, espera por um 200 e nomeia cada recurso que está configurado mas não carregou nada
walk_task.py --url … --config … --task-dir .	Registra um anotador, percorre todo o estudo e verifica se as respostas chegaram em user_state.json
estimate_effort.py config.yaml --rate 15	Itens, anotadores necessários, minutos cada, horas totais e custo
find_design.py --type span --with-instructions	Pesquisa 440 designs de tarefas publicados no Potato Showcase
handover.py config.yaml --confirm	Remove as contas que você criou durante o teste e escreve RUNNING.md
check_ui.py --url … --config config.yaml	Renderiza cada página e relata esquemas abaixo da dobra, mídia vazia, tiles de escolha vazios, esquemas sem controle para responder, respostas que nada coleta, o que os widgets dizem que deu errado, conflitos de atalhos de teclado e esquemas que nunca apareceram. --phase poststudy mede uma página que o passeio não consegue acessar
study_status.py --url … --task-dir .	Progresso, ritmo por anotador, concordância e o que parece errado em um estudo em execução

Cada um aceita --help, e boot_and_check, walk_task, check_ui e study_status aceitam --json quando você quiser agir sobre o resultado em vez de lê-lo.

O loop

potato validate config.yaml --strict               # estrutura e chaves desconhecidas
potato preview config.yaml                         # o que o formulário declara
potato preview config.yaml --screenshot out.png    # renderizar uma página, relatar erros do navegador
nohup potato start config.yaml -p 8000 > server.log 2>&1 &    # iniciar e ler o log

Os três primeiros retornam rapidamente. O quarto nunca retorna — coloque-o em segundo plano, verifique com curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/ por um 200 e leia server.log.

potato --help lista estes sob outros comandos, abaixo das flags de start. Cada um tem sua própria gramática, então potato validate --help e potato preview --help são onde suas opções estão.

Cada etapa captura uma classe diferente de falha

Etapa	Captura	Cega para
validate --strict	Chaves obrigatórias ausentes, tipos errados, chaves desconhecidas em 1–2 níveis	Arquivos laterais, tipos de fase, qualquer coisa dentro de uma entrada de esquema
preview	Quais esquemas e atalhos de teclado a config declara	Se algo disso renderiza
preview --screenshot	Exceções não capturadas, console.error, requisições falhas em uma página	Tudo abaixo de 900px, todo widget condicional, toda outra fase
iniciar + ler o log	Formatos de arquivos laterais, montagem de fases, inicialização de subsistemas	Como fica
dirigir no navegador	O estudo real	—

Pular as duas últimas é como uma tarefa chega que valida, tira screenshot limpo e perde sua fase de treinamento, suas verificações de atenção e um terço de seus itens.

Inicie cedo

O log de inicialização é o verdadeiro validador. É a única coisa que informa se as partes da config que validate nunca abre realmente funcionaram:

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

Uma inicialização saudável em uma tarefa com treinamento e verificações de atenção diz Loaded 3 training instances e Loaded 2 attention check items, e não diz nada sobre fases. Qualquer outra coisa é um recurso que está configurado e desligado.

Inicie assim que a config for analisada — antes da interface estar pronta, antes das instruções serem escritas. running-a-task.md tem a receita para execução em segundo plano, a verificação de prontidão, a tabela de linhas de log e quais arquivos gerados excluir após uma edição.

Três modos de falha silenciosos

Ativado não é executando. attention_checks.enabled: true com um arquivo de itens malformado registra um aviso, depois Loaded 0 attention check items, depois executa todo o estudo com o controle de qualidade desligado. Verifique a contagem, não a config.

--strict não alcança tudo. Ele verifica o nível superior e um nível dentro da maioria dos blocos. Ele não verifica dentro de phases, surveyflow, quality_control, crowdsourcing, publish, automatic_assignment, ui, ui_config, ou dentro de qualquer entrada de annotation_schemes ou instance_display.fields. key_binding em vez de key_value valida limpo e não faz nada. O mesmo para um tipo de fase type: que não existe.

O screenshot é a viewport, não a página. --screenshot escreve 1280×900. Em uma tarefa com um banner de instruções, isso é o banner e metade do item — nenhuma das perguntas. O conselho de "olhe o PNG e verifique se o botão Next está acima da dobra" não pode ser seguido apenas com esta ferramenta. Dirija um navegador e tire screenshot com full_page=True.

Descubra o que eles já têm

Um briefing mais um arquivo de dados é o caso comum, não o único. Pergunte quatro coisas antes de projetar qualquer coisa, porque cada uma tem um comando por trás e cada uma é cara para descobrir depois que a config está escrita:

Pergunte	Porque
Qual é o formato dos dados e onde está a mídia?	Transcrições e corpora de conversas têm seus próprios conversores
Você já tem anotações?	potato import lê catorze formatos e escreve um projeto executável
O que precisa sair no final?	Vinte e nove formatos de exportação. Verifique o destino antes de alguém anotar
Quem executa após o handover e por quanto tempo?	Decide hospedagem, logins e a lista de permissões

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 cobre todos os três, incluindo a única decisão que mais importa: se as anotações importadas são pré-anotações que um humano corrige, ou trabalho --seed-user que marca o item como concluído.

Briefings subespecificados

Leia references/asking-the-experimenter.md antes de escrever a config. Decida você mesmo quando errar for barato; pergunte quando for caro, irreversível ou não for da sua conta — a unidade de anotação, o orçamento de anotadores, o texto do consentimento e qualquer coisa envolvendo pessoas identificáveis.

Nunca espere por uma resposta. Construa com suposições declaradas, escreva as perguntas em QUESTIONS.md junto com algo que funcione e diga qual suposição você revisitaria primeiro.

Procure pelo recurso antes de construir um

O Potato tem mais embutido do que uma referência de config torna óbvio. O erro caro não é um nome de tipo inventado — a validação pega isso. É montar manualmente algo que o Potato já faz.

references/modes-and-subsystems.md é a tabela de roteamento do que um pesquisador disse para o bloco que faz isso: QDA e codebooks, modo solo, salas, adjudicação, fluxo de revisão, sessões, pocket, aprendizado ativo, juízes, crowdsourcing, publicação, telemetria. Verifique antes de escrever um esquema que pareça um workaround.

Ele abre com os sete clusters — material, a resposta, unidade, pessoas, confiança, ajuda de modelo, saída — que é o mesmo mapa que a entrevista oferece como menu. Execute contra o briefing como uma lista de verificação: os clusters que um briefing nunca menciona são onde um pesquisador tem mais probabilidade de estar perdendo algo que desejaria. Levante no máximo dois deles, e apenas onde eles importam; o resto vai para QUESTIONS.md.

O cluster que os pesquisadores perdem com mais frequência é a resposta. Eles pedem radio e likert e param, e soft_label, range_slider, semantic_differential, constant_sum e confidence nunca são alcançados.

Projetando

references/designing-a-task.md cobre as sete decisões por trás de cada tarefa: a unidade, as perguntas, o formato de resposta, anotadores por item, ordem dos itens, controle de qualidade e as fases de cada lado.

A tabela de roteamento cobre os pedidos comuns e para. Onze tipos não são nomeados em nenhum lugar além da referência gerada, então eles nunca são alcançados: multirate (dez avaliações em uma escala, não dez esquemas likert), hierarchical_multiselect (uma taxonomia, recolhida, com pesquisa), select, soft_label (uma distribuição em vez de uma escolha forçada), range_slider, semantic_differential, conjoint, card_sort, extractive_qa, multi_document_event, code_review. Cada um tem um exemplo funcional e uma linha em designing-a-task.md.

Dois que são fáceis de errar e caros para descobrir tarde:

• O formato de resposta decide a métrica de concordância. O Potato a escolhe a partir do tipo de esquema. Uma classificação de 1 a 5 armazenada como radio é pontuada como não ordenada, então "1 vs 2" e "1 vs 5" contam o mesmo. Isso é um erro de medição, não cosmético. Tabela em references/assignment-and-agreement.md.
• num_annotators_per_item define o alvo, max_annotations_per_user define o que uma pessoa realmente vê. Se não for definido, o limite é a contagem de itens, então todos recebem o corpus inteiro. Defina abaixo disso e os anotadores simplesmente param cedo, sem nada para dizer por quê. automatic_assignment.instance_per_annotator parece a chave para isso e não é lida.

O registro de design e o custo

Dois arquivos ao lado da config, nenhum dos quais a config pode conter:

• DESIGN.md — a unidade de anotação e por quê, por que cada formato de resposta, anotadores por item, para que serve o controle de qualidade e uma lista separada e explícita das escolhas que você assumiu porque o briefing não disse. Esse último parágrafo é o que torna o documento digno de ser aberto.
• QUESTIONS.md — o que você não conseguiu decidir. Nunca espere por uma resposta; entregue algo que funcione junto com a pergunta.

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

relata quantos anotadores o design precisa, quanto tempo cada um está trabalhando, horas totais e um custo. Execute antes das instruções serem escritas — é o lugar mais barato para pegar um design que ninguém pode pagar.

references/recording-decisions.md tem o modelo de DESIGN.md e o que move a estimativa.

Comece de um design publicado

Antes de escrever um esquema a partir de uma lista de campos, procure por um que alguém já executou:

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

O Potato Showcase tem 440 designs de tarefas de anotação, a maioria construída a partir de um artigo publicado, com conjuntos de rótulos reais e texto de perguntas reais — e 281 deles carregam instruções escritas. Nenhum deles tem um bloco phases, uma página de consentimento ou uma rodada de treinamento, então pegue as perguntas de lá e o estudo ao redor delas de worked-example.md. references/finding-a-design.md cobre o que mudar antes de reutilizar um.

Escrevendo as instruções

A config tem um validador por trás. O texto que um anotador lê não tem, e é daí que vem a maior parte da discordância em um conjunto de dados finalizado.

references/writing-guidelines.md cobre as quatro superfícies onde o texto voltado ao anotador pode viver (a fase instructions, o banner annotation_instructions, annotation_codebook_url e a description por esquema), o que uma definição de rótulo deve conter para resolver uma discussão, regras de desempate, exemplos trabalhados incluindo os limítrofes, e iterar as diretrizes a partir das discordâncias do piloto. examples/advanced/long-guidelines/ é um modelo funcional de tudo isso.

Duas coisas para acertar sem ler mais:

• O banner não é o codebook. annotation_instructions fica em cada página, e...