maestro/docs/tools/checklist.md

チェックリスト系ツール（CreateChecklist / CheckItem / GetChecklist）

複数アイテム（ファイル、ページ、URL等）を順次処理するときの進捗管理に使う。 「1件処理→即CheckItem」のループを厳守すること。

基本ワークフロー

1. CreateChecklist({ name: "ocr-pages", items: ["page-001.png", "page-002.png", ...] })
2. for each item:
     a. アイテムを1件処理する（OCR、ダウンロード、加工など）
     b. CheckItem({ name: "ocr-pages", item: "page-001.png", status: "done" }) を即呼ぶ
     c. 次のアイテムに進む
3. GetChecklist({ name: "ocr-pages" }) で漏れがないか確認

ステータス

• done — 正常完了
• failed — 処理失敗（後で再試行・スキップ判断）
• skipped — 意図的にスキップ（理由を summary に書く）

厳禁パターン

❌ 複数アイテムをまとめて処理してから後でまとめて CheckItem を呼ぶ

• 途中でクラッシュ・中断したときに進捗が失われる
• アイテム順がブレる
• レビュー時に作業順序が追えない

✅ 1件処理 → 即 CheckItem → 次のアイテム を1件ずつ繰り返す

ファイルの保存場所

logs/checklists/{name}.json に保存される。再開時に GetChecklist で前回の状態を取り出せる。

いつ使うべきか

• 同種のアイテムを 3 件以上順次処理するとき
• 処理が長時間にわたり、中断・再開がありえるとき
• 後で何が処理済み／失敗かを振り返る必要があるとき

逆に、1〜2件しかない・1ステップで終わる処理には不要。