ce-optimize

測定可能な目標を最適化する

成果： 指定した目標に対する改善が確認され、ディスク上のログとともに optimize/<spec-name> ブランチに反映されています。完了時にはユーザーが引き継ぎます。

意図： 次のアクションは、実装内容を変える可能性がある最も低コストのステップです。実装を探す前に、指定されたワークロードのコストを明らかにします。プロファイルを必須とせず、スコアを付けたバリアントの候補群を探して保持します。

完了条件： 停止基準を満たし、宣言された必須目標をすべて満たすか、先に別の停止条件を満たしています。最終状態がディスクに書き込まれ、検証済みで、完了後の選択肢がユーザーに提示されています。合格できないチェックで実行を停止した場合は、妨げとなった内容を伝えます。

このスキルを呼び出すと、リポジトリの読み取り、ハーネスの構築、および（フェーズ 1 の承認ゲート後の）optimize/<spec-name> 上での分離実験とコミットの保持／取り消しが許可されます。支出に上限がない場合、新しい依存関係が発生した場合、完了時にプッシュまたは PR の作成を行う場合、あるいは完了後の選択肢からユーザーだけが選べる場合は確認してください。これらの制限内で次の実験を行う際に、再度確認する必要はありません。

独立した呼び出しと実行依頼は 1 回の応答にまとめ、実際に依存関係がある場合にのみ順序立てて実行します。

調査結果、ユーザーの判断、阻害要因、結果を報告してください。作業が長引く場合は、判明したことと残っていることを適宜共有してください。通常の準備やフェーズ間・バッチ間の移行については、逐一知らせる必要はありません。現在の判断に影響しない限り、費用の記録はログと最終報告にまとめてください。

目標、根拠、判断を、通常のタスク用語で説明してください。「ハーネス」などのワークフロー上の用語は、ユーザーが仕組みについて尋ねた場合を除き、成果物の中で使用してください。期間や費用が不明な場合は、不明と伝えてください。上限は制限であり、予測ではありません。

ステップは実行して初めて完了します。測定、実行依頼、チェックポイントについて説明するだけでは、実行したことにはなりません。対象範囲内の作業が説明だけの状態で残っている間は、ターンを終了しないでください。未完了の作業を次のターンに持ち越せるのは、検証済みのチェックポイントがあり、references/persistence.md の定義に従って、自動で再開する手段に上限があるか、手動再開を明示して引き継ぐ場合に限ります。

対話方法

現在のツール一覧にある、ホストのブロッキング式質問ツールを使用してください（ホスト固有の名前ではなく、機能で照合してください）。現在のツール一覧に存在することは、そのツールが利用可能である証拠です。利用可能かどうかを調べるために、ユーザー向け質問ツールを呼び出してはいけません。一致するツールが一覧にあるものの未ロードの場合は、ホストのツール検出プリミティブを使って、その機能をロードしてください。他のホストのツール名を探してはいけません。一覧に該当するツールがない場合、または実際の質問呼び出しがエラーになった場合に限り、ホストのチャット画面で番号付きの選択肢を提示してください。質問を黙って省略してはいけません。

実行環境

実行状態の保存先、ループの待機方法、実験の実行場所は、3 つの機能によって決まります。永続状態ルートとは、ハーネスが指定する書き込み可能な場所で、リポジトリのチェックアウト外にあり、ターン間やコンテキストのリセット後も保持されます。これがない場合、状態は .context/compound-engineering/ce-optimize/<spec-name>/ 配下に保存されます。ターン終了後の再開とは、ツール呼び出しを開いたままにせず、外部イベントまたはタイマーによって再度呼び出される仕組みです。これがない場合、ループはこのセッション内で実行され、待機を継続できなければ、再開の呼び出し方法を伴うチェックポイントとしてターンを終了します。分離ワーカーとは、結果がローカルツリーへの編集ではなく、プッシュされた ref、ストアファイル、またはホストから配信されるメッセージとして届く実行依頼です。execution.backend: remote にはこれが必要です。これがない場合、その仕様は worktree 上で実行されます。現在のツール一覧、またはハーネスが提供したコンテキストに存在することは、その機能が利用可能である証拠です。バイナリや環境変数が見つからないことは、何の証拠にもなりません。確認を求めず、代替手段を選んでください。

Artifact Root

成果物パスを作成する前に、CE 成果物ルート <root> を解決してください。

• <repo-root>/.compound-engineering/config.yaml からのみ docs_root を読み取ってください（<repo-root> = git rev-parse --show-toplevel）。config.local.yaml から読み取らないでください。未設定の場合、これまでどおり <root> は docs です。
• 設定値を検証してください。リポジトリ相対のディレクトリであり、シンボリックリンク解決後の実パスがリポジトリ内にとどまり、リポジトリルートでも .git/ 配下でもない必要があります。それ以外の場合は、docs_root とその値を示すエラーで停止し、docs にフォールバックしないでください。
• <root> を唯一の成果物保存先として使用してください。存在しない場合は作成し、各パスをこのスキル独自のサブディレクトリを使った <root>/<subdir> として構成し、docs を読み取ることも決してしないでください。

永続化の規律

実験ログはディスク上のものを正とします。測定、書き込み、検証、ユーザーへの表示の順に行います。チェックポイント CP-0〜CP-5、状態ルートのレイアウト、再開について、今すぐ references/persistence.md を読み取ってください。

フェーズ

4 つのフェーズを順番に実行します。それぞれ、開始に必要な参照ドキュメントが指定されています。新規実行ではフェーズを省略しません。より難しい最適化では、フェーズ数を減らすのではなく、各フェーズにより多くの時間をかけます。

再開は新規実行ではありません。 再開時は、実行を検出し、ログにない result.yaml マーカーを復元するために必要な範囲でのみフェーズ 0 に再入してください。その後は、ログに記録されたフェーズから続行し、完了済みであることが証明されている作業を省略します。チェックポイントは、それを作成した作業の完了を証明します。ユーザーの決定が有効なのは、ログに記録されている間だけです。フェーズ 1 の承認記録は、スペックのダイジェストと承認した上限に紐付けられています。その記録がない場合、または現在の内容と一致しない場合は、その承認ゲートを再提示してください。

フェーズ 0：セットアップ。 入力は、ユーザーまたは呼び出し元のスキルから渡される目標、またはスペックの YAML パスです。入力がどちらも指定されていない場合に入力を求め、その後、保存するスペックを読み込むか作成するために references/spec.md を読み取ってください（CP-0）。フェーズ 0 の残りとフェーズ 1 については、references/measurement.md を読み取ってください。

フェーズ 1：測定の準備。 ハーネスを構築または検証し、ベースラインを書き込み（CP-1）、並列処理を調査し、作業ツリーの予算を確認します。実行を停止するゲートが 2 つあります。

• クリーンツリーゲート。 scope.mutable または scope.immutable 内のファイルに未コミットの変更がある間は、続行しないでください。確認方法と尋ねる内容は参照ドキュメントで定義されています。
• ユーザー承認ゲート。 フェーズ 1 で準備した内容を提示し、続行、問題の修正、スペックの調整を選べるようにします。含める内容は参照ドキュメントに記載されています。上限が設定されている費用と、上限のない費用を明示してください。ユーザーが明示的に承認するまで、フェーズ 2 に進まないでください。 その後、承認を記録し、スペックとベースラインをディスクから再読み込みしてください。

フェーズ 2：仮説の生成。 現在のアプローチを分析し、仮説に優先順位を付け、バックログを記録します（CP-2）。より低コストの特定測定によって採用または見送りの判断が変わる可能性がある間は、実装実験を開始しないでください。このフェーズとフェーズ 3 については、references/loop.md を読み取ってください。ゲートは 1 つです。すべての仮説に関する新しい依存関係について、一括リストとして依存関係の事前承認を得てください。

フェーズ 3：最適化ループ。 結果ごとの永続化とバッチチェックポイントを含め、references/loop.md のティックプロトコルに従ってください。次の 8 つの基準のいずれかを満たした時点で、直ちに停止します。宣言された必須ターゲットをすべて達成した、最大反復回数に達した、最大稼働時間に達した、実時間の打ち切り条件に達した、支出上限に達した、停滞した、ユーザーが中断した、または実行可能な仮説が残っていない、のいずれかです。それぞれの条件は references/loop.md に正確に記載されています。それ以外の場合は、次のティックを開始してください。

フェーズ 4：まとめ。 要約と完了後に提示する選択肢について、references/wrap-up.md を読み取ってください。CP-5 はログを最終状態として記録します。フェーズ 3 に戻らない選択肢をユーザーが選んだ後にのみ、これを書き込んでください。「続行」と「保留中の依存関係の承認」の 2 つはフェーズ 3 に戻る選択肢です。