最適化ハンドオフ (kernel-optimize) は何をしますか？
目標がカーネルをハードウェア限界まで押し上げることである場合（単なるパフォーマンスのスポットチェックではなく）、このファイルがPrimus-Turboと../../kernel-optimize/SKILL.mdの自律最適化ループとの間のインターフェースとなります。このループが必要とする前提情報を提供します。最初にハブ../SKILL.mdを読んでください。
プロセス
- 環境を確認 —
pip show primus_turbo；編集可能インストールでなければ再インストール（ハブSKILL.md→ ビルド）。 kernel-optimize/SKILL.md「前提情報」を読む — ループが必要とするものを理解する。- 前提情報を収集する 対象のオペレーションについて（以下の表 + ハブ
SKILL.mdのコードマップ/コマンド）。 - ハンドオフ —
kernel-optimize/SKILL.mdへ；ループは DEFINE_TARGET → PREPARE_ENVIRONMENT → BASELINE → (ANALYZE → OPTIMIZE → VALIDATE)* → REPORT を実行する。 - 受け入れ — プロジェクトに戻り：完全なスイート
pytest tests/pytorch/ -vを実行し、レポートを確認し、クリーンな差分/コミットを確認する。
ループを開始する前に、../../../rules/iteration_rules.mdc を読んでください：1ラウンドにつき1仮説、パフォーマンスの前に正しさのゲート、受け入れ/ロールバックの系列、受け入れられたすべての改善は実際のトレーニングステップに移行可能でなければならない（id(...) キーの活性化/勾配出力キャッシュなし、一様分布のみのGroupGemmショートカットなし）。
前提情報（オペレーションごと）
| 要件 | 入手先 |
|---|---|
| カーネルソースファイルパス | ハブ SKILL.md → コードマップ |
| 集中テストコマンド | ハブ SKILL.md → テスト・ベンチマーク；例：pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON" |
| 集中ベンチマークコマンド | ../verify-performance/SKILL.md；例：PRIMUS_TURBO_GEMM_BACKEND=TRITON python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockwise |
| ベンチマーク出力形式/メトリクス | ../verify-performance/SKILL.md （Forward/Backward TFLOPS、Check ゲート） |
| 高速バリデーションハーネス | 以下の「高速バリデーション」 |
| スコアリングルール | 以下の「最適化スコアリング」 |
execution_mode + 再ビルド | 以下の「最適化環境」 |
最適化環境
| バックエンド/言語 | 推奨 execution_mode | 変更後の再ビルド |
|---|---|---|
| Triton (Python) | repo-mode | なし（編集可能インストール） |
| HIP / CK (C++)、小さな/パラメータ変更 | repo-mode | GPU_ARCHS=<arch> pip install --no-build-isolation -e . -v |
| HIP / CK (C++)、新しいカーネル/大量の試行錯誤 | workspace-mode | kernel-optimize/SKILL.md の最小スタックに従う |
最適化スコアリング
Check 列は厳格なゲートです — FAIL/ERROR の形状がある候補は拒否されます。
| キャンペーン種別 | primary_metric（集約 = PASS形状の幾何平均） |
|---|---|
| 計算バウンド、フォワードのみ | Forward TFLOPS |
| 計算バウンド、フォワード+バックワード（トレーニング） | Combined Step TFLOPS（フォワード/バックワードは診断用に保持） |
| メモリバウンド（要素演算、量子化） | Forward GB/s / Backward GB/s |
結合ステップの導出（fwd+bwd GEMMクラスのオペレーションに推奨）は ../verify-performance/SKILL.md にあります。primary_metric は DEFINE_TARGET でユーザーと確認してください。
高速バリデーション
2つのツール、別々の役割 — 絶対値を比較しないでください（異なるタイミングエンジンを使用します）：
quick_test_bench.py（このフォルダ内、キャンペーンディレクトリにコピー）は、ラウンド間の形状ごとのリグレッションゲートの信頼できる情報源です。BASELINE（ラウンド1）および各VALIDATEラウンドはこのスクリプトを実行し、その--summary-csv出力を比較します。手作りのtime.perf_counterループを使用します。- 完全な
bench_<op>_turbo.py（../verify-performance/SKILL.md参照、torch.utils.benchmark.Timer）は、(i) 完全な形状セットからrepresentative_shapesを選択するため、および (ii) キャンペーン後の最終受け入れのためにのみ使用されます。
両方のバリデーションレベルは quick_test_bench.py を介して実行され、SHAPES のみが異なります：
- 完全バリデーション（BASELINE + 最終受け入れ）→
SHAPES= すべてのtarget_shapes。 - 高速バリデーション（各VALIDATEラウンド）→
SHAPES= 3–5個のrepresentative_shapesサブセット。
representative_shapes：BASELINE実行からの Check=PASS 形状のみで、小規模（起動オーバーヘッド）+ 大規模（計算/メモリ）スケールをカバーし、高分散形状を優先します。manifest.yaml: representative_shapes に記録します。
ハーネス： テンプレート quick_test_bench.py が標準リファレンスです。PREPARE_ENVIRONMENT 中に、SHAPES を空にして <target_backend> を設定した状態で <campaign_dir>/quick_test_bench.py にコピーします。BASELINE では SHAPES をすべての target_shapes で埋め、VALIDATE ラウンドでは representative_shapes に絞ります。対象のオペレーション/設定に応じて調整し、--summary-csv ライターとカラムスキーマは維持してください（非GEMMオペレーションについては以下のスキーマ範囲の注釈を参照）。
測定一貫性契約： BASELINE（ラウンド1）および各VALIDATEは、同じ信頼できるCSVを --summary-csv を介して読み取り、ラウンド間で同一のパーサーによって解析されます。そのパーサーは、設定されていればオプションの mcp__turbo__parse_bench_csv MCPヘルパー、そうでなければ以下のカラムをキーとした直接の csv.DictReader です。特定のリーダーは重要ではありません；スキーマを固定することが重要です。スキーマはこれらのカラムと完全に一致する必要があります（ずれると形状ごとのリグレッションゲートが暗黙的に無効になります）：
label,B,M,N,K,Check,Forward TFLOPS,Forward TFLOPS_stddev,Backward TFLOPS,Backward TFLOPS_stddev,Forward Time (ms),Backward Time (ms),out_snr,da_snr,db_snr
Check は PASS / FAIL を使用します；*_stddev はメトリクスの単位での絶対標準偏差です。呼び出しを manifest.yaml に quick_command: "python <campaign_dir>/quick_test_bench.py" として記録します。BASELINEおよび各VALIDATEは --summary-csv <round_dir>/artifacts/benchmark.csv を追加します。
スキーマ範囲： 上記のカラムは GEMMクラス固有 です（M,N,K 次元、Forward/Backward TFLOPS、out_snr/da_snr/db_snr）。非GEMMオペレーションの場合は、label、Check、*_stddev の規則は維持しつつ、GEMM専用カラムを primary_metric が必要とするカラムに置き換えてください。例えば、「最適化スコアリング」に従ったメモリバウンドオペレーションは、TFLOPS の代わりに Forward GB/s / Backward GB/s を使用し、単一出力オペレーションは out_snr/da_snr/db_snr を独自の正しさメトリクスに置き換えます。どのスキーマを選んでも、BASELINE で固定し、全ラウンドでバイト単位で同一に保ち、使用する CSV リーダー（設定されていれば mcp__turbo__parse_bench_csv マッピング、そうでなければ直接の csv.DictReader）をそれに合わせて更新してください — 形状ごとのリグレッションゲートは正確なカラム名に依存します。