problem-solving

name	problem-solving
description	データ不整合・バグ・障害の問題解決ガイドライン。根本原因分析の手順、上流修正優先の原則、ハルシネーション防止チェック、データとコードの整合性検証、多層防御の考え方を扱う。
when_to_use	データ不整合 / バグ / 障害対応時に自動参照。「つじつま合わせ」を避けて上流で直す判断が必要なとき。Triggers: 'バグ修正', 'データ不整合', '障害対応', '根本原因', 'root cause analysis', 'data inconsistency', 'incident', '上流で直す', 'patch vs fix'

問題解決ガイドライン

データ不整合、バグ、障害対応における問題解決の原則と手順。

1. 根本原因を探る（つじつま合わせをしない）

原則: 上流で直す

問題はデータフローの最も上流で修正する。下流でのパッチ（migrationによるデータ修正、SQL直接更新、出力時の辻褄合わせ）は最終手段。

❌ 悪いパターン
  DBに異常データがある → migrationで論理削除 → バッチ再実行

✅ 良いパターン
  DBに異常データがある → なぜ入ったか調査 → 取り込みロジックにバリデーション追加
  → 異常データを論理削除 → バッチ再実行

判断フロー

1. 症状を確認（どのデータ・どの機能が、どう間違っているか）
2. データフロー/呼び出しチェーンを遡る（結果 → 計算 → 素材 → 取り込み → 外部ソース）
3. 最初に異常が発生した地点を特定
4. その地点のコードを修正
5. 下流にも防御的チェックを追加（多層防御）
6. 修正後にデータ修復（パイプライン再実行）

典型的な見逃しパターン

症状	表層の「原因」	真の根本原因
料金が異常値	計算ロジックのバグ	上流の取り込み時に異常値が混入、バリデーション欠如
レコードの2WD/4WD逆転	割当ロジックの不具合	ORM（Eloquent等）のリレーション型不一致（VARCHAR↔INT）でEager Loadマッチングずれ
一部ユーザーで通知が届かない	通知送信ロジックの問題	論理削除フラグの扱いが delete() と forceDelete() で異なる

2. ハルシネーション防止チェック

原則: 自分の推論を疑い、必ず裏取りする

コードリーディングだけで判断せず、以下を必ず実行する。

チェックリスト

チェック項目	方法
カラム/フィールドが存在するか	SHOW COLUMNS / スキーマ定義ファイル確認（コード読みだけで判断しない）
データが存在するか	SELECT COUNT(*) FROM table WHERE ... / サンプル取得
型が一致するか	DB定義（INT/VARCHAR等）とコード側（$casts, dataclass 等）の両方を確認
外部キー/制約が存在するか	マイグレーション履歴を追跡（追加→削除→再追加の変遷を確認）
論理削除ポリシーは何か	SoftDeletes / deleted_at の有無を確認（delete() と forceDelete() の挙動が異なる）
環境差異がないか	dev/staging/prod で同じクエリを実行して比較

やってはいけないこと

• コードを読んだだけで「このカラムは存在しない」と断定する
• 1つのテーブル/ファイルだけ見て「データに問題はない」と結論づける
• マイグレーションの最終状態だけ見てFK制約の有無を判断する
• 論理削除の有無を確認せず delete() を使う

型不一致の検出パターン

ORMリレーションで以下の組み合わせは危険:

ローカルキー型	外部キー型	リスク
VARCHAR	INT	Eager Load マッチングでずれる可能性
INT	VARCHAR	同上
string	integer	strict comparison で不一致

対策: 型キャストで揃えるか、リレーション定義時に明示的に型変換する。

3. データとコードの整合性検証

原則: 仮説を立てたら、データとコードの両面から検証する

仮説: 「処理Aが項目Xを逆に割り当てている」
  → コード確認: 処理AのJOIN/代入ロジックを読む
  → データ確認: 上流テーブルの値と処理A結果の値を並べて比較
  → 結論: 上流データは正常、処理A結果が逆転 → 処理Aの問題

検証手順テンプレート

-- Step 1: 元データ（上流）を確認
SELECT * FROM source_table WHERE conditions ORDER BY updated_at DESC;

-- Step 2: 中間データを確認
SELECT * FROM intermediate_table WHERE conditions;

-- Step 3: 最終データ（下流）を確認
SELECT * FROM result_table WHERE conditions;

-- Step 4: 上流と下流を突合
-- 値が一致するか、変換ロジックが正しいか確認

4. 多層防御

1つの修正だけに頼らず、複数レイヤーで防御する

Layer 1: 取り込み時バリデーション（異常値を入れない）
Layer 2: 型整合性（正しくマッチングする）
Layer 3: 処理時の防御条件（異常値があっても除外する）
Layer 4: 出力時検証（結果の妥当性チェック）

単一レイヤーだけだと、将来別の経路で同じ問題が再発する可能性が残る。

5. 修正の進め方

修正順序

1. コードの修正を先に行う（根本原因の解消）
2. デプロイする
3. データの修復は修正済みコードで再実行する（migration や SQL 直接修正ではなく、パイプライン再実行が望ましい）
4. 検証で修正を確認する

コミット・PR戦略

• 根本原因の修正とデータ修復は別コミットにする（Revertしやすい）
• 重複コードは発見次第リファクタリングする
• 検証環境向けPRは cherry-pick-pr 方式で作成し、mainブランチを汚染しない（詳細は branch-fix-strategy スキル参照）

6. 調査レポートの書き方

必須項目

1. 症状: 何がどう間違っているか（定量的に）
2. 根本原因: コードレベルでどこが問題か（ファイル名:行番号）
3. エビデンス: DB クエリ結果 / ログ / コマンド出力で裏付ける
4. 修正方針: どのフェーズで何を直すか
5. 検証手順: 修正後にどう確認するか

エビデンスの書き方

**エビデンス（staging DB）**:
| key | value | updated_at | 状態 |
|---|---|---|---|
| A100 | 103,081 | 2026-04-01 10:49 | 異常（最新） |
| A100 |  44,390 | 2026-03-11 13:42 | 正常 |

SQLクエリ結果をそのまま貼り、「コードを読んだ推測」と「DBで確認した事実」を明確に区別する。

関連スキル

• /ndf:investigation-rules — 調査レポート作成時のエビデンス主義
• /ndf:branch-fix-strategy — 複数ブランチへの修正適用戦略
• /ndf:logging-guidelines — ログ設計（原因特定を容易にする）