skill-autoresearch

Skill Autoresearch

このスキルは、固定されたローカルベンチマークを使って、再利用可能なリポジトリアーティファクトを改善する場合に使用します。

契約はシンプルです。まずラチェットが本当に必要かを判断し、次に評価基準を固定して、現在のアーティファクトのベースラインを測定します。必要な場合に限り、意味のある変更を1つだけ加え、同じハーネスを再実行し、測定された改善だけを採用して、採用と差し戻しの両方を記録します。

このスキルは、意図的にリポジトリ内に限定されています。SKILL.md、SOP、プロンプト、テンプレート、ワークフロードキュメント向けの、MarkdownやGitで管理しやすいラチェットを対象とします。実際のニーズが製品規模のトレース、ホスト型ダッシュボード、アプリ／ランタイム評価である場合は、このスキルがLangSmith、Braintrust、Weave、Promptfooに取って代わるかのように扱わず、適切なツールへ切り替えてください。

編集する前に、次のサポートファイルを読んでください。

• references/eval-guide.md
• references/loop-charter-template.md
• references/run-packets-and-route-outs.md

このスキルを使用する場合

• 再利用可能なSKILL.mdやワークフロードキュメントの動作に一貫性がなく、範囲を限定した改善ループが必要な場合。
• 現在のアーティファクトにさらにラチェットを適用すべきか、またはno ratchet justifiedが正しい結論かを判断する必要がある場合。
• ベンチマークを実行中に変更せず、トリガー、切り替え先、実行手順を改善したい場合。
• 主な境界が実証された後に限り、references/、evals/、簡易版、または発見時の表現を追加・更新する必要がある場合。
• GitやPRレビューでも残る、追記専用の採用／差し戻し履歴が必要な場合。
• 「この編集でアーティファクトは本当に改善したのか」に、繰り返し可能な方法で答えたい場合。

このスキルを使用しない場合

• ユーザーが求める具体的な書き換えがすでに明確で、ベンチマークループを必要としない場合。
• 対象に代表的なプロンプトがない、または動作を安定して評価する方法がない場合。
• 実際の作業が、train.py／program.md／val_bpbを使ったGPU依存のkarpathy/autoresearch実験である場合 → autoresearchを使用してください。
• 実際の作業が、ホスト型のプロンプトやアプリの評価、本番環境のトレース、大規模データセット、実験ダッシュボードに関する場合 → LangSmith、Promptfoo、Braintrust、Weaveに切り替えてください。
• アーティファクトと評価者を同時に変更しようとしている場合。

必要な入力

変更作業を始める前に、対象のアーティファクト、代表的なプロンプトまたはシナリオを3～5件、二値評価を3～6件、再実行／予算のルール、主要なアーティファクト以外に変更を許可するサポートファイルを把握してください。

その前に、次の3つのうちどの結果を裏付ける証拠があるかを判断してください。

• ベースラインはおそらく失敗しており、実質的なラチェットが必要である
• 主要なアーティファクトには問題がないが、サポート用の箇所にずれが生じている
• まだラチェットは正当化されない

手順

ステップ1：パケットを1つ選ぶ

何かを編集する前に、依頼を1つの主要パケットに整理してください。

skill_autoresearch_packet:
  primary_packet: ratchet-eligibility | benchmark-readiness | charter-freeze | baseline-score | one-change-mutation | support-sync | final-report | route-out
  target_artifact: SKILL.md | SOP | prompt-template | workflow-doc | other
  evidence_shape: prompts-and-evals | dry-run-checklist | repo-validators | mixed | unknown
  support_scope: none | references-only | evals-only | compact-only | discovery-surfaces | mixed
  confidence: high | medium | low

パケットの意味：

• ratchet-eligibility — 実行をno ratchet justifiedとして終了するか、support-syncへ進むか、実際のベンチマークループを続行するかを判断します
• benchmark-readiness — プロンプト／評価／スコープが固定されるまで、ループを開始できません
• charter-freeze — 変更を加える前に、ループの契約を作成します
• baseline-score — 現在のアーティファクトをスナップショットし、実験0を記録します
• one-change-mutation — 意味のある変更をちょうど1つ加え、再実行して、採用または差し戻しを行います
• support-sync — 中核となるラチェットが正当化された後、または主要なアーティファクトに問題はなくサポート用の箇所だけにずれがある場合に限り、簡易版／ドキュメント／マニフェストを更新します
• final-report — ベースラインから最終結果への差分、採用／差し戻しの件数、残っている失敗をまとめます
• route-out — 依頼の対象がホスト型の評価ツールまたはMLのautoresearchです

ステップ 2：対象と周辺のサーフェスを読む

まず主要な成果物を読み、その後、関連するサポート用サーフェスのみを確認します。

• リンク先の references/、evals/、scripts/、またはコンパクト版
• 発見可能性に影響する場合は、README／セットアップ／マニフェストの文言
• 既存のラチェットがある場合は、以前のループの成果物

以下を把握します。

• 成果物が実際に果たす役割
• 何をきっかけに起動するべきか
• 何を別の場所へ振り分けるべきか
• 現在の失敗モード
• 古くなった発見用の文言や、サポート情報のずれがないか
• 次に進むべき状態が no ratchet justified、support-sync、または実際の変更ループのどれか

ステップ 3：ループを確定する前にラチェットの適格性を判断する

チャーターを作成する前に、次の 3 点に答えます。

1. ベースラインはすでに現在の基準を満たしているように見えますか？
2. 実際の問題はサポート用サーフェスのずれだけですか？
3. ラチェットによる手間をかける価値がまだあるという具体的な根拠はありますか？

答えから no ratchet justified という結論に至る場合は、そこで終了し、その結果を報告します。 主要な成果物はすでに良好だが、ドキュメント／マニフェスト／コンパクト版のサーフェスにずれがある場合は、変更ループを実施したかのように装わず、代わりに support-sync に進みます。 ベースラインが実際に基準を満たしていない場合、または根拠に裏付けられた改善余地が明確にある場合に限り、ベンチマークループを続行します。

ステップ 4：評価器を固定する

編集前に、loop-charter.md を作成します。

チャーターでは次の項目を固定します。

• 実行の目標
• 現在のベースライン
• 変更可能な主要成果物を 1 つ
• 固定された評価ハーネス
• 対象範囲として許可されるサポートファイル
• 時間／反復回数／ツールの予算
• 今回の実行で採用しない方向性

ルール：

• 実行中にプロンプト、評価文言、採点ルールを変更しないでください
• 評価器を変更する場合は、新しい比較トラックを開始します
• 後からサポートファイルを変更する場合でも、変更可能な主要成果物は 1 つに保ちます

ステップ 5：二値評価のみを作成する

references/eval-guide.md を使用します。

スキルおよびワークフローの成果物に適した評価カテゴリ：

• トリガーの精度
• 別の場所へ振り分ける基準の明確さ
• 実行の決定性
• 成果物の有用性
• ベンチマークの規律
• 発見用サーフェスの同期（実行によって位置付けが変わる場合のみ）

ルール：

• はい／いいえのチェックのみを使用します
• 主観より観察可能なチェックを優先します
• 同じ失敗を二重に採点しないでください
• ベースライン実行と変更後の実行で同じプロンプトセットを使用します

ステップ 6：現在の成果物をベースラインとして評価する

1. 現在のバージョンを SKILL.md.baseline などのベースライン成果物にコピーします
2. 実験 0 を記録します
3. 固定したハーネスで現在のバージョンを採点します
4. 何も変更する前に失敗を要約します

判断ゲート：

• ベースラインがすでに十分な余裕をもって基準を満たし、重大なサポート情報のずれもない場合は、終了して no ratchet justified と報告します。
• ベースラインが良好で、コンパクト版／ドキュメント／マニフェストのみにずれがある場合は、support-sync に進み、その旨を明確に伝えます。
• ベースラインが実際に基準を満たしていない場合、またはチャーターで根拠に裏付けられた明確な改善余地を示している場合に限り、変更を続けます。

ステップ 7：一度に 1 つだけ変更する

これがループの中心です。

1. 失敗した出力または成果物のサーフェスを調べます
2. 仮説を 1 つ立てます
3. 意味のある変更を 1 つだけ加えます
4. 同じハーネスを再実行します
5. ベースラインおよび現在の最良結果と比較します
6. スコアが改善した変更のみを残します
7. チャーターで曖昧さの低減や入口のサイズ縮小などの副次指標を明示的に優先している場合を除き、同点または悪化した変更は元に戻します
8. 実行ログに結果を追記します

有効な変更：

• 弱いトリガーの説明を明確にする
• 重要な境界ルールを前に移動する
• 明確な使いやすさの不足を解消する、焦点を絞ったサポートファイルを 1 つ追加する
• 過剰なトリガーを引き起こすノイズの多い指示を削除する
• 安定した詳細をリファレンスに移し、肥大化した入口を短くする

不適切な変更：

• スキルと評価器を同時に書き換える
• 中核となる境界が検証される前に、広範囲にわたる複数ファイルの変更を行う
• 再現率を上げるためにキーワードを詰め込む
• 測定した動作ではなく文体を最適化する

ステップ 8：ラチェットが維持されてから、サポート用の表面を同期する

主な変更によって、見つけやすさ、オンボーディング、命名、使用方法が大きく変わる場合は、次の項目を同期します。

• evals/evals.json
• SKILL.toon などのコンパクト版
• skills.json／コンパクトなインデックスなどの検出用マニフェスト
• README.md、ローカライズされた README の項目、セットアップ用プロンプトなどのドキュメント／セットアップ用の表面

凍結された評価器によって主な成果物の改善が正当化された後に行います。

ステップ 9：すべての実験を記録する

追記専用の成果物を使用します。最低限、次の一式を用意します。

• loop-charter.md
• ベースラインのコピー
• 構造化された結果（results.tsv、results.json、または同等のもの）
• 平易な言葉で書かれた変更履歴／実験ログ

各実験では、次の内容を記録します。

• 維持または差し戻し
• スコアの変化
• 変更内容を一文でまとめたもの
• 仮説
• 残っている失敗

ステップ 10：このスキルにもルールを適用する

対象の成果物自体が skill-autoresearch であっても、このループの例外にはしません。

次の点を検証します。

• 凍結された評価基準に照らした対象スキルの評価
• メインのラチェットが維持された後にのみ行う、サポート用の表面の同期
• 最終的な文言が、凍結された評価器、一度に 1 つの変更を行うイテレーション、追記専用ログ、明示的な維持／差し戻しの判断を引き続き保っていること

出力形式

簡潔なラチェットレポートを返します。

# Skill Autoresearch Report

## Packet
- Primary packet:
- Target artifact:
- Why this packet fits:

## Frozen harness
- Prompts / scenarios:
- Binary evals:
- Validators:
- Scope limits:

## Baseline
- Current score:
- Main failures:

## Mutation result
- Change tried:
- Keep or revert:
- Score delta:
- Remaining failures:

## Support sync
- Updated surfaces:
- Deferred surfaces:

## Next state
- Recommended next move:
- Artifact paths:

例

例 1：トリガーの修正

入力

この古くなったスキルを改善してください。過剰にトリガーされるので、全面的な書き換えではなく、範囲を限定したループが必要です。

適切な方向性

• パケット：one-change-mutation
• まずプロンプト／評価を凍結する
• 説明文または対象外へ誘導する文言だけを書き換える
• 測定結果に基づいて維持または差し戻す

例 2：ベンチマークのドリフト修正

入力

スキルを書き換えながらテストも変更し続けています。それでも最適化を手伝ってください。

適切な方向性

• パケット：benchmark-readiness または charter-freeze
• 評価器が凍結されるまで、実行を先に進めない
• 判定方法も変更する必要がある場合は、保守担当者に新しい比較トラックを開始するよう指示する

例 3：検出用の表面に関するフォローアップ

入力

スキルは改善しました。README、セットアップ用プロンプト、コンパクト版の文言が古いかもしれません。

適切な方向性

• パケット：support-sync
• メインのラチェットが証明された後、またはメインの成果物には問題がなく、サポート用の表面だけが古くなっている場合にのみ実施する
• 広範なドキュメント変更を主な実験だったかのように装わず、マニフェスト／ドキュメントを同期する

例 4：ラチェット不要という結果

入力

現在のスキルはすでに凍結されたチェックに合格しており、レビュアーからのフィードバックも良好です。ただ、もう少し調整したい気がします。

適切な方向性

• パケット：ratchet-eligibility
• 保守担当者が具体的かつ根拠に基づく改善余地を示せない限り、no ratchet justified と結論づける
• 合格済みのベースラインを、不必要な変更から守る

例 5：対象外へ誘導

入力

アプリのプロンプト用に、オンラインのトレース、データセットの比較、ホスト型ダッシュボードが必要です。

適切な方向性

• パケット：route-out
• この作業はリポジトリ内でのスキルのラチェットではなく、LangSmith、Promptfoo、Braintrust、Weave に適していると説明する

ベストプラクティス

1. すべての実行で変更が必要だと決めつけず、no ratchet justified を妥当な成功状態として扱います。
2. 最初の本格的な編集を行う前に、評価器を凍結します。
3. サポートファイルが対象に含まれる場合でも、変更可能な主要成果物は 1 つに保ちます。
4. 意味のある変更を一度に 1 つだけ行います。
5. 完璧な簡易ケースより、代表的なプロンプトを優先します。
6. 成功した実験だけでなく、失敗した実験も記録します。
7. 同じハーネスで引き続き合格する場合に限り、入口を小さくすることを有効な副次的成果として扱います。
8. メインのラチェットが維持されてから、コンパクト版／ドキュメント／マニフェストを同期します。
9. リポジトリ内でのスキル保守、ホスト型評価プラットフォーム、ML の autoresearch の境界を明確に保ちます。

参考資料

• Upstream autoresearch-skill
• Karpathy/autoresearch
• Promptfoo
• LangSmith Evaluation