Sheets to playbook(シートからプレイブックへ)
リポジトリ: ingest/ingest.py を含むフォルダ(Claude Code がクローン先で開かれている場合は現在のプロジェクト)。以下のすべてのパスは、このフォルダからの相対パスです。ステージ 3 の前に ingest/RAW_FORMAT.md を読んでください。そこには文字起こしの形式とプレイブック作成のルールが記載されています。
目標は、何も作り出さずに、その場でのスピードを実現することです。ウェブサイトのすべての行は、写真またはボイスノートに由来している必要があります。ingest.py verify がこれを強制します。
各ステージで何をしているのか、1~2行でユーザーに伝えてください。以下の各ステージの所要時間は、約12テーブルある場合のおおよその目安です。
当日の前に、playbook.config.json に主催者の名前とプレイブックのウェブアドレスを設定してください(コミットメントカードのQRコードはそこを指します)。デフォルトのニュートラルな設定のままの場合はその旨を伝えてください。ただし、そのまま作業を進めて構いません。設定で変わるのは名前と色だけで、内容は変わりません。verify、draft、publish で --config <file> を指定すると、別の設定ファイルが使用されます。
1. 準備(1~2分)
python3 ingest/ingest.py prepare "<folder>"
python3 ingest/ingest.py transcribe # フォルダにボイスノートがある場合のみ;バックグラウンドで実行
prepare は runs/ の下に新しい実行を作成し(runs/latest はそれを指すようになります):写真を正しい向きに回転、HEIC を変換、写真ごとにシャープネススコアを計算、詳細確認用の2x2タイル、contact/ にコンタクトシートを作成、ボイスノートを16kHz WAV に変換します。transcribe はローカルの Whisper(small.en、一度ダウンロードすればオフラインで動作)を使用し、各ノートの冒頭「Table seven…」からテーブル番号を推測します。
2回目のバッチ(最初の半分が進行中に、さらに写真やカードが追加された場合):python3 ingest/ingest.py prepare "<folder>" --into <run> で同じ実行に追加します。新しいIDは最後のものから続けて(P022…)、ラベルと生ファイルは保持され、すでに実行に含まれているファイルはスキップされます。その後、新しいIDのみラベル付けします。
2. ラベル付けとカバレッジの確認(約5分;最初にこれを行ってください。時間的に重要です)
すべてのコンタクトシート(contact/sheet-*.jpg)を確認し、サムネイルが不明瞭な場合は view/ の写真を確認してください。実行フォルダに labels.json を記述します:
{"photos": {"P001": {"table": 7, "sheet": "S2"}, "P014": {"kind": "stubs"}, "P020": {"kind": "other", "note": "部屋の写真"}},
"audio": {"A01": {"table": 7, "by": "speech"}}}
- 各シートには、下部の隅に印刷されたコード(S1、S2、S3、SS)と印刷された見出しがあります。テーブル番号はテーブルリーダーが手書きで、右上の丸とコードの横(
S2 · Table 7)に記入されます。キットのデフォルト見出し:S1「サポートはどこで行き詰まるか?」、S2「役に立ったこと、役に立たなかったことは?」、S3「今、人々は何を試せるか?そしてどのように定着させるか?」、SS サイドシート「良いことを聞いた?ここに書いて。」(引用・質問・リソース)。主催者が質問を変更した場合は、印刷されたコードに従います。丸と隅の番号が一致しない場合は、ペンの色と内容で判断します。そのテーブルの他のシートも確認してください。 transcribeがすでに記入した音声ラベルは、文字起こしの最初の行と照合した上で保持します。- 同じコードとテーブル番号を持つ2つの異なるシート(
statusは複数の写真を持つシートをリストアップします。これらを確認してください):国と内容が重複している場合は、1つのテーブルが2枚のコピーを使用したものです。両方に同じ番号をラベル付けし、読み取り担当者が両方を文字起こしします。明らかに2つの別テーブルの場合は、2つ目のテーブルに91以降の予備番号を割り当て、"note": "wrote 22; second table"を追加し、その旨をユーザーに伝えます。どちらのテーブルを「2つ目」としても構いません。1つを選び、両方についてメモ(セクター、ペンの色)を記述して、レビューで区別できるようにします。 - テーブル番号が写っていないクローズアップ(タリーボックスのみなど):一致するシートでラベル付けし、
"note": "table inferred from <一致したもの>"を追加します。 - 1枚の写真に2枚のシート(並べてピン留めされている):
"sheet": ["S2", "S3"]とラベル付けし、statusで両方としてカウントされるようにします。そして、読み取り担当者がどちらがどの半分か分かるようにnoteにその旨を記載します。 prepareはフレーム内で上下逆になった写真を回転できません(回転フラグがありません)。読み取り担当者は対応できますが、noteにその旨を記載します。カードの写真はシートよりもシャープネススコアが低くなります(プレーンなカード、細いペン)。したがって、再撮影を依頼する前に、view/で BLURRY? と表示されたカードを確認してください。
次に python3 ingest/ingest.py status を実行し(テーブルが12なかった場合は --tables <n> を追加)、欠落(MISSING)またはぼやけた(BLURRY)シートがあればすぐにユーザーに伝えてください。コンタクトシートは LOW-RES(メッセージングアプリ経由で転送されたもの。文字が大きければ問題なし)と DARK(通常は読み取れます)もタグ付けします。これらについては言及しますが、再撮影の必要はありません。理想的には、このチェックはシートがまだ壁に貼ってあり、再撮影可能なうちに行います。
3. 各テーブルの文字起こし(並列実行、約5~10分)
テーブルごとに1つのサブエージェントを生成し(Agent ツール、general-purpose、バックグラウンド、すべて1つのメッセージ内)、カードの切り株がある場合はそのためのサブエージェントも生成します。モデルをダウングレードしないでください。手書き文字の精度が重要な場面です。各プロンプトは独立して動作し、以下を含める必要があります:
- リポジトリの絶対パス、実行フォルダ、テーブル番号、その写真ID(
view/<id>.jpgとmanifest.jsonにリストされたタイル)、およびボイスノートの文字起こしパス(ある場合)。 - 「
ingest/RAW_FORMAT.mdのステージ 1 を読み、それに正確に従ってください。実行フォルダにraw/T<nn>.jsonを記述し、その後python3 ingest/ingest.py verify --run <run>を実行して、ファイルに関するエラーがあれば修正してください。返信には短いサマリー(シートごとのアイテム数、すべてのunclearエントリ、省略したすべての取り消し線の単語)を含めてください。」 - 切り株の場合:ステージ 1 の最後に説明されているように
raw/commitments.jsonを記述します。カードのオプションの名前と組織の行をそのまま書き、そこでのカードルール(破れていないカード、サインオフ、2枚の写真にまたがる1枚のカード)に従います。
サブエージェントの実行中に、自分でボイスノートの文字起こしを読んで、執筆前に会場の状況を把握してください。
4. プレイブックの執筆(約10~15分)
RAW_FORMAT.md のステージ 2 に従います。<run>/session.json を meta.status: "draft" で記述します。meta は examples/session-template.json から開始し、イベントの詳細(イベント名、日付、会場)をユーザーから教えてもらって入力します。実際の参加者数がわかっている場合は people に設定します。これらは決して推測しないでください。テンプレートのままのフィールドはそのままにし、ユーザーにリストアップします。
5. 検証、修正、レビューパックの作成
python3 ingest/ingest.py verify --links
python3 ingest/ingest.py draft # <run>/playbook-draft.html:点線ボックス=ギャップ、タグ=ソース
python3 ingest/ingest.py review # <run>/review.html:すべてのアイテムを写真と並べて表示
すべての エラー(トレースできない行、逸脱した引用、残った名前など)を修正し、verify がパスするまで再実行します。警告は人間のレビュー担当者向けです。報告はするが、隠蔽しないでください。
次に、ユーザーにレビューサマリーを提供します:課題とマージされたテーブル、すべての unclear 読み取りとその写真ID、読み取り担当者が省略したすべての取り消し線の単語、未使用の生アイテム、リンクの問題、そしてグループ化の方法に確信が持てなかったものを含めます。review.html には各読み取り担当者のメモと、各テーブルの「このテーブルには誰がいますか?」の集計が表示されます。ユーザーのために review.html と playbook-draft.html を開きます。
不確かな単語が多い場合? レビューアプリは review.html を上から下まで読むよりも高速です:python3 tools/review/make_review.py --run <run> で <run>/review/index.html が作成され、不確かな読み取りごとに1枚のカードと手書き部分のクローズアップが表示されます。ユーザーが各単語を確認/修正し、決定ファイルを保存し、python3 tools/review/apply_review.py --run <run> <decisions.json> で読み取り結果を生ファイルと session.json に書き戻します。その後、verify と draft を再実行します。不確かな単語以外の質問(取り消し線かどうかのチェックマーク、2つのテーブルをマージするかどうか、リソースに名前を付けるかどうか)は、アプリをビルドする前に <run>/review/extra.json にチェックと判断として記録します。apply_review.py は、それらに対する回答を <run>/review/to-action.md にリストアップし、あなたが対処します。tools/review/README.md を参照してください。
6. 公開(人間がドラフトを確認した後)
レビュー担当者の修正を session.json に適用し、meta.status を "final" に設定してから、以下を実行します:
python3 ingest/ingest.py publish --links # トレースできないものや空のセクションがある場合は拒否
これにより data/session.json と playbook/index.html が書き込まれます。playbook/ フォルダは静的サイトです。どこかにデプロイするのは別のステップなので、最初に確認を取ってください。ページ内のすべてのリンクはスクリプトで処理されるため、ディスクから直接開いても機能します。
禁止事項
- 一般的な知識から、たとえ「役立つ」コンテキストでも、内容を追加しないこと。空欄の方が、作り出したものより優れています。
- 単語を黙って推測しないこと。
[?word]または[illegible]を使用し、それをリストアップすること。 - 公開ページに個人の名前や雇用主の名前を記載しないこと。ただし、本人がカードに書いたコミットメントの自分の名前と組織は除きます(
verifyはこれらをカードと照合します)。 verifyがパスし、人間がドラフトを読んでいない状態で公開しないこと。
作業後
写真とボイスノートには名前や顔が含まれている場合があります。プレイブックが確定したら、runs/*/audio、元の写真とボイスノート、および主催者が保持しないことに同意したその他のものを削除するようユーザーに注意してください。