scenario-refine-loop

シナリオ改善ループ

概要

エージェントが生成物のQAに失敗するパターンは、最初の生成結果を受け入れるか、プロンプト全体を書き換えて予算が尽きるまで再生成するかの二つです。どちらも、同じ二つの成果物を省いています。文書化された評価基準と診断です。収束するループは、生成前に評価基準を用意し、少量をまとめて生成し、アセットごとに判定を記録し、失敗には最も低コストで的を絞った修正を適用し、ラウンド数に上限を設けます。接続方法とコアループについては、scenarioスキルを参照してください。批評ツールの契約については、scenario-asset-analysisを参照してください。ベースラインの規律については、scenario-consistencyを参照してください。ここで名前を挙げた関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で実行する場合は、ツールスキーマに基づいて進め、不足があることを明記してください。

クイックリファレンス

手順	実行内容
1. 評価基準	生成する前に、概要を閲覧者が合否を判定できる項目（「被写体が無地の背景の中央にある」など）に変換します。好みを表す言葉は使いません
2. 生成	評価基準の各項目を判定できる、スキーマが提供する最も低コストなサイズまたは品質ティアで、レシピをテストできる最小のバッチを生成します。コストが重要な場合は dry_run を使います
3. 評価	asset_analyze：1回につき最大10枚の画像を対象に、評価基準を盛り込んだ1つの指示と、画像ごとに固定した出力形式を指定します
4. 修正	不合格の項目ごとに、その項目に対処する最も低コストな修正方法を割り当てます（下表）
5. 停止	すべて合格したラウンドで完了です。3ラウンド連続で合格がない場合、または異なる修正を適用しても同じ項目が2回不合格になった場合は、再試行せずに報告します

基準がタスクの評価基準ではなく、設定済みのブランド概要であり、チームのQuality Gateアドオンが有効な場合は、代わりに asset_quality_gate_run で画像を評価します。その reasons と suggestions は修正方法の表に直接反映できます（scenario-quality-gate。ゲートがない場合は、この asset_analyze の手順にフォールバックします）。

修正方法の割り当て（低コストなものから順）：

評価結果	修正
成果物に局所的な欠陥が1つある	その領域をマスクしてインペイントします。スキーマに mask フィールドがない場合は、変更点を1つだけ明記した指示で成果物を編集します（scenario-image）
全体の仕上がり（グレーディング、色合い、トリミング）が不適切	再生成ではなく、決定論的なツール処理を行います（scenario-image-editing）
内容、構図、またはレンダリングされたパレットが不適切	差分を示す節を編集し、承認済みのベースラインから再実行します
アイデンティティまたはスタイルにずれがある	列挙内容を明確にし、参照を追加するか、参照の役割を変更します（scenario-consistency）
すべての項目が不合格	モデルを変更します。recommend で機能に応じたモデルを再検索します（search はモデル名、プライベートモデル、または image-upscale のようなタグで絞り込んだ候補を探すためのものです）。プロンプトは維持します

ラウンドごとに変更する変数は1つだけにします。プロンプト、参照、モデルを一度に変更すると、改善の要因を特定できません。そのため、次に失敗した場合は最初からやり直します。

ループの一貫性を保つ2つのルール

• 判定は好みではなく、評価基準を根拠にします。 批評役には、画像ごとに順番に次の形式で回答するよう指示します。 <index>: pass|fail, <the failed line>. 「もっと良くできる」は判定ではありません。ブリーフではなく改善を追い求めるループは、その方向性を際立たせている要素をまさに削ぎ落とし、ありきたりな出力へと収束します。
• 再生成は直近の試行ではなく、必ずベースラインから行います。 修正時は、承認済みの参照画像とプロンプトから再実行します。出力を次の出力につなげていくと、ずれが積み重なります（その理由はscenario-consistencyで説明されています）。

実例：ブリーフに沿って4つのアイコンを作成

1. ブリーフから5項目の評価基準を作成します。単一のオブジェクト、中央配置、無地の背景、パレットは#2A9D8Fと#E9C46Aのみ、テキストなし。
2. scenario-imageごとに、model_runを1回ずつ実行して4つ生成し、その後jobs_waitを実行します。
3. 4つすべてのIDをimagesに指定し、評価基準と形状の指示を含めてasset_analyzeを1回呼び出します。回答はテキストアセットとして生成されるため、asset_downloadでダウンロードして判定を確認します。
4. 2つが不合格です。アイコン2はパレットから外れていますが、これは仕上げではなく描画内容の問題です。プロンプト内で16進コードを固定するよう差分の指示を編集し、ベースラインから再実行します。アイコン4にはにじんだエッジが1か所あります。その角をマスクしてインペイントします。アイコン1と3は手を加えず、そのまま納品します。
5. 修正の実行をjobs_waitで待ち、その後、新しい2つのアセットだけをバイト単位で同一の指示で再評価します。問題がなければここで終了し、採用するものをコレクションに保存します（scenario-asset-analysis）。

よくある間違い

• チャットでasset_displayをざっと見て判断すること。記録されない印象は蓄積されませんが、判定は蓄積されます。
• 画像の改善や修正をasset_analyzeに依頼すること。このツールが返すのはテキストのみです。修正はすべて新たな実行で行います。
• 1つ失敗しただけでバッチ全体を再生成すること。アイテムごとに振り分けます。
• バッチを見てから評価基準を書くこと。その場合、バッチの欠点が基準に反映されてしまいます。
• 上限を設けずにループを実行すること。失敗したジョブは返金されますが、満足できない結果は返金されません。実行自体が報告するコストを基にラウンドを制御してください（dry_runで次のラウンドの料金を事前に確認できます）。usageの合計は反映が遅れるため、実行中の判定には使えず、実行後のレポートに回答します。
• 同じモデルで同じ基準を3回目も試すこと。異なる2つの修正で2回失敗したなら、それは運が悪かったのではなく、そのモデルについての証拠です。