Potato アノテーションタスク
Potato タスクは、1 つの YAML 設定ファイルと 1 つのデータファイルで構成されます。構築には 3 つの作業があります。何をどのように尋ねるかを決定し、それを正しく記述し、ログイン画面からスタディの終了まで実際のユーザーが操作するのを確認するまで実行することです。2 つ目の作業にはバリデータがあるため、そこだけを始めて終わらせたくなるのは当然です。しかし、スタディが実際に壊れる場所は、最も可能性が低い場所です。
プロジェクトルートに AGENTS.md があれば、それを読んでください。これには、このドキュメントに加えてプロジェクトの規約が記載されています。
タスクの説明なしで呼び出された場合
誰かが /potato-tasks と入力しましたが、会話に簡単な説明がありません。構築を開始せず、「何を作成しますか？」と尋ねないでください。Potato を使用したことのない研究者は、その質問に有意義に答えることはできません。
1 文の説明を求め、そこからデザインを提案し、推測する必要があった点だけを確認してください。references/interviewing.md は質問集です。冒頭の質問、4 行の提案、次にモダリティ、ユニット、応答形式、アイテムあたりのアノテータ数、品質管理、エクスポート先、ログインできるユーザーをカバーする 2 ラウンドの多肢選択、そして 7 つの機能クラスターをメニューとして提供し、選択されたものだけを詳細に掘り下げる 3 回目のラウンドが含まれます。
2 つの重要な点を強調します。データのモダリティを毎回尋ねてください。これにより、表示方法、スキームファミリー、メディアの場所を示すファミリー内キーが決まります。間違えると、静かに間違った結果になります。また、フェーズ (consent、training、prestudy) を提案しないでください。これらはプロトコルの決定であり、ほとんどのタスクでは不要です。必要な研究者は、それを必要としていることを認識しています。
前提を明示して構築し、待たないという基本ルールは引き続き有効です。これは、インタビューで推測できる 材料 が得られた時点で適用されます。コンテキストがまったくない場合、構造化された 4 つの質問をすることは、あなたができるどんな推測よりも研究者にとって迅速です。
Potato のインストール
このスキルの大部分は potato コマンドを駆動し、Potato のレジストリをインポートします。パッケージがコマンドを実行する環境にインストールされていなければ、どちらも機能しません。
potato --version || pip install potato-annotation
scripts/walk_task.py のブラウザウォークには、さらに Playwright が必要です。
pip install 'potato-annotation[preview]' && playwright install chromium。
このスキルのスクリプト
以下の 7 つの手順は、手動で行うには長く、繰り返し実行するものなので、スクリプトとして提供されています。これらはこのファイルと同じディレクトリの scripts/ にあります。
| スクリプト | 機能 |
|---|---|
boot_and_check.py config.yaml -p 8000 | 起動し、200 応答を待ち、設定されていても何もロードされていないすべての機能を報告します |
walk_task.py --url … --config … --task-dir . | アノテータを登録し、スタディ全体をウォークスルーし、回答が user_state.json に到達したことを確認します |
estimate_effort.py config.yaml --rate 15 | アイテム数、必要なアノテータ数、各アノテータの作業時間、総時間とコストを計算します |
find_design.py --type span --with-instructions | Potato Showcase の 440 の公開済みタスクデザインを検索します |
handover.py config.yaml --confirm | テスト中に作成したアカウントを削除し、RUNNING.md を書き込みます |
check_ui.py --url … --config config.yaml | すべてのページをレンダリングし、フォールド以下のスキーム、空のメディア、空の選択タイル、回答用のコントロールがないスキーム、何も収集しない回答、ウィジェットが報告したエラー、キーバインドの競合、表示されなかったスキームを報告します。--phase poststudy はウォークが到達できないページを測定します |
study_status.py --url … --task-dir . | 進行状況、アノテータごとのペース、一致度、および実行中のスタディの問題を報告します |
各スクリプトは --help を受け付け、boot_and_check、walk_task、check_ui、study_status は結果を読むためではなく、処理するために --json を受け付けます。
ループ
potato validate config.yaml --strict # 構造と未知のキーのチェック
potato preview config.yaml # フォームが宣言する内容の確認
potato preview config.yaml --screenshot out.png # 1 ページをレンダリングし、ブラウザエラーを報告
nohup potato start config.yaml -p 8000 > server.log 2>&1 & # 起動し、ログを読む
最初の 3 つのコマンドはすぐに戻ります。4 つ目は戻りません。バックグラウンドで実行し、curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/ で 200 応答をポーリングし、server.log を読みます。
potato --help は、start フラグの下にその他のコマンドとしてこれらを一覧表示します。各コマンドには独自の文法があるため、potato validate --help と potato preview --help でオプションを確認できます。
各ステップで異なる種類の障害をキャッチ
| ステップ | キャッチするもの | 見逃すもの |
|---|---|---|
validate --strict | 必須キーの欠落、不正な型、1～2 レベルの未知のキー | サイドファイル、フェーズタイプ、スキームエントリ内のもの |
preview | 設定が宣言するスキームとキーバインディング | それらのレンダリングの可否 |
preview --screenshot | キャッチされなかった例外、console.error、1 つのページでの失敗したリクエスト | 900px 以下のすべて、すべての条件付きウィジェット、他のすべてのフェーズ |
| 起動 + ログを読む | サイドファイルの形式、フェーズのアセンブリ、サブシステムの初期化 | 見た目 |
| ブラウザで駆動 | 実際のスタディ | — |
最後の 2 つをスキップすると、検証は通り、スクリーンショットはきれいでも、トレーニングフェーズ、アテンションチェック、アイテムの 3 分の 1 が失われるタスクが出荷されてしまいます。
早期に起動する
起動ログが本当のバリデータです。validate が開かない設定の部分が実際に機能したかどうかを報告する唯一のものです。
grep -E "ERROR|Traceback|Loaded [0-9]+|phase|missing required" server.log
トレーニングとアテンションチェックを含むタスクの正常な起動では、Loaded 3 training instances と Loaded 2 attention check items が表示され、フェーズについては何も表示されません。それ以外は、設定されていてオフになっている機能です。
設定がパースされたらすぐに起動してください。インターフェースが完成する前、指示が書かれる前です。running-a-task.md には、バックグラウンド実行のレシピ、準備完了チェック、ログ行のテーブル、編集後に削除する生成ファイルが含まれています。
3 つのサイレント障害モード
有効は実行中と同じではない。 attention_checks.enabled: true で不正な形式のアイテムファイルがある場合、1 つの警告がログに記録され、Loaded 0 attention check items となり、品質管理がオフのままスタディ全体が実行されます。設定ではなく、カウントを確認してください。
--strict はすべてに到達するわけではない。 最上位とほとんどのブロックの 1 レベル内をチェックします。phases、surveyflow、quality_control、crowdsourcing、publish、automatic_assignment、ui、ui_config、annotation_schemes の各エントリ、または instance_display.fields の内部はチェックしません。key_value の代わりに key_binding と記述しても、検証は正常に終了し、何も実行されません。存在しないフェーズ type: も同様です。
スクリーンショットはビューポートであり、ページ全体ではない。 --screenshot は 1280×900 で書き出します。指示バナーがあるタスクの場合、それはバナーとアイテムの半分であり、質問は表示されません。「PNG を確認し、次のボタンがフォールドより上にあることを確認する」というアドバイスは、このツールだけでは実行できません。ブラウザを駆動し、full_page=True でスクリーンショットを撮ってください。
既存のものを確認する
簡単な説明とデータファイルは一般的なケースであり、唯一のケースではありません。設計を始める前に 4 つの質問をしてください。それぞれにコマンドがあり、設定を書いた後に発見するのはコストがかかるからです。
| 質問 | 理由 |
|---|---|
| データの形式は何ですか？メディアはどこにありますか？ | トランスクリプトと会話コーパスには独自のコンバーターがあります |
| 既にアノテーションはありますか？ | potato import は 14 の形式を読み取り、実行可能なプロジェクトを書き出します |
| 最終的に何を出力する必要がありますか？ | 29 のエクスポート形式があります。誰かがアノテーションする前にターゲットを確認してください |
| 引き渡し後、誰が、どのくらいの期間実行しますか？ | ホスティング、ログイン、許可リストを決定します |
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 は、これらすべてと、最も重要な 1 つの判断をカバーしています。インポートされたアノテーションが、人間が修正する事前アノテーションなのか、アイテムを完了済みとしてマークする --seed-user の作業なのかです。
仕様が不十分な場合の対応
設定を書く前に references/asking-the-experimenter.md を読んでください。間違えてもコストがかからない場合は自分で判断し、コストが高い場合、取り返しがつかない場合、または自分が判断すべきでない場合（アノテーションの単位、アノテータ予算、同意文、特定可能な人物に関するものなど）は質問してください。
回答を待たないでください。前提を明示して構築し、質問を QUESTIONS.md に書き、実行可能なものと一緒に配置し、どの前提を最初に見直すかを示してください。
機能を自分で作成する前に、既存のものを探す
Potato には、設定リファレンスからは明らかでない、多くの組み込み機能があります。コストのかかるミスは、存在しないタイプ名を発明することではありません。検証がそれをキャッチします。コストがかかるのは、Potato が既に持っている機能を手動で組み立てることです。
references/modes-and-subsystems.md は、研究者の発言からそれを処理するブロックへのルーティングテーブルです。QDA とコードブック、ソロモード、ルーム、アジャッジケーション、レビューワークフロー、セッション、ポケット、アクティブラーニング、ジャッジ、クラウドソーシング、パブリッシング、テレメトリー。回避策のように思えるスキームを書く前に、必ず確認してください。
このドキュメントは、7 つのクラスター（資料、回答、単位、人、信頼、モデル支援、出力）で始まります。これは、インタビューがメニューとして提供するものと同じマップです。これをチェックリストとして簡単な説明と照らし合わせて実行してください。簡単な説明で言及されていないクラスターは、研究者が欲しい何かを見逃している可能性が最も高い場所です。そのうち最大 2 つを、それらが重要である場合にのみ提起してください。残りは QUESTIONS.md に入れてください。
研究者が最も確実に見逃すクラスターは回答です。彼らは radio と likert を要求して止まります。soft_label、range_slider、semantic_differential、constant_sum、confidence には決して到達しません。
設計
references/designing-a-task.md は、すべてのタスクの背後にある 7 つの決定をカバーしています。単位、質問、応答形式、アイテムあたりのアノテータ数、アイテムの順序、品質管理、および両側のフェーズです。
ルーティングテーブルは、一般的な要求とその停止点をカバーしています。 11 のタイプは生成されたリファレンスにのみ名前があり、したがって決して参照されません。multirate（10 個の likert スキームではなく、1 つの尺度での 10 個の評価）、hierarchical_multiselect（折りたたまれた、検索可能な分類法）、select、soft_label（強制選択ではなく分布）、range_slider、semantic_differential、conjoint、card_sort、extractive_qa、multi_document_event、code_review。それぞれに動作する例と designing-a-task.md の行があります。
間違えやすく、後になって発見するのにコストがかかる 2 つの点：
- 応答形式が一致度メトリックを決定します。 Potato はスキーマの種類からそれを選択します。1～5 の評価が
radioとして保存されると、順序なしとしてスコアリングされるため、「1 vs 2」と「1 vs 5」は同じとカウントされます。これは測定エラーであり、外観上の問題ではありません。表はreferences/assignment-and-agreement.mdにあります。 num_annotators_per_itemは目標を設定し、max_annotations_per_userは 1 人が実際に表示するものを設定します。 未設定の場合、上限はアイテム数であるため、全員がコーパス全体を提供されます。それを下回る値に設定すると、アノテータは理由もなく早期に停止するだけです。automatic_assignment.instance_per_annotatorはこれのためのキーのように見えますが、まったく読み取られません。
設計記録とコスト
設定ファイルの隣にある 2 つのファイル。設定ファイルはどちらも保持できません。
DESIGN.md— アノテーションの単位とその理由、各応答形式の理由、アイテムあたりのアノテータ数、品質管理の目的、そして、簡単な説明に記載がなかったために前提とした選択肢の、明確で別個のリスト。最後の段落が、このドキュメントを開く価値のあるものにしています。QUESTIONS.md— まったく決定できなかったこと。回答を待たないでください。質問と一緒に実行可能なものを出荷してください。
python .claude/skills/potato-tasks/scripts/estimate_effort.py config.yaml --rate 15
は、設計に必要なアノテータの数、各アノテータの作業時間、総時間とコストを報告します。指示が書かれる前に実行してください。これは、誰も支払えない設計を発見するための最も安価な場所です。
references/recording-decisions.md には、DESIGN.md のテンプレートと、見積もりを変更するものがあります。
公開済みの設計から始める
フィールドリストからスキームを書く前に、誰かが既に実行したものを探してください。
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
Potato Showcase には 440 のアノテーションタスク設計があり、そのほとんどは公開された論文に基づいて構築され、実際のラベルセットと実際の質問文があります。そして、そのうち 281 件には書面による指示があります。それらのどれにも phases ブロック、同意ページ、トレーニングラウンドはありません。したがって、質問はそこから、スタディの残りの部分は worked-example.md から取得してください。references/finding-a-design.md では、再利用する前に何を変更すべきかを説明しています。
指示の作成
設定にはバリデータがあります。アノテータが読むテキストにはバリデータがなく、完成したデータセットの不一致のほとんどはここから発生します。
references/writing-guidelines.md は、アノテータ向けテキストが配置される 4 つのサーフェス（instructions フェーズ、annotation_instructions バナー、annotation_codebook_url、スキームごとの description）、ラベル定義が議論を解決するために含める必要があるもの、タイブレークルール、境界例を含む実例、およびパイロットの不一致からガイドラインを反復する方法をカバーしています。examples/advanced/long-guidelines/ は、そのすべての実用的なモデルです。
これ以上読まなくても正しく理解できる 2 つのこと：
- バナーはコードブックではありません。
annotation_instructionsはすべてのページに表示されますが、...
[以下、省略]