turntuptechnologies-ai バグ調査・修正（debug-root-cause）
このスキルがやること
バグを「再現を観測してから、原因を説明できる状態にして、テストで再発を防いで」直す。推測で直す・症状だけ消すのを防ぐための順序の固定。
手順
- 再現する: 最小の再現手順を確立し、失敗を実際に観測する。再現できないうちは修正に進まない。
- 再現できない場合 → ログ・エラーメッセージ・環境差（OS/バージョン/データ）・発生条件の情報収集に戻る。それでも不能なら「再現不能」と、分かったこと・足りない情報を報告して指示を仰ぐ。
- 切り分ける: 疑わしい範囲を半分に絞る操作（
git bisect・入力の最小化・レイヤー境界での観測など）を繰り返す。 - 根本原因を特定する: 「そのコードが、その入力で、なぜその症状を起こすか」を一文で説明できる状態まで。症状が消えた ≠ 原因が分かった。
- 回帰テストを書く: 修正の前にバグを踏む失敗するテストを書き、red であることを確認する。
- テストが書けない領域（環境依存・UI 目視等）→ 理由を報告し、手動再現手順を修正の説明に記録する。
- 修正する: 根本原因に対する最小の変更。テストが green になることを確認する。
- 水平展開を確認する: 同じパターンのバグが他に無いか（同じ関数の他の呼び出し元、コピペされた類似コード、同じ誤った前提を持つ箇所）を grep 等で確認する。
報告フォーマット
必ずこの構成で報告する:
## 症状
<何が起きていたか（再現手順つき）>
## 根本原因
<一文で。例: `parseDate()` がタイムゾーン無しの文字列を UTC として解釈するため、JST 環境で日付が 1 日ずれる>
## 修正内容
<何をどう変えたか（path:line）>
## 回帰テスト
<追加したテストと、修正前 red → 修正後 green を確認した旨。書けなかった場合は理由>
## 水平展開
<同種の箇所を確認した結果（あり→どうしたか / なし）>
ルール・コツ
- 修正候補が複数思いつく段階は、まだ原因が特定できていないサイン。修正に進まず切り分けに戻る。
- 「とりあえず try/catch」「とりあえず null チェック」は症状隠しになりやすい。なぜその値が来るのかを一段遡ってから判断する。
git bisect中に作業ツリーを変更しない。開始前に未コミット変更が無いことを確認する。- 再現に本番データや外部サービスが必要な場合は、勝手に触らずユーザーに確認する。
- 修正とリファクタを混ぜない。修正過程で見つけた別の問題は create-issue で起票する。
完了条件
以下を全て満たしたら完了。満たせない項目があれば、黙って省略せず理由を報告する。
- 修正前に失敗（再現）を実際に観測した（再現不能の場合はその旨と収集した情報を報告した）
- 根本原因を一文で説明した
- 修正前に失敗し修正後に通る回帰テストを追加した（不能な場合は理由と手動再現手順を報告した）
- 水平展開の確認結果を報告した
- 報告フォーマットの全節（症状/根本原因/修正内容/回帰テスト/水平展開）を埋めた
補足
- 社名・内部 URL・認証情報などの固有情報は扱わない。
- 修正を PR にする場合は pre-pr-checks → create-pr へ続ける。