hokuto100retsuken/empirical-prompt-tuning

Empirical Prompt Tuning

プロンプトの品質は書いた本人には分からない。バイアスを排した実行者に実際に動かしてもらい、両面で評価して反復するのが核。改善が頭打ちになるまで止めない。

使う: skill / プロンプトを新規作成・大幅改訂した直後、または挙動の原因を指示側の曖昧さに求めたいとき。使わない: 使い捨てプロンプト、主観的好みを反映したいだけのとき。

ワークフロー

0. 整合チェック（静的）: description が謳う用途と body のカバー範囲に乖離があれば iter 1 前に合わせる（飛ばすと subagent が body を再解釈し false positive）。
1. ベースライン準備: (a) 評価シナリオ 2〜3 種（中央値 1 + edge 1〜2、現実のタスク）、(b) 要件チェックリスト（シナリオごと 3〜7 項目、精度 % = 満たした数 / 全項目数、事前固定）。
2. バイアス排除読み: Task tool で新規 subagent を dispatch（自己再読は不可）。複数シナリオは単一メッセージで並列呼び出し。
3. 実行: 下記「subagent 起動契約」のプロンプトを渡し、シナリオ実行＋自己申告レポートを返させる。
4. 両面評価:
   • 自己申告（レポートから）: 不明瞭点 / 裁量補完 / 詰まった箇所
   • 指示側の計測（判定規則はここで一元定義）:
     • 成功/失敗: [critical] 要件が**全て ○**のときのみ成功。1 つでも × / 部分的なら失敗（○ / × の 2 値）。
     • 精度: ○=1 / ×=0 / 部分的=0.5 で合算し全項目数で割る。[critical] も同係数で含む（成功判定と精度は独立した二重軸）。
     • ステップ数（tool_uses、Read/Grep 含む）、所要時間（duration_ms）、再試行回数（レポートから）
     • 失敗時は「どの [critical] が落ちたか」を不明瞭点節に 1 行添える
   • [critical] は最低 1 つ必須（0 件だと成功判定が vacuous）。事後に付け外ししない。
5. 差分適用: 不明瞭点を潰す最小修正。1 イテレーション 1 テーマ（関連する複数修正は OK）。修正前に「この修正が要件チェックリストのどの項目を満たすか」を閾値文言レベルで明示（軸名からの推測は届かない／効果は非線形）。
6. 再評価: 新しい subagent で 2→5 を回す（同一 agent 再利用 NG、前回を学習している）。
7. 収束判定: 下記「打ち切り基準」へ。

評価軸の補足

質的（不明瞭点・裁量補完）を主、量的（時間・ステップ数・再試行）を補助（時間短縮だけ追うと痩せる）。tool_uses はシナリオ間の相対値で見る — 1 シナリオだけ他比 3-5 倍以上なら自己完結性が低く references descent を強いているサイン（対処は最小完成例の inline 化）。精度 100% でも偏りがあれば iter 継続の根拠。

subagent 起動契約

実行者に渡すプロンプトの構造（両面評価の入力契約）:

あなたは <対象プロンプト名> を白紙で読む実行者です。

## 対象プロンプト
<本文を全文貼る or Read で読ませるパス>

## シナリオ
<状況設定 1 段落>

## 要件チェックリスト
1. [critical] <最低ラインの項目>
2. <通常項目>
（判定規則はワークフロー 4 に一元定義。[critical] 最低 1 つ必須。）

## タスク
1. 対象プロンプトに従いシナリオを実行し成果物を生成。
2. 終了時に下記構造で返答。

## レポート構造
- 成果物: <生成物 or 実行結果サマリ>
- 要件達成: 各項目 ○ / × / 部分的（理由付き）
- 不明瞭点: 詰まった箇所・迷った文言（箇条書き）
- 裁量補完: 自分の判断で埋めた箇所（箇条書き）
- 再試行: やり直し回数と理由

呼び出し側はレポートの自己申告を抽出し、tool_uses / duration_ms を usage メタから取得して評価軸を埋める。

環境制約

新規 subagent を dispatch できない環境では本 skill は適用しない。代替: 別セッションへ依頼 / 評価を諦め「empirical evaluation skipped」と報告。NG: 自己再読で代替（バイアスが入る）。

構造審査モード: 実行せずテキスト整合性だけ見たいときは、依頼プロンプトに「構造審査モード」と明記すれば skip 動作に引っかからず静的レビューを返せる。empirical の代替ではなく補助（連続クリア判定には使えない）。

打ち切り基準

• 収束: 連続 2 回で全て満たす — 新規不明瞭点 0 / 精度改善 +3pt 以下 / ステップ数変動 ±10% / duration 変動 ±15%。収束判定時に hold-out シナリオ 1 本を追加し、精度が直近平均から 15pt 以上落ちたら過適合（edge を足す）。
• 発散: 3 回以上で新規不明瞭点が減らない → 設計方針が間違っている。パッチをやめ構造を書き直す。
• リソース打ち切り: 重要度と改善コストが釣り合わなければ止める（80 点で出す）。

提示フォーマット

## Iteration N
### 変更点（前回差分）
- <修正 1 行>
### 実行結果（シナリオ別）
| シナリオ | 成功/失敗 | 精度 | steps | duration | retries |
|---|---|---|---|---|---|
| A | ○ | 90% | 4 | 20s | 0 |
### 不明瞭点（今回新出）
- <シナリオ>: [critical] 項目 N が × — <理由>   # 失敗時必須
### 裁量補完（今回新出）
- <シナリオ>: <補完内容>
### 次の修正案
- <最小修正 1 行>
（収束判定: 連続 X 回クリア / 停止まであと Y 回）

Red flags（合理化に注意）

• 「読み直せば同じ」「同じ subagent を使い回す」→ 客観視不可・前回を学習している。毎回新規 dispatch。
• 「1 シナリオで充分」→ 過適合。最低 2。
• 「不明瞭点ゼロが 1 回出た」→ 連続 2 回で確定。
• 「複数の不明瞭点を一気に潰す」→ 何が効いたか追えない（ただし関連 2-3 件の微修正は 1 iter にまとめてよい、分けすぎ注意）。
• 「メトリクスが良いから質的は無視」→ 時間短縮は痩せすぎのサイン、質的を主に。
• 「書き直した方が早い」→ 3 回以上減らないなら正解、それ以前は逃げ。
• シナリオを修正に合わせてチューニングしない（本末転倒）。

関連

superpowers:writing-skills（skill 作成の TDD、本質的に同じ）/ retrospective-codify（タスク終了後の学び固定化、本 skill は開発中）/ superpowers:dispatching-parallel-agents（並列実行の作法）