proof-of-work

「正しく見える」ことは、「動作を検証した」ことではありません。 実証可能な根拠をもってその隔たりを埋めるのが、実証の規律です。 タスクが完了したと主張する前に、再現可能な根拠を示します。

実証

使用しない場合

• 実装前の計画（imbue:karpathy-principles を使用）
• 作業がスコープ内かどうかの判断（imbue:scope-guard を使用）

概要

「実証」手法は、タスクが完了したと述べる前に技術的な検証を必須とすることで、時期尚早な完了の主張を防ぎます。たとえば、LSP の設定が再起動後に機能すると決めつけず、サーバーが起動し、ツールがクエリに応答することを検証します。この方法により、ユーザーが検証を試みる前に、解決策が機能することを確認できます。

完了を主張する前に、解決策の性能について再現可能な根拠を示し、エッジケースにも対処してください。すべての主張は、現在の環境で取得した実際のコマンド出力によって裏付ける必要があります。

鉄の掟

失敗するテストなしに実装しない 根拠なしに完了を主張しない 理解せずにコードを書かない

鉄の掟は、テストが形だけの作業になることを防ぎます。テストを書く前に実装を計画すると、RED フェーズが設計を主導できません。完了を宣言する前に、そのアプローチの技術的な根拠と限界を理解してください。コードを書く前に、対処する失敗の根拠を記録し、テストが実装を主導していることを確認してください。

検証と TDD のワークフロー

実装の基本と、代替案ではなくその方法を選んだ理由を検証してください。常に機能するはずだと述べるのではなく、解決策が失敗する可能性のある箇所を特定してください。TDD サイクルでは、次の手順が必須です。

1. RED：実装の前に、失敗するテストを書く。
2. GREEN：テストに合格する最小限の実装を作成する。
3. REFACTOR：動作を変えずにコードを改善する。

鉄の掟のセルフチェック

セルフチェックの質問	答えが誤っている場合	対応
失敗や必要性を示す根拠を記録していますか？	いいえ	停止し、まず失敗を記録する
先入観で決めた実装をテストしていますか？	はい	停止し、テストに設計を主導させる
設計に不確かさを感じていますか？	いいえ	停止する。不確かさは良い兆候です
テストが実装を主導しましたか？	いいえ	停止する。手順が逆です

鉄の掟の進捗追跡

• proof:iron-law-red：実装前に失敗するテストを作成した。
• proof:iron-law-green：最小限の実装がテストに合格した。
• proof:iron-law-refactor：動作を変えずにコードを改善した。
• proof:iron-law-coverage：カバレッジのゲート（行、分岐、ミューテーション）に合格した。

行、分岐、ミューテーションのすべてのカバレッジゲートに合格していることを確認してください。詳しい適用パターンについては、iron-law-enforcement.md を参照してください。

使用基準

作業が「完了」「終了」「準備完了」と述べる前に、このスキルを適用してください。解決策を推奨する前や、設定が「機能するはずです」と述べる前にも使用してください。テストせずに設定が正しいと決めつけていたり、問題を再現せずに修正を推奨していたりすることに気づいたら、作業を止めてください。実際に検証せずに「正しく見える」と考えるのは危険信号です。設定の各行が何を意味するか、あるいは特定の手法が現在の状況に適用される理由を説明できない場合、必要な検証手順が省略されています。

エージェントの報告は主張であり、根拠ではありません

これは作業がどこで行われた場合にも当てはまり、ファイルシステムもシェルもないワークフロースクリプト内では、特に重要です。スクリプトが知っていることはすべて、エージェントから伝えられたものです。「テストに合格した」と返すステージも、「動作するはずです」と言うセッションと同じ種類の発言であり、同じ重みしかありません。つまり、重みはありません。

したがって、ワークフローでは調査、順位付け、構成、提案ができます。根拠を生み出す実行は、その出力を貼り付けられる場所で行います。ワークフローの戻り値はゲートへの入力になります。ゲートそのものではありません。

検証プロトコル

ステップ 1：問題を再現する（proof:problem-reproduced）

解決策を提案する前に、現在の状態を確認します。 ps、echo、cat などのツールを使って、実行中のプロセス、環境変数、 設定ファイルを確認します。コマンドの出力とエラーログで、問題を記録します。

ステップ 2：解決策をテストする（proof:solution-tested）

解決策が機能すると主張する前に、現在の環境で実行します。 実際の出力を記録し、期待される動作と一致することを確認します。 想定した出力に頼ってはいけません。

ステップ 3：既知の問題を確認する（proof:edge-cases-checked）

このアプローチに関連する既知のバグや制限事項を調査します。 GitHub の issue、バージョンの互換性、公式ドキュメントを確認し、 潜在的な障害要因やよくある落とし穴を特定します。

ステップ 4：証拠を記録する（proof:evidence-captured）

imbue:proof-of-work を使って、実行したコマンド、その出力、 タイムスタンプ、各ステップから導いた結論を記録します。

ステップ 5：完了を証明する（proof:completion-proven）

受け入れ基準を定義し、各項目を検証します。障害要因が特定された場合は、 完了したと主張するのではなく、証拠を添えて診断を記録し、 回避策を提示します。

統合

改善ワークフローとの連携

proof-of-work を使って、/update-plugins または /fix-workflow によって 特定された改善機会を検証します。ベースラインの指標（ステップ数、失敗率、所要時間）を 記録し、提案された変更をテストして、改善後の指標を記録し、定量的な効果を示します。

検証チェックリスト（「完了」と主張する前に）

問題が証拠とともに再現され、実際の環境で解決策がテストされたことを確認します。 既知の問題を調査し、エッジケースを検討します。再現可能な形式で証拠を記録し、 すべての受け入れ基準が満たされていることを確認します。完了を伝える際は、 実行した具体的なテストとその結果を詳しく記し、各主張の根拠となる証拠を引用します。

危険信号のセルフチェック

完了メッセージを送信する前に、推奨されたコマンドを実行し、 その出力を記録したことを確認します。既知の問題を調査し、 ユーザーが検証手順を再現できることを確認します。推測ではなく、 証明できていることを確認します。

補助モジュール

• TodoWrite の命名パターン：imbue TodoWrite 項目の 命名規則と安全な削除ルール
• 証拠の記録：体系的な証拠の記録、 監査証跡、再現性のあるパターン
• 独立した検証：重大な変更において、 作成したエージェントが唯一の検証者であるべきではない理由と、 独立したチェックとして認められる条件
• 検証者の完全性：チェックが実際に機能しているかどうか： 仕様を別途検証し、動作が壊れたときにチェックが失敗することを証明し（ミューテーション／リバート）、 LLM による判定より、実行可能なチェックやプロパティベースのチェックを優先します

関連スキル

• imbue:karpathy-principles：「目標主導の実行」原則は、 アイアン・ローをプレフライトゲートとして活用できる、4 つの原則からなる統合フレームワークです
• ゲートとスキルの連携グラフ全体については、 docs/quality-gates.md#skill-level-quality-gate-composition を参照してください

終了基準

• すべての実装変更に、テストファーストで実行したことを確認する 対応する TodoWrite 項目（proof:iron-law-red、proof:iron-law-green）がある。
• 実際のコマンド実行とその出力に裏付けられた [E1]／[E2] の証拠参照が、 応答内に少なくとも 1 つある。
• すべての受け入れ基準が明示され、目視ではなく実行によって それぞれ検証されている。
• 障害要因がある場合は、正確な失敗出力と、解消するための 次の具体的な手順が記録されている。
• 最終回答に、裏付けとなる証拠なしで「動作するはず」「正しいように見える」 または「動作するだろう」という主張が含まれていない。