simulation-failure-triage

シミュレーション失敗のトリアージ

目標

よくあるシミュレーション失敗の兆候を分類し、直ちに行うべき対応、再試行の段階的手順、停止条件を返します。

要件

• Python 3.10+
• 外部依存関係なし
• Linux、macOS、Windows で動作

収集する入力

入力	説明	例
コード	シミュレーションコード	LAMMPS、VASP、MOOSE、QE
ステージ	セットアップ、実行時、後処理	runtime
症状	失敗の兆候	nan,pressure-blowup
ログテキストまたはファイル	エラーの証拠	Lost atoms、ZBRENT
最近の変更	最後に変更した設定	larger timestep

判断の指針

• まず、ログ、入力ファイル、実行ファイルのバージョン、スケジューラーの出力などの証拠を保全します。
• セットアップエラー、数値的不安定性、物理モデルの問題を切り分けます。
• 管理された変更を1つだけ加えて再試行します。
• 結果が科学的な意味を失う場合や、必須のモデル入力が不足している場合は、再試行を中止します。

スクリプトの出力

scripts/failure_triage.py は次を出力します。

• likely_causes
• immediate_actions
• retry_ladder
• stop_conditions
• evidence

ワークフロー

python3 skills/robustness/simulation-failure-triage/scripts/failure_triage.py \
  --code LAMMPS \
  --stage runtime \
  --symptoms nan,pressure-blowup \
  --recent-change "increased timestep" \
  --json

エラー処理

無効なステージやサイズ超過のログファイルがある場合は、終了コード 2 で停止します。不明な症状はカスタム証拠として保持されます。

制限事項

このスキルは初動のトリアージを行います。失敗したシミュレーションを修復できることを保証するものではありません。

検証チェックリスト

• 再実行する前に、保全した証拠一式を記録しました。元の失敗を再現できるよう、コピーしたログ、入力ファイル、スケジューラーの出力、実行ファイル／バージョン文字列を保存しました（最初の immediate_actions 項目に従ってください）。
• 最終的なクラッシュ行だけでなく、実行時に最初に出た警告／エラーを引用し、evidence.log_excerpt（先頭500文字、大文字・小文字は元のまま）にその内容が含まれていることを確認しました。抜粋に根本原因を示す兆候が含まれていない場合は、--log-file／--log-text を指定して再実行してください。
• すべての likely_causes 項目について、symptom、category、first_action を記録し、キーワードが LOG_HINTS／PATTERNS にないために、実際の兆候が category: custom に分類されていないことを確認しました。
• 失敗カテゴリが誤って分類されていないことを確認しました。segfault／SIGSEGV／signal 11／core-dumped は crash（corrupted-output ではありません）に、OOM／bad_alloc／oom-kill は out-of-memory（incomplete-run ではありません）に分類されます。
• retry_ladder に従い、一度に変更する項目を1つに限定し、各段階で変更したパラメーター1つとその効果を記録しました（メモリがボトルネックの場合は、メモリに関する段階も含みます）。
• すべての stop_conditions 項目を確認し、いずれかの条件に該当した場合（例：検証できないポテンシャル／擬ポテンシャル、任意の安定化設定に依存する結果）は、場当たり的な安定化調整を重ねず、再試行ループを停止しました。
• 数値的な復旧後は、ここで成功と判断するのではなく、保存則／物理的な範囲／「これらの結果を信頼できるか」の確認のために simulation-validator スキルへ引き継ぎました。

よくある落とし穴と誤った正当化

ありがちな近道	なぜ誤りなのか／何をすべきか
「ログの最終行がエラーだから、そこを修正します。」	最後のクラッシュ行は下流の症状であることがよくあります。スクリプトに2つ目の immediate_actions 項目があるのは、最初の警告／エラーこそが真の原因だからです。evidence.log_excerpt に記録し、そこからトリアージしてください。
「セグフォルトが起きたので、出力ファイルが破損しているかディスクの問題です。」	crash（SIGSEGV／signal 11／core dumped）は、範囲外アクセス、ヌルポインター、ABI のバグを示し、gdb／valgrind／ASan での再現が必要なメモリーフォールトの分類であり、I/O の問題ではありません。corrupted-output として扱わないでください。
「ジョブが強制終了されたので、walltime を増やします。」	killed だけでは真に曖昧なため、incomplete-run のままです。OOM の兆候（bad_alloc、oom-kill、「out of memory」）は別個の out-of-memory 原因であり、walltime を増やすのではなく、メモリー削減／--mem の増加が必要です。
「実行できるように、dt を下げ、プリコンディショナーを変更し、さらにバロスタットも調整します。」	再試行の手順では、各段階で変更するのは1つだけです。修正を重ねると結果が「恣意的な安定化の変更に左右される」ことになり、明示的な stop_conditions のトリガーになります。パラメーターを1つ変更して効果を記録し、その後に進んでください。
「不足していた PAIR coeff のパスを追加したら実行できたので、物理的な設定も問題ありません。」	missing-potential／bad-pseudopotential を修正して正常に実行できても、解決したのはセットアップの問題であり、妥当性ではありません。元素種の対応付け、価電子数、汎関数が誤っている可能性は残ります。実行完了は正しさを意味しません。
「今は実行できるので、トリアージは完了です。」	トリアージで復旧するのは実行だけです。保存則、物理的な境界、収束性はここでは対象外です。数値を信頼する前に、simulation-validator に確認を委ねてください。

セキュリティ

入力検証

• --stage は固定の許可リスト（setup、runtime、postprocess、unknown）と照合されます。それ以外の値が指定されると、コード 2 で終了します。
• --code は空でなく、100文字以下である必要があります。空の値または長すぎる値が指定されると、コード 2 で終了します。
• --symptoms はカンマで分割され、最大50項目に制限されます。各項目は100文字以下です。いずれかの上限を超えると、コード 2 で終了します。
• 不明な症状は拒否されず、黙って破棄されるのではなく、custom の証拠として保持されます。
• 数値引数はないため、有限値／正の値のチェックは適用されません。
• 入力検証の失敗（およびログの読み取りエラー）はすべて捕捉され、stderr メッセージとともにコード 2 で終了します。

ファイルアクセス

• 読み取るファイルは、省略可能な --log-file パスだけです。省略した場合、スクリプトはファイルを読み取りません。
• 読み取り前に、stat でログファイルのサイズが確認されます。10 MB の上限（MAX_LOG_SIZE）を超える場合、スクリプトはエラーを発生させ、コード 2 で終了します。ファイルの内容と --log-text は、どちらも10 MB に切り詰められます。
• スクリプトはファイルを書き込みません。すべての結果は stdout に出力されます（--json を指定した場合は JSON、それ以外はプレーンテキスト）。
• パスのサンドボックス化に関する注意点：ログのパスは作業ディレクトリに制限されていないため、スクリプトは呼び出し元のプロセスに読み取り権限があるファイルなら何でも読み取れます。信頼できるパスのみを指定してください。

ツールの制限

• allowed-tools は Read, Bash, Write, Grep, Glob です。
• Bash は同梱の scripts/failure_triage.py のみを実行します。
• Read はスキル独自のファイルと、ユーザーが指定したログを開いて失敗の証拠を確認します。Grep／Glob はログファイル、入力、過去の出力を検索します。Write はユーザーの指示に従ってトリアージのメモや保存した証拠を記録します。同梱のスクリプト自体はファイルを書き込みません。

安全対策

• eval／exec および動的なコード実行はありません。ログのテキストはデータとして扱われ、実行されることはありません。
• スクリプトはサブプロセスを起動せず、外部ソルバーも実行しません。
• 出力は構造化 JSON（--json）で、機械的に検証できます。
• DoS 対策としてリソース使用量に上限を設けています。ログサイズ／テキストは10 MB、症状は50件、code と各症状は100文字までです。

参考資料

• よくある失敗の兆候と再試行の手順については、references/failure_patterns.md を参照してください。

バージョン履歴

• 1.1.3：Verification checklistを追加（failure_triage.pyの出力に基づくエビデンス重視のチェック項目 — エビデンス保持セット、最初のエラーの抜粋、カテゴリ誤分類の防止策、1つずつ変更する再試行手順、停止条件、simulation-validatorへの引き継ぎ）し、最終行だけに基づくトリアージ、セグメンテーションフォールトをI/Oエラーとみなすこと、OOMと実行時間上限の混同、安定化のための変更の重ね合わせ、「実行できたから有効」といった項目を網羅するCommon pitfalls & rationalizationsテーブルを追加。
• 1.1.1：評価を識別力のあるものに強化 — 各ケースでscript_checksを使ってfailure_triage.pyの正確なJSON出力（特定のcategory／first_action文字列、ログヒントに基づく症状の推定、固定された再試行手順／停止条件のテキスト、最近の変更に対する即時アクション）を指定するようにし、一般的なトリアージ知識ではなく、スキルの実際の出力を評価するように変更。
• 1.1.0：専用のout-of-memoryおよびcrash（セグメンテーションフォールト）分類を追加。セグメンテーションフォールトとOOMをI/Oエラーまたは実行中断として誤分類しないように変更。元のケースのログ抜粋を保持。入力検証の上限（症状、コードの長さ）を追加。シミュレーションバリデーターによる詳細な検証に委ねるよう説明を明確化。missing-potentialの評価トークンを修正。
• 1.0.0：コード横断シミュレーションの障害をトリアージするスキルの初回リリース。