evidence-docs

根拠に裏付けられたドキュメント

主張は、確認する手段を伴って初めてドキュメントになります。 このスキルは規範であり、道しるべでもあります。10の規範と、それぞれの定義、適用、導入箇所を示します。

これはナビゲーターであり、二つ目の写しではありません。以下の各規範には、唯一の記載場所があります。それが規範3です。規範を言い換えるナビゲーターは、索引を付けているルールそのものに違反します。各規範の完全な記述、根拠、適用方法は、documentation.md → 規範 に記載されています。

10の規範

1. 主張にはその所在を添える — file:line、出力を伴うコマンド、テスト名。教訓にはコミットを明記します。
   • 1a. 証拠のように見えるトークンは、解決されるまでは証拠ではありません。 sha、行番号、パス、フラグ、テスト名。どれももっともらしく見えても存在しないことがあり、読み直されなくなるまさにその瞬間に信頼されます。コミットへの参照は、コミットの作成後に記入し、コマンドで確認します。
2. 数値は算出し、言い直しません。
   • 2a. シェルから得た数値は、一致した項目を確認するまでは測定値ではありません。 トークンが別のものに含まれる可能性がある場合は、件数のそばに一致項目を分類して出力します。また、終了ステータスが次の処理を左右するコマンドをパイプに渡してはいけません。そうすると、シェルはページャーについての結果を返します。この3つの数字を含む18行 と 18件のスロットリングイベント は、異なる主張です。
3. すべての事実には唯一の記載場所があります — それ以外の場所では、言い直さずにリンクします。
4. 参照先は、ドキュメントが読まれる場所を基準に解決されます — ドキュメントが置かれている場所を基準にするのではありません。
5. 誰も確認していないまま緑から赤に変わっても、証拠にはなりません。
   • 5a. 欠陥を再現できないほど小さなモデルでは、修正を証明できません。 まず再現し、それから修正します。未修正の入力で緑になるハーネスは、ハーネスとはいえません。モデルが対象より小さい場合は、欠けているものを数値とともにリストで明記します。
6. チェックが証明するのは、その適用範囲内のことだけです。
7. 沈黙は合格ではありません — 確認していないときに、その仕組みが何を出力するのかを確認します。
8. 推定値を測定値として発表してはいけません — ルールには証拠の条件を明記します。
9. 確認していないものは、確認したものと並べて出力します。
   • 9a. 測定されたゼロと未測定の数量を、同じように出力してはいけません — 規範9は不在を明記することを求め、9aは何も測定していないときに数値を提示しないことを求めます。
10. ドキュメントは、それを真実にした変更とともに公開します — 訂正は上書きせず、追記します。

これらは認識論的な規範であり、主張をドキュメントたらしめるものです。運用レイヤー、つまり所定のトリガーで何をすべきか、その確認方法と終了条件については、learned.md に記載されています。両者が同じことを述べているように見える場合、規範は なぜ を、ルールは どのように を示します。

次に読むもの

やろうとしていること	読むもの	理由
プロジェクトのドキュメントをゼロから整備する	documentation.md → The inventory	作業を始める前に、4つの質問に答えます
決定を記録し、作成者がいなくなっても残す	Registers and ids + templates/decisions.md	追記専用のID、エッジマーカー、決定の記録場所を1か所に定めます
変更を加え、ドキュメントを孤立させない	The Doc Loop + The propagation matrix	メタ行から始め、変更に応じて更新が必要なドキュメントを示します
事実をどこに記載するか決める	Single source of truth	片方を更新した日から、2か所に書かれた内容は食い違います
嘘をつけないチェックを構築する	gates.md	3つの軸、適用レベル、段階的な有効化、検証について説明します
成功を報告する仕組みを信頼する	gates.md → False success	確認する理由そのものを失わせる失敗について説明します
チェックをエージェント自身のツールに組み込む	hooks.md	フックの契約と、ガードがクラッシュしたときにアクションを許可する理由を説明します
既存のプロジェクトのドキュメントを監査する	setup.md	低コストなものから行う7つのパスと、修正計画としての出力について説明します
教訓を次の実行に引き継ぐ	retrospective.md	まずスタンプを付け（コールドトリガーが読み取ります）、次に10件の上限まで整理します。各教訓にはコミットを記載します
ホストプロジェクトにゲートを組み込む	templates/docgate.sh	グリーンな状態で組み込みます。入力がまだない場合は休止状態です
エージェントの動作を保証する	tdd.md → When the thing under test is an agent — このナビゲーターのディレクトリ外へのリンクは、スキル単体で配布するパッケージャーの環境ではリンク切れになるため、リンクではなく項目名を記載しています	アドレスはトレースIDと実行されたアサーションです（規範1）。誰も意見の相違を確認しなかった判定者は、誰も赤に変わるのを確認しなかったグリーンです（規範5）
変更全体を受け入れまで進める	task-pipeline スキル（別途インストール）	このスキルが標準であり、変更をリポジトリに反映する方法はそちらにあります

どのような場合に適用されるか

境界線は「事実として読まれるかどうか」です。 決定記録、README、受け入れレポート、ランブック、ユーザー向け変更履歴、監査結果、何かを検証したという主張が該当します。

このスキルの対象外： 下書き、考えを声に出して整理すること、チャットでの回答、コミットメッセージ、コードコメント。「確認させてください」に file:line を求めることは、実際に何かを守る場面でエージェントがルールを回避するよう仕向ける最も手っ取り早い方法です。

拒否の表現 — 「без доков」／「on my word」。 それ以外ならこのスキルが適用されるタスクで使われます。直接実行し、推定を測定値として提示するのではなく、その主張に裏付けがないことをはっきり述べてください（規範8）。

規範が仕える相手

要点はオペレーターの意図です。証拠は、その意図が現実に触れても揺るがないためのものです。 拒否する口実ではありません。

上記のすべては、オペレーターが本当に望んだ結果を得られ、途中で何も気づかれないまま壊れないようにするためにあります。オペレーターに「何を言ってよいか」を決めるためのものではありません。規範8を「検証されていない主張は書けない」と解釈して作業を拒否するスキルは、自らの目的を逆転させています。ルールを守り、ルールが仕えるはずの人を見失っているのです。

その境界線は次のとおりです。同じ境界線ではありません。

オペレーターがしてよいこと	オペレーターがしてはならないこと。これは拒否の根拠になります
まだ事実ではないことを主張する — 作成中の製品を説明するランディングページ、ロードマップ、売り込み	測定結果に、実際とは異なる内容を言わせること：合格したテスト、ベンチマーク、件数、引用
根拠がないと一度伝えられた後、承知のうえで裏付けのない主張を公開する	推定値を測定結果として提示すること（規範8）。これだけは、どんな意図があっても許されません

**したがって、裏付けのない主張への対応はこうです。一度伝え、明示し、作業を進める。**交渉でも、二度目の警告でも、質問に見せかけた黙った拒否でもありません。オペレーターが承知していると確認したら、その主張を将来の見通しであると示すマーカーを付けて公開します。ここでこのスキルが果たすべきことは、そのマーカーを付けることだけです。そして、タスクを完了します。

**そして、より難しい半分に取り組みます。**意図に従うことは最低限であり、提供する価値そのものではありません。価値を提供するとは、求められた内容を保ちながら、その意図をより良いものにすることです。より構造的で、より予測しやすく、保守や拡張が容易なものにします。従うだけのエージェントは、キーボードより遅いだけです。

唯一のテスト

文書を公開する前に、「どうやって分かったのですか？」と聞かれたら困る文を探し、その文に3つの方法のうち1つを適用します。根拠の場所を示す、削除する、またはオペレーターが裏付けのない主張として述べることを選び、公開したと明示する。3つ目の選択肢は抜け道ではありません。ほかの2つに意味を与えるものです。規則に従いながら先へ進む方法がなければ、人々はその規則を回避するようになります。そうなれば、根拠の場所を示すものは何も残りません。

これらの参照資料の編集について。ここにある references/ と templates/ 配下のファイルは生成されたコピーです。そのため、このスキルを単独でインストールしても、隣接するチェックアウトがなくてもすべてのリンクが解決されます。編集するのはコピーではなく、元のファイルです。どのファイルがどこから生成され、どう再同期するかについては、GENERATED.md を参照してください。

トリガー

説明は短縮版です。1.98.0まで記載されていた完全なトリガー一覧を、ここにそのまま移したものでも、このスキルが呼び出されます。

「真実として読まれるあらゆるものを書くとき、またはレビューするときに使用します。意思決定記録、README、受け入れレポート、ランブック、変更履歴の項目、監査所見、あるいは何かが検証済みであるという主張などが該当します。証拠に裏付けられた文書の10の規範 — 主張を単なる断言ではなく文書たらしめるもの — を適用し、それぞれの規範を実施する原則へと導きます。また、プロジェクトでドキュメントゲート、意思決定レジスター、伝播マトリックス、または作成者がいなくなっても残るレトロスペクティブが必要な場合にも使用します。トリガー — 『ドキュメントゲート』、『意思決定記録』、『ADR』、『受け入れレポート』、『ランブック』、『これは検証済みですか』、『доказательная документация』、『записать решение』、『запиши решение』、『отчёт о приёмке』、『раннбук』、『чем это подтверждено』、『доки в синхроне』。対象外：下書き、チャットの回答、コミットメッセージ、コードコメント — 対象外にするには『без доков』と言ってください。」