skill-autobench

skill-autobench — 実際の利用体験から評価を作成する

規約： conventions/brain-first.md を参照してください — マイニングは脳から始めます。生のトランスクリプトファイルに手を付ける前に 会話アーカイブを検索し、まず脳に問い合わせることなく 「履歴がない」と宣言してはいけません。

規約： conventions/model-routing.md を参照してください — マイニングと統合は、デフォルトでは低コストのティアで実行します。複数モデルによる 完全な判定パスは、明示的にオプトインします（契約を参照）。

自己改善ループは、評価、バリアント生成器 （SkillOpt）、リプレイ＋判定ハーネス（gbrain eval cross-modal）の3本柱で構成されます。 生成器と判定器は gbrain に同梱されています。継続的に欠けているのは 評価の作成者です。評価を作成する人が必要ですが、仕様から作成したベンチマークで 検証できるのはスキルが約束したことだけです。ユーザーが実際に求めたことや 実際に問題になったことは検証できません。このスキルでは、想像ではなく実態に基づいて 評価を作成します。

パイプライン

1. マイニング — 実際の呼び出しウィンドウを抽出する

データ基盤は、優先順位の高い順に次のとおりです。

1. 脳の会話アーカイブ — conversations/ 配下のページ。conversation-archive スキルによって 作成されます（このデータ基盤を使うには、そのスキルが必須です。履歴がまだ 取り込まれていない場合は、まず実行してください）。対象スキルの名前、トリガーフレーズ、 出力形式を検索します。

   gbrain search "<skill-name>"
   gbrain query "when did I use <skill-name> and what did I ask for"
   

2. 利用可能なハーネスごとのセッショントランスクリプト — ハーネスが公開しているものを 使用し、保存場所を決めつけないでください。gbrain transcripts recent --full は、 設定済みのローカルトランスクリプトコーパスを読み取ります（設計上、ローカルのみです）。 Claude Code はプロジェクトごとのセッションを ~/.claude/projects/ に JSONL 形式で保存します。 他のハーネスにも、それぞれ独自のセッションストアがあります。存在しないストアは 単にスキップします。

各ヒットから呼び出しウィンドウを抽出します。呼び出し前のユーザーの依頼、 呼び出しそのもののターン、そしてその後の2ターンです。修正はそこに現れるためです。 **呼び出し後のユーザーによる修正は、最も有力なシグナルです。**実際に観測された 失敗モードであり、hard_fail とリプレイ可能なケースになります。

**フェイルクローズ：**対象スキルの実際の呼び出しが1件も得られなかった場合は、 正直な「履歴なし」レポート（確認したデータ基盤、実行したクエリ、スキャンしたウィンドウ、 一致件数ゼロ）を出力して終了します。「典型的な」呼び出しを捏造してはいけません。 履歴がないスキルには、gbrain skillopt <name> --bootstrap-from-skill が適切なツールです （仕様由来であることを明示し、その点について正直です）。Dedup を参照してください。

2. 統合 — ウィンドウを評価案にする

マイニングしたウィンドウと現在の SKILL.md から、次を作成します。

• 提案する eval_contract：目標、評価軸、hard_fails。評価軸は実際に観測された依頼から導き、 hard_fails は実際に観測された修正を表します。
• リプレイ可能なケースを4〜8件。各ケースは {input, expected_behavior, failure_mode_to_catch} の形式とします。現実的な入力、 検証可能な期待動作、そしてそのケースで検出する失敗モードを記述します。
• 仕様と利用状況のギャップ：「仕様には X とあるが、ユーザーは一貫して Y を求めている」。

**根拠ラベルは必須です。**すべての評価軸とケースに、次のいずれかのラベルを付けます。

• HISTORY-IMPLIED — 実際にマイニングしたウィンドウが根拠です。どのウィンドウかを明記します。
• SPEC-DERIVED — SKILL.md のみから推定したもので、利用状況の証拠はありません。

この2つを混同してはいけません。履歴が乏しい場合や対象から外れている場合は、 証拠を捏造して水増しするのではなく、ステージングしたファイルの冒頭に 「GROUNDING WARNING: 見つかったウィンドウは N 件のみで、コアパスを実行したものはありません」 と目立つように記載します。

**ステージング前のプライバシー処理：**ステージングした評価はスキルのリポジトリに置かれ、 配布可能です。マイニングしたウィンドウには実在する人名、企業名、取引情報が含まれます — ファイルに書き込む前に、すべてのケースをプレースホルダーのスラッグ （alice-example、acme-example）に置き換えてください。履歴に基づくケースでは、 実在する固有名詞は使わず、形と失敗モードを維持します。

3. ステージ — 常に人間による確認を必須とします

skills/<name>/eval/autobench-<date>.md を作成し、フロントマターに status: PENDING-HUMAN-APPROVAL を記述します。

このスキルは SKILL.md を絶対に書き換えません — eval_contract も、本文も、 トリガーも対象外です。ステージングされた eval をマージするかどうかは、人間が判断します。（これは エージェントが遵守すべきワークフロー上の契約であり、機械的に強制されるゲートではありません。）

ループ（承認後）

1. 人間がステージングされた eval を確認、編集、承認します。承認済みの eval_contract は、明示的にスキルのフロントマターにマージされます。

2. 承認済みのケースを skills/<name>/skillopt-benchmark.jsonl の行に変換し、 gbrain skillopt <name> を実行します — これが SkillOpt サーフェス拡張です。 仕様由来のブートストラップを、履歴に基づくベンチマークに置き換えます。

3. ネイティブゲートを通じて出力を判定します。

   gbrain eval cross-modal --task "<what the output was meant to achieve>" --output <path>
   

4. 利用がさらに蓄積されたら autobench を再実行し、以前の ステージング済みベースラインとの差分を取ります。

パネルの整合性 — 集計結果を鵜呑みにしない

マルチモデル判定の品質は、実際にパネルが機能しているかどうかにかかっています。気づきにくい 障害のパターンは、モデル ID の正規化でプロバイダーの接頭辞が取り除かれ、「異なるモデル」への すべての呼び出しが 1 つのホストに届き、「3 つの最先端モデルによる合意」が、トレンチコートを 着た 1 つのモデルの意見になってしまうことです。マルチモデルの判定を信頼する前に、結果オブジェクトに対して次を 確認してください。

1. 名前が付いた各モデルが、空ではない応答を返していること。 応答が空、または失敗した スロットは、集約の最初の兆候です。
2. 応答の取得元が、それぞれ異なるプロバイダーのエンドポイントであること。 「異なるモデル」 3 つがすべて同じプロバイダーを報告した場合、パネルは 1 つのホストに集約されています。
3. 「異なるモデル」2 つが、バイト単位で同一の出力を返していないこと。 モデル名が異なる 2 つのモデルが同じバイト列を返した場合、それらは同じモデルです。 これは、プロバイダーのメタデータが欠落している場合や偽装されている場合でも、 集約を検出できます。

gbrain eval cross-modal は、解析可能なスコアを返すモデルが 2/3 未満の場合、すでに INCONCLUSIVE を示す 2 で終了します。バイト単位で同一の重複を確認するチェックと、 エンドポイントの異なりを確認するチェックは、このスキルがその上に追加する独立した 安全策です。PASS/FAIL を確定的なものとして扱う前に、受領 JSON（受領ディレクトリに 書き込まれます）に対してこれらを実行してください。整合性チェックは既存の結果に対する純粋な アサーションロジックであり、それ自体がモデルを呼び出すことはありません。ネットワーク通信も、 コストも発生しません。

失敗から改善するための分類 — 採掘した失敗をどうするか

採掘した修正・失敗ケースを、それぞれ最も低コストで長期的に有効な修正方法に基づいて分類します。

クラス	履歴に見られる兆候	長期的に有効な修正
DETERMINISTIC-CODIFIABLE	LLM フォールバックが、同じ入力形式（正規表現、解析、スラッグ、日付）を繰り返し処理している	決定論的なコードに置き換え、恒久的なテストケースを追加します。LLM は解決策ではありません。置き換え対象となるコードのトレーニングデータを生成するためのものです。
PROMPT-FIXABLE	修正内容が、SKILL.md で指定できるトーン、形式、または欠落に関するもの	eval ケースと gbrain skillopt の実行
SPEC-GAP	仕様で約束されていないことを、ユーザーが一貫して求めている	仕様と利用状況のギャップに関する、人間向けの所見
ROUTING-MISS	スキルが誤った依頼に反応した、または反応しなかった	ベンチマークケースではなく、routing-eval.jsonl のケース

目指す方向は、修正した失敗がすべて恒久的なテストになり、 決定論的な処理の割合が増え、LLM フォールバックの割合が減ることです。記録して改善し、 採掘した失敗を黙って破棄しないでください。

契約

• 入力： skills/ 配下に存在するスキル名です。
• 基盤： conversations/ のアーカイブページを優先し、次に利用可能な場合はハーネスごとのセッション記録を使用します（gbrain transcripts recent は設計上ローカル専用です）。利用可能な基盤がない場合は、履歴がないことを正直に報告し、証拠を捏造しません。
• 出力： skills/<name>/eval/autobench-<date>.md にステージングするファイルを1つ作成し、status: PENDING-HUMAN-APPROVAL とします。あるいは、履歴がない場合の報告を行います。SKILL.md、トリガー、ルーティング関連の箇所は決して編集しません。
• コスト方針： マイニングと統合では、安価なモデルをデフォルトで使用します。複数モデルによる完全な評価（1サイクルあたり3つのプロバイダースロット）は明示的なオプトインであり、評価は独自の評価ハーネスではなく、ネイティブの gbrain eval cross-modal を通じて実施します。
• 誠実さ： すべての次元とケースに SPEC-DERIVED または HISTORY-IMPLIED のラベルを付けます。履歴が乏しい場合は、取り繕わずにその旨を明記します。
• プライバシー： マイニングしたケースは、ステージング前にプレースホルダーのエンティティに置き換えます。

出力形式

---
skill: <name>
status: PENDING-HUMAN-APPROVAL
generated: <date>
substrate: { conversation_pages: N, transcript_files: M, windows: K, corrections: C }
---

# Autobench: <name> — <date>

## Grounding
<one paragraph: how much real history backs this eval; GROUNDING WARNING if thin>

## Proposed eval_contract
goal / dimensions (each labeled HISTORY-IMPLIED|SPEC-DERIVED) / hard_fails

## Cases (4-8)
### case-01 [HISTORY-IMPLIED — window ref]
input: ...
expected_behavior: ...
failure_mode_to_catch: ...

## Spec-vs-usage gaps
- spec says X; users ask Y (windows: ...)

## Fail-improve classification
- case-03 → DETERMINISTIC-CODIFIABLE (same date-format fallback, 4 windows)

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックが発生した場合は、エージェント運用者プロトコルに従ってください。このスキル固有の事項は次のとおりです。

• スキルの実際の呼び出しにつながる基盤がない場合は、FAIL-CLOSED とします。その旨を報告し、評価ファイルは作成しません。想像でケースを合成してはいけません。
• gbrain eval cross-modal または審査の実行に必要なキーがない場合、あるいは no_pricing が発生した場合は、評価が審査されていないことを伝え、ドラフトを PENDING-HUMAN-APPROVAL のままにします。

アンチパターン

• ❌ 合成した評価を SKILL.md に自動マージすること。人間による承認が契約です。
• ❌ SPEC-DERIVED の次元を履歴に基づくものとして示すこと。使用状況の証拠を捏造するのは最大の過ちです。
• ❌ 何もマイニングせず、それでも確信に満ちた評価を出すこと。明確に失敗するか、正直にラベルを付けてください。
• ❌ 3つのプロバイダーが実際にそれぞれ異なる応答を返したことを確認せず、「3つのモデルが8/10と評価した」と信頼すること。
• ❌ パネルの整合性チェックでモデルを呼び出すこと。これは結果オブジェクトに対する純粋なアサーションロジックです。
• ❌ ネイティブのゲートが gbrain eval cross-modal であるにもかかわらず、独自の審査ハーネスを構築すること。
• ❌ 実在の人物や企業が含まれる状態で、マイニングしたケースをステージングすること。プレースホルダーのみを使用してください。

重複排除（明確な境界）

• skill-optimizer（SkillOpt、ホスト側） — 既存のベンチマークに対してスキルの本文を最適化します。--bootstrap-from-skill は仕様からタスクを導出します。このスキルは実際の利用履歴からベンチマークを作成し、それを skills/<name>/skillopt-benchmark.jsonl に渡します。SkillOpt の対象範囲を拡張するものであり、重複はしません。引き継ぎ前に、skill-optimizer の SKILL.md（エンジンがあるホスト上）を読んでください。履歴がまったくない場合は、このスキルではなく --bootstrap-from-skill を使用します。
• BrainBench（gbrain eval スイート） — エンジン（検索、メモリー準拠、キャリブレーション）を評価します。この評価では、スキルをその履歴に基づいて評価します。
• skills/skillify/SKILL.md / skills/skill-creator/SKILL.md — 説明からスキルを作成します。実際の利用履歴のマイニングは行いません。
• skills/cross-modal-review/SKILL.md / gbrain eval cross-modal — 審査パネルを実行します。評価を作成するものではありません。ここでのパネル整合性アサーションは、パネルが実際に実行されたことを検証します。
• skills/skillpack-check/SKILL.md — スキルの構造と準拠状況を監査します。動作の品質は評価しません。
• routing-eval.jsonl — ディスパッチをテストします（適切なスキルが起動するか）。autobench はディスパッチ後の動作をテストします。ROUTING-MISS の検出結果は、そちらに振り分けます。