Debug root cause

バグ調査・修正（debug-root-cause）

このスキルがやること

バグを「再現を観測してから、原因を説明できる状態にして、テストで再発を防いで」直す。推測で直す・症状だけ消すのを防ぐための順序の固定。

手順

1. 再現する: 最小の再現手順を確立し、失敗を実際に観測する。再現できないうちは修正に進まない。
   • 再現できない場合 → ログ・エラーメッセージ・環境差（OS/バージョン/データ）・発生条件の情報収集に戻る。それでも不能なら「再現不能」と、分かったこと・足りない情報を報告して指示を仰ぐ。
2. 切り分ける: 疑わしい範囲を半分に絞る操作を繰り返す。手段の例:
   • git bisect — いつのコミットから壊れたか
   • 入力の最小化 — どの入力・データで壊れるか
   • レイヤー分離 — UI / API / データ層のどこで値が壊れるか（境界でログ・デバッガで観測）
3. 根本原因を特定する: 「そのコードが、その入力で、なぜその症状を起こすか」を一文で説明できる状態まで。症状が消えた ≠ 原因が分かった。
4. 回帰テストを書く: 修正の前にバグを踏む失敗するテストを書き、red であることを確認する。
   • テストが書けない領域（環境依存・UI 目視等）→ 理由を報告し、手動再現手順を修正の説明に記録する。
5. 修正する: 根本原因に対する最小の変更。テストが green になることを確認する。
6. 水平展開を確認する: 同じパターンのバグが他に無いか（同じ関数の他の呼び出し元、コピペされた類似コード、同じ誤った前提を持つ箇所）を grep 等で確認する。

報告フォーマット

必ずこの構成で報告する:

## 症状
<何が起きていたか（再現手順つき）>

## 根本原因
<一文で。例: `parseDate()` がタイムゾーン無しの文字列を UTC として解釈するため、JST 環境で日付が 1 日ずれる>

## 修正内容
<何をどう変えたか（path:line）>

## 回帰テスト
<追加したテストと、修正前 red → 修正後 green を確認した旨。書けなかった場合は理由>

## 水平展開
<同種の箇所を確認した結果（あり→どうしたか / なし）>

ルール・コツ

• 修正候補が複数思いつく段階は、まだ原因が特定できていないサイン。修正に進まず切り分けに戻る。
• 「とりあえず try/catch」「とりあえず null チェック」は症状隠しになりやすい。なぜその値が来るのかを一段遡ってから判断する。
• git bisect 中に作業ツリーを変更しない。開始前に未コミット変更が無いことを確認する。
• 再現に本番データや外部サービスが必要な場合は、勝手に触らずユーザーに確認する。
• 修正とリファクタを混ぜない。修正過程で見つけた別の問題は create-issue で起票する。

完了条件

以下を全て満たしたら完了。満たせない項目があれば、黙って省略せず理由を報告する。

• 修正前に失敗（再現）を実際に観測した（再現不能の場合はその旨と収集した情報を報告した）
• 根本原因を一文で説明した
• 修正前に失敗し修正後に通る回帰テストを追加した（不能な場合は理由と手動再現手順を報告した）
• 水平展開の確認結果を報告した
• 報告フォーマットの全節（症状/根本原因/修正内容/回帰テスト/水平展開）を埋めた

補足

• 社名・内部 URL・認証情報などの固有情報は扱わない。
• 修正を PR にする場合は pre-pr-checks → create-pr へ続ける。