justify

問題を解決する最もシンプルな変更が、 マージするうえで最も安全な変更です。 コードを追加するのは簡単です。コードの必要性をなくすのが エンジニアリングです。

正当化

追加バイアスの問題

AI モデルは役に立つように訓練されているため、 根本原因を修正するよりもコードを追加する方向へ 体系的に偏りが生じます。

AI のデフォルトの動作	正しい動作
回避策を追加する	根本原因を修正する
テストの期待値を変更する	実装を修正する
新しいヘルパーを作成する	既存のものを使う
エラー処理を追加する	エラーを防ぐ
互換性シムを追加する	古いコードを削除する
try/catch で囲む	例外の発生源を修正する

このスキルは、変更にこうしたパターンがないか監査し、 それぞれについて明示的な正当化を求めます。

使用するタイミング

• 実装作業を完了した後
• コミットまたは PR の作成前
• 自分の変更の品質を確認するとき
• scope-guard フラグが RED/YELLOW ゾーンを示しているとき

使用しないタイミング

• コードを書く前。この監査の対象はすでに完了した作業です（ imbue:karpathy-principles を使用してください）
• 機能がスコープに含まれるかを判断するとき（imbue:scope-guard を使用してください）

監査プロトコル

ステップ 1：差分を収集する

# Determine base branch
base=$(git merge-base master HEAD 2>/dev/null \
  || git merge-base main HEAD 2>/dev/null)

# Get change statistics
git diff "$base" --stat
git diff "$base" --shortstat
git diff "$base" --diff-filter=A --name-only  # new files
git diff "$base" --diff-filter=M --name-only  # modified files
git diff "$base" --diff-filter=D --name-only  # deleted files

ステップ 2：追加バイアススコアを算出する

各項目を 0～3 で評価します（0 = 問題なし、3 = バイアスが強い）。

指標	重み	測定方法
行数比	2x	additions / max(deletions, 1)
新規ファイル	2x	--diff-filter=A の件数
テストロジックの変更	3x	テストのアサーション／期待値の差分
新しい抽象化	1x	新しいクラス、関数、モジュール
回避策のパターン	2x	追加された Try/catch、if/else のガード

行数比のスコア：

比率	スコア	解釈
< 2:1	0	バランスの取れた変更
2:1 to 5:1	1	追加の傾向がややある
5:1 to 10:1	2	追加バイアスの可能性が高い
> 10:1	3	追加バイアスが強い

合計スコア：

bias_score = sum(signal_score * weight) / sum(weights)

合計	ゾーン	対応
0.0 - 0.5	GREEN	続行する
0.5 - 1.5	YELLOW	各指標を正当化する
1.5 - 2.5	RED	アプローチを再考する
2.5+	STOP	アプローチが誤っている可能性が高い

ステップ 3：鉄則への準拠を確認する

鉄則とは、テストが実装を導くのであって、 その逆ではないということです。違反がないか確認します。

# Find test files that were modified
git diff "$base" --name-only | rg "test_|_test\.|spec\." \
  || git diff "$base" --name-only | grep -E "test_|_test\.|spec\."

# For each modified test file, check what changed
git diff "$base" -- <test_file> | rg "^[-+].*assert|^[-+].*expect|^[-+].*should"

違反パターン（テストロジックが改変されている）：

• アサーション値が変更されている（期待される出力が変更されている）
• テストケースが削除またはコメントアウトされている
• @skip または @pytest.mark.skip が追加されている
• エラーの期待値が弱められている（広範な例外型）
• 新しい動作に合わせてモックの戻り値が変更されている
• 元の動作を表さなくなるようにテスト名が変更されている

違反ごとに明示的な正当化が必要です：

「このテストのアサーションを変更したのは、 実装が元の要件を満たせなかったからではなく、 要件が変わったからです。」

要件が変わっていないなら、テストを変更してはいけません。 代わりに実装を修正してください。

ステップ 4：最小限の介入を分析する

変更したファイルごとに、次の質問に答えます。

1. この変更は必要でしたか？ このファイルに手を加えずに目標を達成できませんでしたか？

2. これが最小限の変更でしたか？ 同じ結果を、より少ない行数で実現できませんでしたか？

3. この変更は複雑さを増やしましたか、それとも減らしましたか？ 新しい関数、クラス、制御フローは複雑さの追加にあたり、 正当化が必要です。

4. 削除を優先する代替案はありますか？ コードを追加するのではなく、削除することで問題を 解決できませんでしたか？

ステップ 4.5：不変条件への影響分析

変更が最小限でも、基盤となる設計上の決定を ひそかに変更してしまうと、致命的な誤りに なり得ます。変更したファイルごとに、設計上の 不変条件に触れていないか確認してください。

不変条件に該当するもの：

• アーキテクチャパターン（モジュールの境界、レイヤーの 分離、データフローの方向）
• データ構造の選択（リストではなくマップを使う理由、 正規化ではなく非正規化にする理由）
• API コントラクト（公開インターフェース、プロトコル形式）
• エラー処理の方針（即時終了と復旧のどちらを選ぶか）
• 並行処理モデル（シングルスレッドを前提とするか、 アクターモデル、共有なし）

検出のヒューリスティック：

# Check for structural changes (new modules, moved
# boundaries, changed interfaces)
git diff "$base" --name-only | rg "(interface|abstract|base|core|types|schema|model)" \
  || git diff "$base" --name-only | grep -E "(interface|abstract|base|core|types|schema|model)"

# Check for pattern-breaking changes
git diff "$base" -U5 | rg "(TODO.*refactor|HACK|WORKAROUND|XXX)" \
  || git diff "$base" -U5 | grep -E "(TODO.*refactor|HACK|WORKAROUND|XXX)"

不変条件との衝突が検出された場合：

解決策をひそかに選んではいけません。人間に 次の 3 つの選択肢を提示してください。

選択肢	説明	適切な場合
維持する	機能を追加しない。不変条件が多くの利点をもたらす	不変条件によって多くのことが単純化され、機能の重要性が低い
重ねる	洗練されていなくても、その上に機能を追加する	機能が必要で、不変条件にも価値があり、不完全さを許容できる
改訂する	不変条件そのものを変更する	新たな知見によって当初の決定が無効になった

正当化レポートに追加する内容：

### Invariant Impact: NONE / DETECTED

[If DETECTED:]
- **Invariant**: [name the design decision]
- **Conflict**: [what change clashes with it]
- **Option chosen**: Preserve / Layer / Revise
- **Justification**: [why this option, not the others]
- **Human reviewed**: YES / NO — if NO, flag as
  requiring review before merge

リスク増大への警告： 不適切な不変条件の決定は 積み重なります。このブランチで複数の不変条件を 改訂している場合は、ブランチ全体をアーキテクチャ レビューの対象として提示してください。不変条件を ひそかに変更するたびに、救済不能なコードベースに なる確率が高まります。

ステップ 5：正当化レポートを生成する

次の構成でレポートを出力します。

## Justification Report

**Branch**: feature/xyz
**Base**: master
**Delta**: +N/-M lines, X files changed

### Additive Bias Score: X.X (ZONE)

| Signal | Score | Detail |
|--------|-------|--------|
| Line ratio | N | +A/-D = R:1 |
| New files | N | [list] |
| Test changes | N | [list] |
| New abstractions | N | [list] |
| Workarounds | N | [list] |

### Iron Law Compliance: PASS/FAIL

[List any test logic modifications with justification]

### Change-by-Change Justification

#### file.py (+N/-M)
- **What**: [description]
- **Why**: [root cause this addresses]
- **Alternatives considered**: [what else could work]
- **Why this is minimal**: [why fewer changes won't work]

#### test_file.py (+N/-M)
- **What**: [description]
- **Justification**: [why test logic changed, if it did]
- **Iron Law status**: PASS/VIOLATION

### Risk Assessment

| Factor | Rating |
|--------|--------|
| Lines changed | LOW/MED/HIGH |
| Files touched | LOW/MED/HIGH |
| Test modifications | NONE/JUSTIFIED/VIOLATION |
| New abstractions | NONE/JUSTIFIED/UNNECESSARY |
| Overall merge risk | LOW/MED/HIGH |

### Recommendations

[List any changes that should be reconsidered,
simpler alternatives, or unnecessary additions]

判断の重み付け

複数のアプローチを評価するときは、次の要素を 重視してください。

要素	重み	根拠
変更行数が少ない	HIGH	リスクが低く、レビューしやすい
新しいファイルがない	HIGH	新たな保守負担が生じない
テストロジックを変更しない	HIGH	鉄則を順守できる
根本原因を修正する	HIGH	再発を防げる
コードを削除する	BONUS	保守対象を減らせる
抽象化を追加する	PENALTY	3 回目の使用時にのみ正当化される
エラー処理を追加する	NEUTRAL	システム境界でのみ追加する

差し引きテスト：変更を受け入れる前に、 「コードを 追加 する代わりに 削除 して、 これを実現できないか」と確認してください。可能であれば、 差し引くアプローチを優先してください。

作業証明との統合

Justify は変更レベルの説明責任によって、 作業証明を拡張します。

• proof-of-work：「動作したか？」（証拠）
• justify：「この方法は適切だったか？」（理由付け）

作業の完了を宣言する前に、両方が必要です。 まず proof-of-work を実行し、その後 justify を実行してください。

指摘すべきアンチパターン

1. テストの改変

壊れたコードに合わせてテストの期待値を変更すること。 修正：テストの変更を元に戻し、実装を修正してください。

2. ショットガン追加

単一の懸念に対する修正のために、多数のファイルへ コードを追加すること。 修正：変更箇所を 1 か所に絞ってください。

3. 防御的な過剰設計

実際には起こり得ない状況に対して、try/catch、 null チェック、検証を追加すること。 修正：内部コードを信頼してください。境界でのみ検証してください。

4. 時期尚早な抽象化

1 つのユースケースのために、ヘルパー、ユーティリティ、 基底クラスを作成すること。 修正：コードをインライン化してください。3 回目の使用時に抽象化してください。

5. 互換性シム

呼び出し元を更新する代わりに、後方互換性のための コードを追加すること。 修正：呼び出し元を直接更新してください。使われなくなった経路は削除してください。

6. 不変条件のひそかな改訂

設計上の不変条件を改訂していることを明示せずに、 アーキテクチャパターン、データ構造の選択、または API コントラクトを変更すること。 修正：不変条件を明示してください。3 つの選択肢 （維持する、重ねる、改訂する）を人間に提示してください。 判断を自分だけで下してはいけません。モデルは学習データの 「平均」に偏り、不適切な不変条件の決定は積み重なり、 救済不能なコードベースにつながります。

精査のための質問（leyline:additive-bias-defense より）

変更を正当化する前に、以下の質問を適用してください。 質問 4 と 5 への回答が具体的な 証拠でない場合、その変更は正当化されません。

1. 優先事項との整合性：現在の優先事項から 外れていますか？
2. 重要性：この時点で実装することが重要ですか？
3. シンプルさ：よりシンプルで洗練された 解決策はありますか？
4. 証拠：これが必要であることを示す証拠は何ですか （単なる想定ではなく）？
5. 結果：これを追加しない場合、何が壊れますか？

証明責任の転換

初期姿勢は、この追加は存在すべきではないです。変更の必要性を証明するのは変更側であり、査読者が不要であることを証明するのではありません。

正当化レポート（ステップ 5）を作成する際、Burden of Proof セクションを追加してください。

変更	精査の質問 4 への回答	精査の質問 5 への回答	判定
file.py	[証拠]	[結果]	justified/needs_evidence/unjustified

判定が unjustified の変更は、レポートが合格する前に必ず削除するか、やり直す必要があります。

トレードオフを記録する（判断ジャーナル）

このステップで現実的な選択肢を伴う判断が確定した場合、理由が明確なうちに（ドラフトを作成して確認したうえで）docs/tradeoffs.md に記録してください。

• leyline がインストールされている場合は、Skill(leyline:decision-journal) を呼び出してトレードオフの項目（判断、検討した選択肢、断念したこと）を追記し、phase を review に設定します。ドラフトを提示し、確認後に追記してください。
• フォールバック（leyline がない場合）：ファイル内の ENTRY TEMPLATE を使って docs/tradeoffs.md に追記し、次の TR-NNN ID を割り当ててください。

賢明な助言

今行っていることは、優先事項から外れていませんか？ この時点で実装することが重要ですか？ AI や最初に思いついた考えに頼りすぎないでください。 さらに良くなるよう自分自身に問いかけ、より洗練された実装や よりシンプルな解決策を考えてください。

終了条件

• 加算的バイアススコアが計算され、そのゾーン（GREEN/YELLOW/RED/STOP）が報告されている。
• 鉄則への準拠が PASS または FAIL として示され、テストロジックを変更した場合はその理由が説明されている。
• すべての変更に判定（justified、needs_evidence、unjustified）が付いている。最終レポートに unjustified の判定が残っていない。
• 不変条件との競合が検出された場合、選択した選択肢と人間によるレビューのフラグが明示されている。
• 正当化された重要な追加が、レポートの合格前に docs/tradeoffs.md（またはファイル内のテンプレート）に記録されている。

関連スキル

• imbue:karpathy-principles — 「Surgical Changes」と 「Goal-Driven Execution」の原則は、より高次の統合から この監査を呼び出します。
• leyline:additive-bias-defense — この監査が詳細に適用する 契約です。
• imbue:proof-of-work — この監査を補完する検証レイヤーです （proof-of-work が「動作したか」を問うのに対し、 justify は「存在する必要があったか」を問います）。
• ゲートスキルの連携グラフ全体については、 docs/quality-gates.md#skill-level-quality-gate-composition を参照してください。