79yuuki/dotfiles/empirical-prompt-tuning

Empirical Prompt Tuning

プロンプトや skill の品質は、作者の主観だけでは分からない。 白紙実行者に実際に動いてもらい、固定シナリオ + fixed checklist + hold-out で改善を回す。 高頻度 skill / routing-sensitive skill は、運用へ昇格する前にこの検証を通す。

Quick route

• 新規 skill / 大改訂 skill / routing更新 → まず Iteration 0、次に白紙実行者テスト
• 高頻度 skill → 白紙実行者テスト 必須
• 単発プロンプト → この skill は使わない
• dispatch 不可 → 自己再読で代替しない。empirical evaluation skipped: dispatch unavailable と明示して止める

高頻度 skill の定義

以下のいずれかを満たしたら高頻度扱い。

• 週次以上で繰り返し使う
• 他 skill の routing / quality gate に効く
• cron / automation / review loop の中核に入る
• company-wide / cross-project に再利用する
• hot.md に上げたい、または standing rule 化したい

ワークフロー

Step 0: Iteration 0 — description と body の整合チェック

まず静的に見る。

• frontmatter description の trigger / NOT for / 想定用途を確認する
• body が description の約束を本当にカバーしているか確認する
• 乖離があれば、白紙実行者テストの前に直す

これは false positive 防止。 description だけ強くて body が弱い状態でテストすると、読者が好意的に補完して通ってしまう。

Step 1: ベースラインを作る

最低これを固定する。

• シナリオ 2-3本: 中央値 1、本番で困りやすい edge 1-2
• 要件チェックリスト 3-7項目
• [critical] 項目を最低1つ
• hold-out 1本: 収束判定まで温存する境界ケース。ケースは train / holdout に分け、調整は train だけで行い、採用判定は holdout で下す
• ノイズ幅: 修正前に同一プロンプトを複数回走らせてスコアのばらつきを測る。それ未満の差は改善と見なさない
• 採点は二値ルーブリック: 「〇〇を含む」「××をしない」のような検証可能な主張の二値項目で採点する。1〜5点尺度は使わない

先に固定し、評価の途中で都合よく変えない。

スキル追加・改訂の効果を比較する場合は references/decision-evaluation-and-skill-lift.md を読む。同じモデル・fixture・環境で旧版/新版（または対象skillなし/あり）を比較し、主要な変更変数は1つに絞る。判断目的・主指標・安全条件・コスト/レビュー負担を先に固定し、安全検査の合格を有用性の証明にしない。

詳しい起動契約は references/blank-executor-contract.md、 レポート雛形は references/report-template.md を使う。 Latest local gate summaries may be mirrored in references/latest.md / references/latest.json when the environment is updating this skill package directly (these files exist only in that case).

Step 2: 白紙実行者を dispatch する

自己再読ではなく、別セッション / 別 subagent に読ませる。 実行者には以下だけ渡す。

• 対象プロンプト or skill のパス
• シナリオ
• fixed checklist
• レポート構造

実行者には、成果物に加えて次を自己申告させる。

• 不明瞭点
• 裁量補完
• 再試行回数

Step 3: 両面評価を取る

最低限これを見る。

• success: [critical] が全部通ったか
• accuracy: checklist 達成率（二値項目の合格率。judge は被検モデルと別のモデルにする）
• efficiency: 無駄な探索・往復・過読が減ったか
• executor feedback: 不明瞭点 / 裁量補完 / retries

tool_uses / duration_ms が session metadata から取れるなら記録する。 取れない環境では、success / accuracy / executor feedback を優先して続行する。 時間短縮だけを最適化しない。ただしベースラインが約95%以上なら精度は天井なので、目標をコスト（トークン・時間）に切り替える。

Step 4: 1 iteration 1 theme で直す

1回で全部盛りしない。

• 関連する微修正はまとめてよい
• 無関係な修正は次の iteration に回す（1ラウンド1変更が原則。複数変えると効いた要因が分からない）
• 「この修正が checklist のどれを改善するか」を先に言語化してから直す

Step 5: 再実行する

毎回 新しい白紙実行者 で回す。 同じ実行者を再利用しない。 前回の改善を学習しているから。

Step 6: 収束判定をする

停止目安:

• 連続2回で新規不明瞭点 0
• accuracy の改善が小さい
• efficiency の変動が小さい
• hold-out で大崩れしない

3回以上回しても不明瞭点が減らないなら、修正パッチではなく構造自体を見直す。

高頻度 skill gate

高頻度 skill は、以下を満たすまで standing rule 扱いしない。

1. Iteration 0 を通す
2. 白紙実行者テストを最低1 iteration 実施する
3. 結果を reports/empirical-prompt-tuning/ に残す
4. hold-out を含む改善方針を次アクションに書く

「良さそう」だけで hot.md / routing / org-wide rule に昇格しない。

レポート保存先

毎回、以下を残す。

• Markdown: reports/empirical-prompt-tuning/YYYY-MM-DD-<target>-iterN.md
• Latest summary: reports/empirical-prompt-tuning/latest.md
• Machine-readable summary: reports/empirical-prompt-tuning/latest.json
• references/latest.md / references/latest.json may mirror the latest in-package gate note when skill packaging is the active task; do not treat that mirror as a substitute for reports/empirical-prompt-tuning/ in normal runs.
• When reports/ writes are not available from the active skill-management tool, save a concise skipped-gate note in references/YYYY-MM-DD-<target>.md and link it from the “Recent skipped examples” list; label it clearly as a fallback, not a full empirical report.

最低限の記録項目:

• target
• scenario list
• checklist
• success / accuracy / efficiency notes
• executor-reported ambiguity / discretionary fills / retries
• change made this iteration
• next action
• status (doing / converged / skipped / rewrite-needed)

Red flags

• 自己再読で代替する → ダメ
• 1シナリオだけで満足する → 過適合しやすい
• 不明瞭点ゼロ1回で終える → 早すぎる
• MUST / ALWAYS を足すだけで改善した気になる → 最後の手段
• metricだけ見て質的フィードバックを捨てる → 危ない
• 同じ白紙実行者を使い回す → ダメ

実務ルール

• 高頻度 skill の更新では、まずこの skill を読み、検証計画を立てる
• skill-creator から辿ってきた時は、../skill-creator/SKILL.md の high-frequency gate と合わせて扱う
• dispatch 不能ならスキップを明記し、実証済みみたいな顔をしない
• 実測で効いたものだけを routing / hot / org-wide rule に昇格する