systematic-debugging

実行

バグ、失敗、または予期しない動作：

1. 切り分け — エラーを読み、再現し、差分を確認して、診断レイヤーを上位へたどります。 L1 症状 → L2 ロジック → L3 システム → L4 アーキテクチャ → L5 システム間 契約 → L6 プラットフォーム → L7 仕様のギャップ。レイヤーは観察の高度を 示すものであり、単一の因果連鎖ではありません。停止する高度における因果の形を、 根本原因を断定する前に明示的に分類します。再発を生み出す要因を因果的証拠で 説明できるか、T クラス境界に到達するまで停止しないでください。
2. オーナーを特定 — 正常な動作と比較し、不正な値を追跡して正規のオーナーを 特定します。オーナーの重複は調査結果として扱います。
3. 編集前に判断 — 修正の前に、共有ロジック、契約、フォールバック、アダプター、 プロデューサー／コンシューマーの境界、または信頼できる唯一の情報源の境界が 関係する場合は、Patch-Shape Triage と Ripple Signal Triage を実行します。 新たなソースコードの経路や重要なソース編集については、Change Necessity を明示します。 新たな分岐、フォールバック、アダプター、オーナー、または互換性経路については Minimality Check を実行し、オーナーに過剰な負荷がかかっている場合や複雑さが 増す場合は Pre-Edit Complexity Check を実行します。Change Necessity が code-change を選択した後、最初の修正編集に着手する前に、 test-driven-development に従って修正対象に対する TDD Route を決定します （デフォルトは off、動作／バグ修正／共有／契約／永続化／権限／移行のリスクがある場合は strict）。
4. 立証 — 最小限の再現または検証で、1 つの仮説を検証します。最初に失敗する テストが必須なのは、記録された TDD Route: strict の場合に限られます。 TDD Mode: off では、失敗するテストや RED/GREEN サイクルを必須にしないでください。 修正に 3 回失敗したら停止し、アーキテクチャを疑ってください。
5. 修正して完了 — 正規のオーナーで最小限の修正を行い、リスクに応じて検証し、 アーキテクチャをレビューして、修正と廃止の両方のトラックを完了します。 症状が残る、または変化した場合は因果モデルを見直し、別の不具合だと決めつけないでください。

完了条件：信頼度 ≥ B、因果ステータスが再発の証拠または外部の終端と一致し、 トラックが明示され、H シグナルがなく、必須の D 証拠に合格していること。

コア不変条件

根本原因を見つけ、バグの種類を正規のオーナーで修正します。最小限の修正とは、 テキスト上の差分が最小であることではなく、オーナーレベルで必要十分な修正が 最小であることです。すべてのバグに同じ因果的十分性の基準を適用します。関連する 影響を追跡して除外の根拠を示し、解決策を維持する前に修正方針を左右する不明点を 解消します。実験は完了前に行ってもかまいません。調査の深さを決めるのは、見かけ上の 規模やリスクではなく、証拠の不足です。

バグのクイックレーン

証拠に裏付けられた、局所的で再現可能な単一オーナーのバグで、パッチ形状に シグナルがない場合は、読み返しを簡潔にします：Symptom、Reproduction、 Root Cause、Change Necessity、Fix Boundary、Verification。因果証明の オーナーが Quick Exit Proof に合格した場合に限り、因果カードを省略します。 これにより読み返しは簡潔になりますが、因果関係の網羅性や証拠の基準は変わりません。 クイックレーンでは、ソース編集の前に Change Necessity を明示する必要があります。 ユーザーに見える必要性、変更しない／コード以外で対応する選択肢、コードを変更する 必要性、最小境界、Decision: code-change のような明示的な判断トークンを 1 文で示してもかまいません。共有ロジック、契約、フォールバック、重複オーナー、 コンシューマー側のパッチ、またはモジュール間の動作が見つかった場合は、このレーンを 離れてください。

Aegis Visibility は、証拠／オーナー／パッチ形状／検証への影響を示します。 根本原因、回避した誤修正、境界、証拠、複雑さ、リスクを verification-before-completion に引き継ぎます。別途、完了記録は不要です。

修復の前に診断する

UI／インタラクションの不具合では、ユーザーに見える接点における関連状態と 復旧ルールを定めるため、ui-ux-governance を組み合わせます。再現と根本原因の 特定はここで担います。手動確認の提案は、実施済みの証拠ではありません。

1. エラー／スタックトレース全体を読み、入力、環境、バージョン、成功条件を 記録します。正しい対象で、最終的な提供まで含めて、ユーザーが失敗した結果を 再現します。解析の成功や内部チェックの合格だけでは、失敗が見えないことが あります。ハードコードされた例ではなく、修正後の動作と関連する隣接ケースを 検証します。読み取り専用の診断は、修正を許可するものではありません。
2. 一貫して再現させます。再現が不安定な場合は、断続的またはタイミング依存の 再現であることを証拠が示す場合に限り、feedback-loop-construction.md を 読んで、範囲を限定したループを構築します。テスト入力として再現に必要な要素を 最小化します。修正範囲は縮小せず、さらに上流を掘り下げ、正しい接点でテスト します。
3. 最近の変更を調べ、動作する例と比較します。コードは証拠です。権限、用語集、 コード、テストの内容が一致しない場合は、用語をひそかに再定義せず、 establishing-project-context を組み合わせます。
4. コンポーネント境界に計測を追加し、不正な値を発生源までたどります。 観測された不正な値が発生源から複数の呼び出しまたはコンポーネントを経由した 下流にある場合に限り、root-cause-tracing.md を読みます。 タスクの歪みについては、ソース → 理解 → 表現 → 実行 → 提供の順にたどり、 意味の変化が証拠によって最初に確認された箇所を特定します。これは乖離が観測 された箇所を特定するものであり、根本原因が証明されたことを意味しません。 現在の証拠を十分に再利用します。
5. 仮説を1つ立て、変数を1つだけ使った証拠で反証を試みます。推測に基づく修正を 重ねてはいけません。各ループの最後に Goal | DeeperCause | Evidence | Risk/Unknown | Decision を記録します。

正規の所有者とパッチ形状のゲート

編集する前に、候補が次のいずれかの兆候に当たる場合、ローカル箇所が正規の所有者 であることを証拠で確認できない限り、さらに上流を調べます。

• キーワード、フレーズ、正規表現、否定語リスト、またはサンプルテキストの例外
• ローカルのガード、追加の条件分岐、try／catch、早期リターン、または その場限りの分岐
• フォールバック、アダプター、互換性のための分岐、プロンプト分岐、または レガシーパスの拡張
• コンシューマー／呼び出し元／準備状態／表示レイヤーへのパッチ
• 型付きインテント、正規化された状態、コントラクト、または別の信頼できる情報源が あるにもかかわらず、下流のロジックが生テキストを再解析したり、アクション／ 状態を再推定したりすること
• プロデューサー／所有者の証拠を確認せずに行う、アーティファクト／ダウンロード／ エクスポート／読み戻し／キャッシュへのパッチ

PatchShape:
CanonicalOwner:
UpwardDrillSignal:
Decision: fix owner | continue investigation | escalate

ローカルテストが合格してもトリアージは不要になりません。名前を変更した キャリアは、新しい方向性ではありません。

修正によって既存のセマンティクス、責任、コントラクト、または関係性を再解釈 または廃止する可能性がある場合は、維持する動作、最もリスクの高い反例、重要な 不明点を明示します。既知の明示的なアンカーまたは上流／下流の参照について、 それぞれの役割と扱いを明示します。すなわち、維持する、正規の所有者に再割り当て する、理由を示して廃止する、または競合のために却下する、のいずれかです。 未解決の関係性は不明のままにし、下流で再推定してはいけません。値より先に役割を 確定し、証拠のあるキャリア機能ではなく、無効な責任を廃止します。この範囲を 限定した注意書きは、動作マトリックス、関係性グラフ、参照整合性の証明、または 網羅的な発見の主張ではありません。成果物、TDD リスクシグナル、回帰テストの 範囲を追加するものではありません。既存の TDD ルート所有者と設定済み／デフォルト モードは、引き続き適用されます。

診断が L3 をまたぐ場合、パッチ形状の兆候が現れた場合、ユーザーが根本原因の主張に 異議を唱えた場合、以前の修正後も症状が残る場合、複合的な根本原因のトポロジーが 考えられる場合、1つのインシデントに紐づく症状が2つ以上ある場合、発生ごとに再現 条件が異なる場合、または上流のプロデューサー／設定／デフォルト／コントラクト／ 仕様が除外されていない場合は、根本原因を主張する前に、 root-cause-claim-contract.md を読みます。Pre-Claim Gate、因果的閉包／反証の証明、 レイヤー上限の証明、Causal Topology Gate を単独で定めるのは、この文書だけです。

変更の必要性

この判断はプロンプトではなく、動作を契機とします。新しいソースコードのパスすべてに適用されます。そのパスの作成または重要なソース編集の前に、Change Necessity の判断（no-change | docs/config-only | code-change | needs-clarification）を明示してください。項目の詳細は advanced-debugging-governance.md にあります。

最小性とオーナーとの適合性

提案する分岐、フォールバック、アダプター、互換性パス、新しいオーナーについては、advanced-debugging-governance.md の項目を用いて Minimality Check を実施し、sufficient repair | local patch | needs first-principles review の判定を付けてください。妥当でない責任は廃止します。local patch には、保持する理由と廃止のトリガーが必要です。通常とは異なる新しい修復対象領域については、docs/current/AEGIS_MINIMALITY_REFERENCE.md の Existence Check を実施してください。廃止に古いコード、外部互換性、または永続状態のリスクが関わる場合は、 anti-entropy-governance を組み合わせてください。これは廃止経路を選択しますが、 破壊的操作の権限を与えるものではありません。

責任過多または複数の目的を持つオーナーを編集する前に、advanced-debugging-governance.md のテンプレートを用いて Pre-Edit Complexity Check と Pre-Edit Owner-Fit Decision を完了してください。

負荷の兆候については using-aegis/references/complexity-governance.md を使用してください。 既定では、既存箇所に new-responsibility を追加しないでください。より安全な境界によって承認済みの形が変わる場合は、まず計画／仕様を更新してください。

修復とリスクに応じた検証

スコープ内の成果に必要な、証拠によって裏付けられた原因を、それぞれの責任を担うオーナーで修復してください。独立した原因を無理に一つのオーナーへ集約したり、「ついでに」作業をまとめたりしないでください。厳格な TDD のもとでは、まず最小の失敗テストを作成してください。TDD が無効の場合、再現は診断上の証拠であり、本番コード編集の RED ゲートでも前提条件でもありません。

検証はリスクに応じて行ってください。

• 単一オーナー内のローカル修復：元の再現と、対象を絞った回帰テスト。
• 共有／契約／モジュール横断の修復：正規オーナー、影響を受けるコンシューマー、互換性の境界。
• フォールバック／オーナーの廃止：メイン経路、残存参照、否定ケース、境界の確認。
• タイミング／並行性の修復：ポーリング、スリープ、または競合タイミングが原因の一部であることを証拠が示す場合に限り、condition-based-waiting.md を読んでください。
• 複数の信頼境界を越える無効な状態：根本修復が判明し、独立した検証境界がもう一つ必要であることを証拠が示した後に限り、defense-in-depth.md を読んでください。

修復の失敗／継続／乖離、または3回の失敗があった場合は、別の修正を行う前に advanced-debugging-governance.md を読んでください。また、停止の判断が不明確／争点となる場合、Layer Stop Card／介入の場合、または複合根があり得る場合にも読んでください。クローズアウトのトリガー：修復によって追加されたパッチ形状、複数箇所／単一の回帰、残存するパターン／異常／重複／誤ったオーナー／下流の修復、同じ症状に対する未調査の修正、未解決の再発／裏付けのない根の状態、欠落した複合トポロジー固有のメンバー／偽装防止の証明、リポジトリ外の権限、移行されていない公開済み契約の破壊、未定義の仕様、権限／情報の不足。これらは H/T/D に振り分けます。詳細は因果関係の証明ではありません。

設定済みのワークスペースサポートを利用できる場合、重要なデバッグでは <aegis-workspace-helper> を使って対象プロジェクトの init、new-work、add-evidence、check を実行してください。コマンドの詳細は long-task-continuation に記載されています。

失敗した試行には <aegis-workspace-helper> add-attempt を使用してください。add-evidence は最後にのみ使用します。

迅速なバグ修正や手早いバグ修正を求められても、この手順は省略できません。Ripple Signal Triage が発動した場合は、編集前にその記録を残し、正規オーナーと影響を受ける下流経路を検証してください。記録は助言であり、完了を承認するものではありません。

クローズ

以下は必ず報告してください。

• 修復 — 原因、担当者、最小限の変更、互換性、検証。
• 廃止 — 責任の有効性、担い手／機能の処置、保持する理由／トリガー、削除の確認。

再現性、同一パターンへの対応、権限、複雑さ、廃止を確認してください。デバッグログにはプレフィックスを付け（例：[DEBUG-a4f2]）、クローズ前に 1 回の grep で削除を確認してください。確信度：A = 直接的な回帰の証拠、B = 不明点が限定された強い証拠、C = 部分的で未解決。

Trace Digest で監査証拠を要約してもかまいませんが、思考の連鎖を公開したり、根本原因、ルールの影響、検証の証拠の代わりにしたりしてはいけません。