validator-help

/validator-help

バリデータの動作をエビデンスに基づいて診断します。このスキルは診断専用です — 何が起こったのか、なぜ起こったのかを説明しますが、問題を自動修正することはありません。ソースコードではなく、実行時の成果物と CLI 出力に基づいて動作します。

診断ワークフロー

すべての診断の質問に対して、次の順序に従ってください。

1. log_dir を解決する: .validator/config.yml を読み取り、log_dir フィールドを抽出します（デフォルト: validator_logs）。以下のすべてのログパスは <log_dir>/ からの相対パスです。
2. まずパッシブなエビデンス: コマンドを実行する前にファイルを読み取ります。
   • <log_dir>/.debug.log — タイムスタンプ付きのイベントログ（コマンド、ゲートの結果、状態の変化、エラー）
   • <log_dir>/.execution_state — last_run_completed_at、branch、commit、working_tree_ref、unhealthy_adapters（アダプター名 → {marked_at, reason}）を含む JSON
   • <log_dir>/console.*.log — 実行ごとのコンソール出力（番号が最も大きいものが最新）
   • <log_dir>/check_*.log — チェックゲートの出力
   • <log_dir>/review_*.json — 違反（file、line、issue、fix、severity、status）を含むレビューゲートの結果
   • .validator/config.yml — プロジェクトの設定
3. 必要に応じてアクティブなエビデンス: パッシブなエビデンスが確実な診断には不十分な場合にのみ、CLI コマンドを実行します。
4. エビデンスを挙げて説明する: 確認された所見と推測を明確に区別します。

エビデンスのソース

ソース	確認できる内容
.validator/config.yml	log_dir、base_branch、entry_points、cli.default_preference、max_retries、rerun_new_issue_threshold
<log_dir>/.debug.log	タイムスタンプ付きのイベント履歴: 実行されたコマンド、ゲートの結果、状態の遷移、エラー
<log_dir>/.execution_state	最後に成功した実行のタイムスタンプ、そのときのブランチ/コミット、作業ツリーのスタッシュ参照、異常なアダプターのクールダウン
<log_dir>/console.*.log	各実行イテレーションの人間が読める形式の出力
<log_dir>/check_*.log	チェックゲートのコマンド（リンター、テストランナーなど）からの生の出力
<log_dir>/review_*.json	ファイル、行、問題、優先度、解決ステータスを含む構造化されたレビュー違反
<log_dir>/.validator-run.lock	ロックファイル（PID を含む） — 実行がアクティブな間のみ存在します
<log_dir>/.ci-wait-attempts	CI 待機の試行回数カウンター

CLI コマンド早見表

これらはパッシブなエビデンスが不十分な場合にのみ使用してください。

コマンド	使用するタイミング
agent-validate list	設定されているゲートとエントリポイントを確認する
agent-validate health	アダプターの可用性とヘルスステータスを確認する
agent-validate detect	どのファイルが変更され、どのゲートが適用されるかを確認する
agent-validate validate	config.yml の構文とスキーマを検証する
agent-validate clean	現在のログをアーカイブして状態をリセットする（破壊的 — 最初にユーザーに確認してください）

ルーティングロジック

ユーザーの質問に基づいて、詳細なガイダンスのために適切な参照ファイルを読み込みます。

質問の領域	参照ファイル
設定の欠落、YAML エラー、設定ミス、init の問題	references/config-troubleshooting.md
チェックの失敗、レビューの失敗、no_changes、no_applicable_gates、rerun モード	references/gate-troubleshooting.md
ロックの競合、古いロック、並列実行、クリーンアップ	references/lock-troubleshooting.md
アダプターのヘルス、不足しているツール、使用制限、クールダウン	references/adapter-troubleshooting.md

質問が複数の領域にまたがる場合は、関連する各参照ファイルを読み込んでください。

出力の契約

すべての診断レスポンスには、次のセクションを必ず含める必要があります。

診断

何が起こったのか、なぜ起こったのかを明確に述べます。

エビデンス

読み取った具体的なファイル、確認されたフィールドの値、診断を裏付けるコマンド出力。関連するログ行や設定値を引用してください。

信頼度

次のいずれかです：

• 高 — 診断が直接的な証拠によって完全に裏付けられている
• 中 — 診断の可能性が高いものの、一部の証拠が欠けている
• 低 — 診断が推測に基づいており、重要な証拠が入手できない

次の場合は信頼度を下げてください：

• .debug.log または .execution_state が存在しない、または空である
• 出力で参照されているログファイルが存在しない
• 設定値を検証できない
• CLI コマンドが失敗する、または予期しない出力を返す

次のステップ

ユーザー向けの実行可能な推奨事項です。信頼度が高くない場合は、診断を確定するためにどのような追加証拠が必要かを提案してください。

バグの報告

診断を完了したら、次のルーティングロジックを適用して、GitHub Issue を起票すべきかどうかを判断してください：

• 信頼度が高く + バグが示唆される（証拠が設定の問題、ユーザーの誤り、想定される動作ではなく、agent-validator の欠陥を指し示している）：validator-issue を引数 --auto-file <診断サマリー> を付けて自動的に呼び出します。これにより、診断サマリーがバグの説明として渡され、対話的な確認がスキップされます — Issue はドラフトの表示直後に起票されます。
• 信頼度が高く + バグではない（診断の結論が設定の問題、ユーザーの誤り、または想定される動作である）：何も行いません。validator-issue を呼び出さないでください。
• 信頼度が中程度 + バグの可能性（証拠が validator の欠陥の可能性を示唆しているものの、決定的ではない）：ユーザーに次のように尋ねます：「これは validator のバグである可能性があります。GitHub Issue を起票しますか？」ユーザーが確認した場合は、診断サマリーをバグの説明として validator-issue を呼び出します。ユーザーが拒否した場合は、起票せずに終了します。
• 信頼度が低い：何も行いません。ユーザーに問いかけず、validator-issue も呼び出さないでください。