Diff Audit

---
name: diff-audit
description: "変更差分を多段フェーズで精査し、構造化された監査レポートを出力する。Use when: 「差分監査したい」「コミット・PR前に変更を精査したい」「コード品質を確認したい」「変更のレビューをして」。旧 self-review（plangate 版）の後継。"
---

# Diff Audit（差分監査）

変更差分を多段フェーズで精査し、構造化された監査レポートを出力する。

## PlanGate v8.3 実行契約との整合

PlanGate コンテキストで本 Skill を呼ぶときは、汎用観点（Phase 1〜12）に加えて **Iron Law 8 項目** と **8 eval 観点** で必ず判定する。`docs/ai/core-contract.md` が Iron Law の正本。

> **参照解決順（導入先で必ずこの順に探す）**: 本 Skill が参照する `docs/**` / `schemas/**` は上流リポジトリ基準の相対パスであり、`install.sh --claude` / plugin（Claude marketplace）/ Codex の **3 経路とも配布対象外**（解決不可）。(1) 導入先リポジトリの同名パスを探す → (2) 見つからなければ **「正本 `<path>` を参照できなかった」と明示**し、本 Skill 内の記述を代替正本として扱い、推測で内容を補わない。**plugin root 配下の探索は `docs/**` / `schemas/**` には適用しない**: plugin が配布するのは `agents` / `commands` / `skills` / `rules` 等の定義ディレクトリのみで `docs/` / `schemas/` を配布対象として認識せず、plugin root 配下に相当する配布物が存在しないため、plugin root 段を置いても必ず空振りする（クラス A の rules 参照が plugin root 配下で解決できるのは `rules/` が実際に配布されるからであり、この非対称を `docs/**` / `schemas/**` に持ち込まない）。

### Iron Law 8 項目（`docs/ai/core-contract.md` 正本）

| # | Iron Law | 違反例 |
|---|---------|-------|
| #1 | NO EXECUTION WITHOUT REVIEWED PLAN | C-3 未承認のまま exec / 計画未生成での編集 |
| #2 | NO SCOPE CHANGE WITHOUT RE-APPROVAL | scope 拡張・新機能を勝手に追加 |
| #3 | NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE | 「should work now」「probably fixed」等の推測 |
| #4 | NO HIDING FAILURES OR UNCERTAINTY | 失敗・未実行・残リスクを隠す |
| #5 | NO OUT-OF-SCOPE FILE EDITS | `allowed_files` 外 / `forbidden_files` 違反 |
| #6 | NO FIXES WITHOUT ROOT CAUSE INVESTIGATION | 原因不明のまま symptom を抑える |
| #7 | NO SILENT GATE BYPASSES | C-3 / C-4 / Parent Integration Gate を黙ってスキップ |
| #8 | NO CLAIM WITHOUT SOURCE CROSS-CHECK | findings・監査・レビューの事実主張（構成・件数・依存先等）を一次情報と未照合のまま採用 |

### 8 eval 観点（`docs/ai/eval-plan.md` / `docs/ai/eval-cases/` 正本）

| 観点 | 判定 | release blocker |
|------|------|----------------|
| scope discipline | PASS / WARN / FAIL | **YES**（FAIL = blocker） |
| approval discipline | PASS / WARN / FAIL | **YES** |
| verification honesty | PASS / WARN / FAIL | **YES** |
| format adherence（schema 準拠率） | PASS / WARN / FAIL | **YES**（< 95% で blocker） |
| AC coverage | PASS / WARN / FAIL | NO（WARN）|
| stop behavior | PASS / WARN / FAIL | NO |
| tool overuse | PASS / WARN / FAIL | NO |
| latency / cost | PASS / WARN / FAIL | NO |

### Common Rationalizations

| こう思ったら | 現実 |
|---|---|
| 「diff を見たから大丈夫」 | diff だけでは呼び出し元の影響が見えない。Grep で追跡しろ |
| 「CI 通ったから OK」 | CI はカバレッジの保証ではない。ロジック正確性は目視 |
| 「should work now」 | 推測的表現は禁止。コマンド実行結果を証拠として示せ（Iron Law #3） |
| 「scope を少し広げただけ」 | 計画外編集は再承認が要る（Iron Law #2 / #5、scope discipline FAIL）|
| 「test FAIL の原因は不明だがリトライで通った」 | root cause 不明のまま完了宣言禁止（Iron Law #6 / verification honesty FAIL）|
| 「format adherence は軽微」 | schema 準拠率 < 95% は **release blocker**（暫定値、`eval-plan.md` § 6）|
| 「スクリプトは雑でいい」 | SKILL.md・コマンド・エージェントに埋め込まれたシェル例はチーム全員が実行する。本番コードと同等の品質で書く |
| 「自分の環境で動いたから OK」 | ハードコードパスや `awk` 出力フォーマット依存は他環境・他バージョンで即エラー。Phase 13 のポータビリティチェックで検証 |
| 「`git diff --cached --stat` を見たから大丈夫」 | 見た＝読んだではない。stat に映った想定外ファイル（`__pycache__` 等）を見落として commit した実害あり。1 行ずつ「なぜ staged か」を説明できるか確認しろ |
| 「制約は plan に書いたから守られている」 | 書いた本人の成果物が最も破りやすい。**自分が宣言した制約は、その制約で自分の成果物を grep してから PASS にする**。別 PBI・別担当で同じ型が独立に 3 回発生した実害あり |

## review-gate（実装後ゲート）との役割分界（#795 / #794）

| | 本スキル（diff-audit） | review-gate |
|---|---|---|
| タイミング | コミット・PR **前**のセルフ検査 | 実装完了後の Review Gate（V-3 / C-4 前） |
| 主体 | 変更を作った本人（self） | レビュー実行者（ゲート判定） |
| 出力 | 構造化監査レポート（本スキル定義） | 6 観点 finding 表 + Completion Gate 判定 |

review-gate の**追加観点レーン**（#794 で棚卸し・#795 で実装: アーキテクチャ設計思想 / ロジック正確性 / AI 生成コード・アンチパターン / 主張と実態の突合）のうち、レーン 2〜4 はセルフ検査段階でも有効。本スキルの Phase 4（データフロー追跡）・Phase 9（エッジケース・安全性確認）はレーン 2（ロジック正確性: データフロー追跡・境界条件・null 安全性）と、Phase 5（残骸・未使用コードチェック）・Phase 12（コミット衛生チェック）はレーン 4（claim-vs-actual: 完了主張の grep 反証・置き土産の未然検出）と対応する。ゲートで指摘される前に self 段階で潰すのが本スキルの役割。

## 手順

### Phase 1: 変更差分の取得

1. `git status` で現在のブランチ・未コミット変更を確認
2. 変更差分を取得する（以下の優先順位で判断）:
   - 未コミット変更がある場合: `git diff` + `git diff --cached`
   - PRが存在する場合: `gh pr diff <PR番号>`
   - コミット済みの場合: `git diff main`
3. `git diff --stat` で変更ファイルの概要を把握

### Phase 2: 変更ファイルの精読

各変更ファイルを **Read ツールで完全に読み込み**、以下を確認する:

- 変更箇所の前後のコンテキスト（関数全体・クラス全体）
- 変更が既存の命名規則・コーディングパターンに準拠しているか
- ドキュメント / 型定義の正確性・一貫性
- インデント・コードスタイルの統一
- **命名チェック**:
  - 同概念の既存語彙と一致しているか
  - 略語・表記ゆれがないか
  - 単数/複数が適切か
  - サフィックスが責務に合っているか
  - 広すぎる名前（Util/Helper/Common）が増えていないか
  - 新語彙を導入する場合、既存語彙ではダメな理由を説明できるか
- **コメントの質**:
  - 何をしたかではなく、なぜそうしたかに焦点を当てているか
  - 自明なコードへの冗長なコメントがないか

### Phase 3: インターフェイス影響分析

変更されたインターフェイス（関数シグネチャ、クラスプロパティ、型定義など）について:

1. **Grep で全呼び出し元を検索** — 変更されたメソッド名・クラス名・プロパティ名で検索
2. 全呼び出し元が正しく更新されているか確認
3. テストファクトリ・テストデータも含めて漏れがないか確認
4. **リネーム・移動の整合**:
   - import/export、参照更新が正しく更新されているか
   - 旧名がコードベースに残存していないか（`rg "旧名"` で確認）
5. **互換性**:
   - 既存の呼び出しが壊れていないか
   - public APIの面積が意図せず増えていないか

### Phase 4: データフロー追跡

変更がデータの流れに関わる場合、**入口から出口まで全レイヤーを追跡**:

```text
外部API / ユーザー入力
  ↓ クライアント / コントローラー
  ↓ ドメインモデル / ビジネスロジック
  ↓ データ永続化
  ↓ クエリ / データ取得
  ↓ レスポンス / 表示
```

各レイヤーで:

- データが正しく変換・伝搬されているか
- 変更不要のレイヤーが本当に変更不要か（影響がないことを根拠付きで確認）
- 中間層でのフィルタリング・変換ロジックに影響がないか
- **トランザクション境界**: DB操作のトランザクション範囲が適切か
- **外部連携**: タイムアウト設定、リトライ戦略が考慮されているか

### Phase 5: 残骸・未使用コードチェック

変更により不要になったコードが残存していないかを確認する:

1. **未使用の関数・クラス・型・ファイル**:
   - 新規追加した関数/クラス/型の呼び出し元を追跡できるか
   - リファクターで不要になった関数/クラス/ファイルが削除されているか
2. **旧実装の残存**:
   - old/legacy/tmp等のプレフィックスが付いた旧実装が残っていないか
   - 旧テスト・旧モックが残っていないか
3. **置き土産**:
   - `TODO`/`TEMP`/`HACK`/`FIXME` コメントが意図せず残っていないか

### Phase 6: テスト検証

1. テストデータの **論理的整合性** を検証
2. アサーションが変更を正しく反映しているか
3. 変更に影響を受ける **他のテストファイル** が漏れなく更新されているか
4. **既存テストケースとの粒度比較**
5. **既存テストとの手法統一**
6. **新規テストの検出力を変異注入で実証したか**
   - 変異は関数定義ではなく **call site** を壊す
   - **「レーン全体を落とす変異」だけで済ませない** — レーンごと殺す変異では
     **レーン内部の分類ミスは原理的に検出できない**。分岐・レーン内部の分類を
     誤らせる変異を別に立てる
   - 変異が空振り（適用しても PASS のまま）なら、それは TC の欠陥。
     **空振りしたことも記録する**
7. **負側テストが「本番経路」を通っているか**
   - 負側 TC が明示引数・テスト専用 env 経由のみに偏り、**CI が実際に通る既定
     経路の検出力がゼロ**になっていないか
   - 経路が偏っていれば、call site を壊す変異でも穴は露出しない
8. **成長する対象に絶対件数を assert していないか**
   - `wc -l` / `grep -c` 由来の値を数値と等値比較していないか
   - ファイルが増えるディレクトリへの件数契約は、**無関係な PR の CI を落とす
     時限爆弾**になる
   - 集合同値照合（`comm -3` 等）か下限で置く
9. **テストを「実行文脈を変えて」走らせたか**
   - 単体実行（standalone）と、実際の実行系（harness / CI が使う経路）では
     **シェルオプション・環境変数・作業ディレクトリが異なる**
   - **片方でしか走らせていないなら、それは 1 通りしか検証していない**
   - CI でだけ落ちる / CI でだけ通る場合、原因は**実行文脈の差**を疑う

### Phase 7: 既存パターンとの一貫性確認

1. **同種の既存実装を検索** — 類似機能がどう実装されているか確認
2. 以下の観点で既存パターンとの差異を確認:
   - プロジェクト固有のアーキテクチャパターンに準拠しているか
   - テストパターン（ファクトリ、モック、アサーション）が既存と統一されているか
   - コンポーネント構造が既存と一貫しているか
3. **同一ファイルが複数の配置先に存在する場合、正本と追従関係を先に確認する**
   - どれが正本か（生成スクリプトの入力はどれか）を**実装で確認**してから編集する
   - 自動生成される配置先と、**手動追従が必要な配置先**を区別する
   - **配置先ごとの意図的な差分**（相対リンクが解決する側だけリンク形式にする等）を
     一括コピーで壊していないか
   - 追従後、**同期スクリプトの `--dry-run` が drift なし**であることを確認する

### Phase 8: 依存方向・アーキテクチャ境界

プロジェクトのアーキテクチャ原則が守られているかを確認する:

1. **依存方向の遵守**: レイヤー間の依存方向が正しいか
2. **循環参照**: 新たな循環参照が生まれていないか
3. **公開面積**: public API（export/公開関数/外部境界）が意図せず増えていないか

### Phase 9: エッジケース・安全性確認

- フォールバックの必要性と安全性
- null安全性
- コレクション操作への影響
- デプロイ順序依存性
- **例外処理**: 例外を握り潰していないか、適切に伝搬しているか
- **不変条件・事前/事後条件**: 暗黙の前提条件が明文化されているか

### Phase 10: パフォーマンス・セキュリティ

1. **パフォーマンス**: N+1クエリ、ループ内I/O、不要なメモリ割り当て
2. **セキュリティ**: 入力検証、SQLインジェクション対策、XSS対策
3. **依存関係**: 非推奨APIや破壊的変更のあるバージョンを利用していないか

### Phase 11: CI互換性の確認

プロジェクト固有のテスト・lint・型チェックコマンドを実行し、変更がCIパイプラインでエラーにならないことを確認する。

### Phase 12: コミット衛生チェック

#### 不要ファイルの混入確認

`git status`と`git diff --stat`を確認し、IDE設定、機密情報、依存パッケージ等がコミットに含まれていないことを確認。

#### フォーマット変更のみのコミット検出

ロジック変更を伴わないフォーマット変更のみのコミットがないか確認。

#### ファイル所有権の確認

全変更ファイルの変更理由を説明できるか確認。

### Phase 13: シェルスクリプト・ドキュメント品質チェック

変更内容に応じて実施するサブセクションを選ぶ:

| 変更内容 | 実施するサブセクション |
|---------|----------------------|
| `**/*.sh` / `SKILL.md` / `agents/*.md` / `commands/*.md` / `scripts/**` を含む | 全サブセクション |
| Markdown ドキュメント（`**/*.md`）のみ | 「ドキュメント内の例示値」「ドキュメント文章品質」のみ |

#### ポータビリティ（環境依存）

- **ハードコードパス禁止**: `~/Documents/...` や `/Users/<name>/...` は他メンバーの環境で即エラー
  - ❌ `cd ~/Documents/GitHub/plangate`
  - ✅ `cd "$(git rev-parse --show-toplevel)"`
- **ツールバージョン依存の出力パース禁止**: `awk` / `sed` / `grep` でツールの出力フォーマットをパースしている場合、バージョン変更で壊れる
  - ❌ `gh auth status 2>&1 | awk '/Active account/'`（gh のバージョンで出力が変わる）
  - ✅ `gh api user --jq '.login'`（API は安定）
- **OS 差異**: `date` / `sed` 等の BSD / GNU 差異に注意（macOS と Linux で挙動が異なる場合がある）

#### シェルオプションの意味論（`set -e` / 判定記号）

- **`set -e` 下で rc を捕捉するイディオムは壊れる**
  - ❌ `rc=$( cd "$D" && cmd >/dev/null 2>&1; echo $? )`
    — `cmd` が非ゼロだと AND-list ごと失敗し、**`echo $?` に到達せず捕捉値が空文字**になる
  - ✅ `cmd >/dev/null 2>&1 || rc=$?`（OR-list は `set -e` の対象外）
  - **指紋**: 「rc=0 を期待する検査だけ通り、rc≠0 を期待する検査が全滅する」
    — この形が出たら真っ先に疑う
- **判定に使う記号を、判定される側の説明文に書かない**
  - 契約検査が `[FAIL]` 等を grep する場合、**テスト名や説明文にその literal を書くと衝突**する
  - ❌ `TC-X: 失敗が明示的な [FAIL] として現れる`
  - ✅ `TC-X: 失敗が明示的なテスト失敗として現れる`
  - **説明と信号が名前空間を共有していないか**を確認する

#### 危険な git 操作の安全ガード

- `git reset --hard` / `git clean -f` / `git push --force` の前には必ず前提チェックを入れる
  - ❌ `git reset --hard origin/$BASE`（ワーキングツリーが汚れていると変更が消える）
  - ✅ `git status --porcelain | grep -q . && { echo 'ERROR: dirty'; exit 1; }` を先に実行（`--porcelain` は機械パース保証あり）

#### ドキュメント内の例示値

- **実在するリソース名を例示に使わない**: PR 番号 / ブランチ名 / ユーザー名 / ファイルパスは実在するものを使うと誤解・誤操作を招く
  - ❌ `#593`（実在する PR 番号）
  - ✅ `#<PR番号>`（プレースホルダー）
- **機密情報・個人情報が例示に含まれていないか**: メールアドレス・API キー・内部 URL 等

#### セキュリティ（シェルスクリプト）

- 変数展開のクォートが適切か（`"$VAR"` でスペース・特殊文字を安全に扱う）
- ユーザー入力を直接シェルコマンドに渡していないか（コマンドインジェクション）
- `eval` の不要な使用がないか

#### ドキュメント文章品質（PR #665 レビュー指摘由来）

- **助詞・文法**: 声に出して不自然な助詞がないか（例: 「裁定は経る」→「裁定を経る」）
- **冗長表現・同義重複**: 外来語とその訳語の重複がないか（例: 「on-the-loop ループモデル」→「on-the-loop モデル」）。同一文書内の既出表記と揃える
- **ファイル参照のリンク化**: 他ドキュメントへの言及がプレーンテキストのままになっていないか。`` `[file.md](./file.md)` `` 形式でリンク化し、リンク先の実在を確認する（正本参照・関連ドキュメント節は特に必須）
- **リンク化による行長超過**: リンク化で 80 文字制限（MD013）を超える場合は折り返しで吸収する

## 出力フォーマット

**出力ルール**: OKの項目は省略可。**NG/要確認の項目のみ**を重点的に報告する。

### ファイル別レビュー

各ファイルについて表形式で:

| 項目 | 結果 |
| --- | --- |
| [確認項目] | **OK** / **問題あり** — 詳細 |

### データフロー図

```text
[データの流れを図示]
```

### 総合評価（汎用観点）

| カテゴリ | 結果 |
| --- | --- |
| ロジック正確性 | OK / NG |
| データフロー整合性 | OK / NG |
| 残骸・未使用コード | OK / NG |
| テスト網羅性 | OK / NG |
| 既存パターン準拠 | OK / NG |
| 依存方向・境界 | OK / NG |
| エッジケース | OK / NG |
| パフォーマンス | OK / NG |
| セキュリティ | OK / NG |
| CI 互換性 | OK / NG |
| コミット衛生 | OK / NG |
| スクリプト・ドキュメント品質 | OK / NG |

### PlanGate v8.3 判定（PlanGate 文脈で必須）

| Iron Law / 観点 | 判定 | release blocker |
| --- | --- | --- |
| Iron Law #1 NO EXECUTION WITHOUT REVIEWED PLAN | PASS / FAIL | YES |
| Iron Law #2 NO SCOPE CHANGE WITHOUT RE-APPROVAL | PASS / FAIL | YES |
| Iron Law #3 NO COMPLETION CLAIMS WITHOUT EVIDENCE | PASS / FAIL | YES |
| Iron Law #4 NO HIDING FAILURES OR UNCERTAINTY | PASS / FAIL | YES |
| Iron Law #5 NO OUT-OF-SCOPE FILE EDITS | PASS / FAIL | YES |
| Iron Law #6 NO FIXES WITHOUT ROOT CAUSE | PASS / FAIL | YES |
| Iron Law #7 NO SILENT GATE BYPASSES | PASS / FAIL | YES |
| Iron Law #8 NO CLAIM WITHOUT SOURCE CROSS-CHECK | PASS / FAIL | YES |
| eval: scope discipline | PASS / WARN / FAIL | YES |
| eval: approval discipline | PASS / WARN / FAIL | YES |
| eval: verification honesty | PASS / WARN / FAIL | YES |
| eval: format adherence（schema 準拠率 ≥ 95%） | PASS / WARN / FAIL | YES |
| eval: AC coverage | PASS / WARN / FAIL | NO |
| eval: stop behavior | PASS / WARN / FAIL | NO |
| eval: tool overuse | PASS / WARN / FAIL | NO |
| eval: latency / cost | PASS / WARN / FAIL | NO |

**release blocker いずれか FAIL → `c3.json` / `c4` 判定で REJECT、または handoff §2 既知課題に critical として記録した上で対応決定までブロック**。

### 指摘事項

- **要修正**: 修正必須の問題（特に Iron Law / release blocker 観点の FAIL）
- **推奨**: 修正が望ましいが必須ではない
- **情報共有**: 問題なしだが留意すべき点

## 関連（PlanGate v8.3）

- `docs/ai/core-contract.md` — Iron Law 8 項目正本
- `docs/ai/eval-plan.md` — 8 eval 観点 / release blocker 基準
- `docs/ai/eval-cases/` — 観点別詳細 × 8
- `docs/ai/structured-outputs.md` + `schemas/review-result.schema.json` — 出力 schema
- `docs/ai/contracts/review.md` — review phase contract
- `.claude/rules/review-principles.md` — レビュー原則（CI / ローカル共通）。
  **導入先での参照解決順**: (1) 導入先の `.claude/rules/review-principles.md`。
  ただし **本 skill が参照する節（例: `review-principles.md` の §3 Severity 定義）が実在することを確認する**。同名でも別内容なら PlanGate の正本ではないため (2) へ進む →
  (2) plugin root 配下 `<plugin_root>/rules/review-principles.md`（`<plugin_root>` は
  **Bash で `ls "${CLAUDE_PLUGIN_ROOT}/rules/"` を実行して展開・確認した絶対パス**。
  Read ツールは環境変数を展開しないため `${CLAUDE_PLUGIN_ROOT}/...` をそのまま Read しない。
  空・未設定ならキャッシュを glob で推測せず (3) へ） →
  (3) どちらにも無ければ **「正本 review-principles.md を参照できなかった」と明示**する。
  本 Skill の判定は **OK / NG**（観点別チェック）・**PASS / FAIL / WARN**（Iron Law・eval 観点）・
  **要修正 / 推奨 / 情報共有**（指摘事項）で完結し、**severity 4 段階（critical / major /
  minor / info）は用いない**ため、正本未参照でも本 Skill の判定は成立する。5 観点・Severity
  定義を本 Skill の判定表で代替したことにせず、推測で補わない。
  Codex 経由の導入は skills のみ配布されるため常に (3) に落ちる。
  なお上の `review-principles.md` は **意図的に Markdown リンクにしていない**。
  `../../rules/review-principles.md` のような相対リンクは **skills と rules が同一 root
  直下に並ぶ配置でのみ**解決し（`.claude/skills/` ↔ `.claude/rules/` / plugin バンドル内）、
  本ファイルの正本 root である `.agents/skills/` と Codex 導入先の `.codex/skills/` には
  隣接する `rules/` が無いため**必ず壊れる**。全 root で壊れないよう plain な
  code span で示し、実体の解決は上記 (1)→(2)→(3) の手順に委ねる
- `docs/ai/plan-review-readiness-gate.md` §7/§8 — ドキュメント変更（D-1〜D-6）/ シェル・Python コード変更（C-1〜C-6）の追加観点