result-diagnosis

結果の診断

実験結果がプロジェクトにとって何を意味するのかを診断します。このスキルは、結果が出た後の意思決定に使用します。特に、結果が否定的、予想外、不安定、または解釈しにくい場合に役立ちます。

次の場合にこのスキルを使用します。

• 手法がベースラインを上回らない
• シードによって結果が大きく異なる
• ある指標は改善するが、別の指標は悪化する
• ベースラインが予想外に優れている
• プロットや表に不審な点がある
• 結果の原因が実装のバグ、指標のバグ、データの問題、不公平な比較の可能性がある
• 初期の実験結果から、アルゴリズムや論文の主張の見直しが必要と思われる
• ユーザーから「この結果は何を意味しますか？」や「次に何をすべきですか？」と尋ねられた

洗練されたレポートの作成には、このスキルを使用しないでください。診断が明確になった後で、experiment-report-writer と組み合わせてください。

このスキルは、次のスキルと組み合わせてください。

• 診断内容を主張、エビデンス、リスク、アクション、またはワークツリーの状態に反映する場合は、research-project-memory
• 結果を共有可能なレポートにまとめる場合は、experiment-report-writer
• 診断から手法の見直しが必要と判断される場合は、algorithm-design-planner
• 診断から新たな統制実験が必要と判断される場合は、experiment-design-planner
• 次のステップが再実行、サニティチェック、またはアブレーションの場合は、run-experiment
• 適切な対応が論文の主張の絞り込みや再構成の場合は、conference-writing-adapter

スキルのディレクトリ構成

<installed-skill-dir>/
├── SKILL.md
└── references/
    ├── diagnosis-taxonomy.md
    ├── evidence-audit.md
    ├── next-decision-rules.md
    ├── report-template.md
    └── triage-protocol.md

段階的な読み込み

• 必ず references/diagnosis-taxonomy.md、references/triage-protocol.md、references/next-decision-rules.md を読みます。
• ログ、設定、指標、プロット、実行結果、またはコードの状態を調べる場合は、references/evidence-audit.md を読みます。
• 詳細な診断レポートには references/report-template.md を使用します。
• 結果が現在のSOTA、ベンチマークの慣例、または最近のベースライン性能に依存する場合は、ウェブ検索またはユーザーが提供した論文で最新の情報を確認します。

基本原則

• 最適化する前に診断します。
• 観測された結果と解釈を分けます。
• コストの高い再実行より先に、簡単なサニティチェックを優先します。
• 否定的な結果も情報として扱います。プロジェクト全体ではなく、主張を取り下げる判断につながる場合があります。
• 実装、データ、指標、ベースライン、選択ルールを確認する前に、アルゴリズムのせいにしないでください。
• 統制された証拠を繰り返し確認して主張が否定される場合、実装のせいにし続けないでください。
• すべての診断の最後に、デバッグ、再実行、アブレーション、手法の見直し、主張の絞り込み、執筆、保留、または中止のいずれかの判断を示します。
• 不確実性を明示的に記録します。

ステップ1 - 結果と期待される挙動を定義する

次の項目を抽出します。

• 実験の問いと、それに関連する主張
• 手法とベースライン
• データセット／分割
• 指標と期待される方向
• 観測された結果
• シード／反復の数
• 設定、コミット、ログ、表、図
• どのような結果を期待していたか、その理由
• この結果が論文の主張に影響するのか、内部デバッグだけに関わるのか

曖昧な入力を次のように書き換えます。

Expected [method] to improve [metric/diagnostic] over [baseline] on [setting], but observed [result] under [controls].

期待される挙動が定義されていなかった場合は、experiment-design-planner に戻します。

ステップ2 - 症状を分類する

references/diagnosis-taxonomy.md を読みます。

主な症状を分類します。

• 改善がない
• 性能低下
• 不安定性または高い分散
• 指標間の不一致
• 不自然に大きな性能向上
• ベースラインが予想外に強い
• 診断結果と性能の不一致
• 学習の失敗または発散
• 再現性の失敗
• プロット／表の不整合
• 結果が論文のストーリーと矛盾する

次に、考えられる診断カテゴリを分類します。

• 実装のバグ
• 指標／評価のバグ
• データ／分割／前処理の問題
• 不公平なベースラインまたはチューニングの問題
• シードの分散または反復不足
• 最適化／ハイパーパラメーターの問題
• 手法のメカニズムの失敗
• 規模／適用領域の不一致
• 主張とエビデンスの不一致
• 想定どおりの否定的な結果

ステップ3 - エビデンスを収集する

references/evidence-audit.md を読みます。

一次成果物を優先します。

• 設定の差分
• 実行コマンド
• gitコミット
• ログと標準エラー出力
• 指標ファイル
• チェックポイント
• シード
• データセットのバージョンと分割のハッシュ
• プロットと表
• 以前のベースラインの実行結果
• 実装の変更

推測せず、証拠が不足していることを明記します。

Step 4 - トリアージの実施

references/triage-protocol.md を読んでください。

次の順序で確認します。

1. 再現性と出所：正しいコミット、設定、データ、シード、出力先であること。
2. 指標と評価：指標の方向、集約方法、分割、データリーク、後処理。
3. ベースラインの公平性：予算、チューニング、チェックポイントのルール、データ、サンプラー、コードパスが同じであること。
4. 実装の健全性：機能フラグ、テンソルの形状、勾配の流れ、損失のスケール、学習／評価モード。
5. 統計的安定性：シード、分散、信頼区間、外れ値。
6. メカニズムの診断：意図したメカニズムに変化があったかどうか。
7. 主張との整合性：結果が論文の主張を裏付けるか、弱めるか、反証するか。

進行を止めるバグ、または無効な比較が見つかった場合に限り、そこで中断してください。

Step 5 - 競合する説明を組み立てる

考えられる説明ごとに、次の内容を示してください。

• その説明を支持する証拠
• その説明に反する証拠
• 説明を判別できる最も低コストなテスト
• 説明が正しい場合の判断

最低限、次の可能性を検討してください。

• バグ
• 不適切な指標
• 実験設計の不備
• 強すぎる、またはチューニング不足のベースライン
• ハイパーパラメーターの問題
• メカニズムの誤り
• 主張の範囲が広すぎる

Step 6 - 次の判断を選ぶ

references/next-decision-rules.md を読んでください。

主な判断を1つ選んでください。

• debug：バグまたは出所の問題を解決するまで、結果を信頼できない
• rerun：結果は妥当そうだが、検出力が不足しているか、対照実験が欠けている
• ablate：メカニズムを切り分ける必要がある
• revise-method：メカニズムの設計変更が必要と思われる
• narrow-claim：証拠がより限定的、または異なる主張を支持している
• write：報告するのに十分な信頼性が証拠にある
• park：結果は結論が出ておらず、直ちに計算リソースを使う価値がない
• kill：公平な対照条件のもとで、主張または研究の方向性が反証された

基本的な出所または公平性が未解決の場合は、write を選ばないでください。

Step 7 - 診断結果を書く

完全なレポートには references/report-template.md を使用してください。

プロジェクトに保存する際、パスが指定されていない場合は、次を使用してください。

docs/diagnosis/result_diagnosis_YYYY-MM-DD_<short-name>.md

必須の出力：

# Result Diagnosis: [Short Name]

## Result Snapshot
## Expected vs Observed
## Symptom Classification
## Evidence Checked
## Competing Explanations
## Most Likely Diagnosis
## Decision
## Next Checks or Actions
## Claim Impact
## Project Memory Writeback

Step 8 - プロジェクトメモリに書き戻す

プロジェクトで research-project-memory を使用している場合は、次を更新してください。

• memory/evidence-board.md：観測された結果、制約、ソースパス
• memory/provenance-board.md：診断がソースの有効性に依存する場合、結果の出所を検証済み、古い、矛盾あり、または不明として記録
• memory/claim-board.md：裏付けられた、弱められた、修正された、証拠が必要、暫定、保留、または削除された主張
• memory/risk-board.md：バグ、指標のリスク、ベースラインのリスク、メカニズムのリスク、または主張のリスク
• memory/action-board.md：デバッグ、再実行、アブレーション、手法の修正、執筆、保留、または中止のアクション
• memory/handoff-board.md：診断によって後続作業が変わる場合は、手法設計、実験設計、論文の証拠、または執筆への引き継ぎを作成
• memory/phase-dashboard.md：診断によって証拠の作成が進む場合、またはプロジェクトがデバッグ、手法の修正、主張の範囲縮小に戻る場合は、アクティブなゲートを更新
• worktree .agent/worktree-status.md の "Local Hot Results"：コードの worktree 内にいる場合は、まずここを更新。昇格する前に、ローカルで確認済み／無効化済み／置き換え済みの状態を記録
• <ProjectRoot>/memory/hot-results.md：結果が確認済みで、プロジェクトレベルの主張を変える場合に限り、ここへ昇格。診断が進行中の間はここに書き込まない
• memory/decision-log.md：主張の中止、手法の変更、範囲の縮小など、長期的に残す判断

検証済みの結果には observed を、説明には inferred を使用してください。古くなった主張は明示してください。

最終確認

完了する前に、次の点を確認してください。

• 観測された結果と解釈が区別されている
• 出所と設定が確認済み、または未確認として記載されている
• 指標の方向と集約方法が明確である
• ベースラインの公平性に対処している
• 実装の健全性チェックを考慮している
• シード間の分散と反復を考慮している
• 関連する場合、メカニズムの診断を確認している
• 結果が具体的な判断に結び付けられている
• 論文の主張への影響が明示されている
• プロジェクトメモリが存在する場合、更新されている