problem-solvinglisted

# 問題解決ガイドライン データ不整合、バグ、障害対応における問題解決の原則と手順。 ## 1. 根本原因を探る（つじつま合わせをしない） ### 原則: 上流で直す 問題はデータフローの**最も上流**で修正する。下流でのパッチ（migrationによるデータ修正、SQL直接更新、出力時の辻褄合わせ）は最終手段。 ``` ❌ 悪いパターン DBに異常データがある → migrationで論理削除 → バッチ再実行 ✅ 良いパターン DBに異常データがある → なぜ入ったか調査 → 取り込みロジックにバリデーション追加 → 異常データを論理削除 → バッチ再実行 ``` ### 判断フロー ``` 1. 症状を確認（どのデータ・どの機能が、どう間違っているか） 2. データフロー/呼び出しチェーンを遡る（結果 → 計算 → 素材 → 取り込み → 外部ソース） 3. 最初に異常が発生した地点を特定 4. 再現テストを追加する（この時点で失敗することを確認する。下記「再現テストを先に書く」） 5. その地点のコードを修正 6. 再現テストが通ることを確認する 7. 下流にも防御的チェックを追加（多層防御） 8. 修正後にデータ修復（パイプライン再実行） ``` 根本原因がこの変更の範囲の外にあった場合は、`/ndf:out-of-scope` を起動して起票する。 上流で直すことと、この変更で直すことは別である。**起票先のリポジトリもその Skill が 決める。** 上流の原因は、別のリポジトリの課題であることがある。 **「上流で直す」と、棚卸の「ルートコーズ」は見る対象が違う。** ここで上流をたどるのは、 見つけて直している最中の不具合である。起票済みの課題を一覧で見比べ、現れている場所ではなく 根本原因の場所で直すと決めるのは、課題の棚卸の「ルートコーズ」である （[issue-upkeep](../issue-upkeep/SKILL.md)）。 ### 再現テストを先に書く（必須） **修正の前に、不具合を再現する失敗テストを追加する。** 再現できないまま修正すると、 直ったかどうかを判定できず、同じ不具合の再発も検出できない。 | 確認すること | 目的 | | --- | --- | | 追加したテストが**失敗する** | 不具合を再現できている | | 失敗の理由が症状と一致する | 別の原因で落ちていない | | 修正後に**通る** | 直ったことの証跡 | | テストを残す | 同じ退行を二度検出できる | サイクルの詳しい進め方は `tdd-cycle`（未導入なら対象プロジェクトの既存テスト手順）に従う。 **再現テストが書けないときは、再現条件がまだ特定できていない。** 修正へ進まず 1〜3 に戻る。 どうしても自動テストにできない場合（外部環境依存など）は、手動の再現手順と確認結果を 記録して代わりとし、その旨を報告に明記する。 ### テストが困難な既存コードでは現状固定テストを先行する 対象にテストがほとんどない場合、再現テストを書く前に**現状の振る舞いを固定するテスト**を 置く。副作用を分離できず再現テストが書けない状態で修正すると、直したい振る舞い以外を 壊しても気づけない。手順は `refactoring` の現状固定テストに従う。 ```text 1. 変更対象の入口と副作用を洗い出す 2. 現状の出力を固定するテストを置く（不具合を含む現状も