investigation-rules

name	investigation-rules
description	調査レポート作成のルール。否定的結論のエビデンス要件、残課題の記載フォーマット、ハルシネーション防止のための裏取り原則を扱う。DB調査に限らずコードベース調査・仕様調査一般に適用。
when_to_use	調査・デバッグ・不具合レポートを作成するとき。「ない」「該当なし」等の否定的結論を出すときは必ず参照。Triggers: '調査', 'デバッグ', '不具合レポート', '原因調査', 'investigation', 'root cause', 'カラムがない', '該当コードがない', 'データがない'

調査レポート作成ルール

不具合調査・データ調査・仕様調査でレポートを作成する際のルール。コード読解だけに頼らず、必ず実行結果・出力・実データで裏取りする。

否定的結論にはエビデンス必須

「カラムがない」「データがない」「関数が呼ばれていない」「該当コードがない」等の 否定的な結論 を書く場合、必ず実行結果をエビデンスとして添付すること。

なぜこのルールが必要か

AIは「もっともらしいが間違った推論」をしがちで、コード読解だけで「ない」と断定して誤判断を招きやすい。事例として、外部テーブルの一部カラムだけを見て「該当カラムなし」と結論づけたが、実際には別名のカラムにデータが存在していた、という判断ミスが典型。

具体的な裏取り方法

主張の種類	必須エビデンス
DB: カラムが存在しない	SHOW COLUMNS FROM table_name / DESCRIBE の結果
DB: データが存在しない	SELECT COUNT(*) FROM table WHERE ... の結果
DB: テーブルが存在しない	SHOW TABLES LIKE '%keyword%' の結果
コード: 関数/シンボルが存在しない	grep -rn 'name' . / LSP検索 / Serena find_symbol の結果
コード: 呼び出し箇所がない	find_referencing_symbols / grep の結果
設定: 値が存在しない	設定ファイルのdiff / env / config コマンド出力
ログ: エラーが出ていない	grep / 検索ツールのクエリと結果期間

レポートへの記載例

### 残課題

| 課題 | 概要 | エビデンス | 優先度 |
|------|------|-----------|--------|
| 外部API の retry 未実装 | Xクライアントで retry ハンドリングが無い | `grep -rn "retry\|Retry" src/client/x/` → 0件 | 中 |
| status=deleted の件数 | 論理削除レコードが残存 | `SELECT COUNT(*) FROM ... WHERE status='deleted'` → 2,341件 | 低 |

やってはいけないこと

• コードを読んだだけで「このカラムは存在しない」と断定する
• 1つのテーブル/ファイルだけ見て「データに問題はない」と結論づける
• 外部テーブルの一部のカラムだけ見て「他にはない」と判断する（全カラムを確認する）
• エビデンスなしで残課題の優先度を「低」にする（誤判断の典型）

外部データ調査の原則

外部API/外部テーブル/サードパーティデータソースを調査する際は、全体構造を必ず確認する。

-- まず全体像を把握する
SHOW COLUMNS FROM external_source_table;

-- 次に対象カラムのデータ分布を確認する
SELECT column_name, COUNT(*) FROM table GROUP BY column_name;

外部データは外部システム由来でカラム名・値域が予測しづらいため、コードから逆引きするだけでは見落とす。

ハルシネーション防止チェックリスト

推論で埋めず、必ず以下を実行して裏取りする:

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

調査結果の書き方テンプレート

## 症状
何がどう間違っているか（定量的に、エビデンス付きで）

## 調査経緯
1. 仮説1: xxx → クエリ/コマンドで確認 → 否定/肯定
2. 仮説2: yyy → ...

## 根本原因
コードレベルでどこが問題か（ファイル名:行番号で特定）

## エビデンス

SQL/コマンド実行結果をそのまま貼る

## 修正方針
どのフェーズで何を直すか（多層防御の観点）

## 検証手順
修正後にどう確認するか（回帰テスト含む）

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

関連スキル

• /ndf:problem-solving — 根本原因分析と多層防御の原則