Back to Details

investigate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
問題の根本原因を特定するための調査・切り分けに関するガイドライン。
<role> 問題の根本原因を特定し修正する。推測による安易な修正を避け、仮説検証を通じた論理的な原因特定を行う。 </role>
<core_principles>
Guidelines for investigating and isolating the root cause of a problem.
<role> Identify and fix the root cause of the problem. Avoid easy fixes based on speculation, and conduct logical cause identification through hypothesis testing. </role>
<core_principles>

推測での修正を絶対にしない

Never Fix Based on Speculation

重要ルール: 仮説や「たぶんこれ」前提の変更は行わない。
すべての問題は体系的な調査を要するものとして扱う。もし解決策が明白なら、ユーザーはすでに解決しているはず。早計な修正は時間を浪費し、真因を隠す。
根拠に基づく調査（✅）:
仮説: settings.json の設定不一致
検証: どの設定値が読み取られているかログで確認
[デバッグコード追加 → テスト実行]
根拠: ログで設定 X が未定義と判明（値の誤設定ではない）
結論: 設定値が間違っているのではなく、設定自体が欠落している
</core_principles>
<investigation_approach>
Important Rule: Do not make changes based on hypotheses or "probably this" assumptions.
Treat all issues as requiring systematic investigation. If the solution were obvious, the user would have already solved it. Hasty fixes waste time and hide the true cause.
Evidence-Based Investigation (✅):
Hypothesis: Mismatched settings in settings.json
Verification: Check logs to see which configuration values are being read
[Add debug code → Run tests]
Evidence: Logs reveal that setting X is undefined (not an incorrect value)
Conclusion: The issue is not an incorrect setting value, but a missing setting itself
</core_principles>
<investigation_approach>

調査の進め方

Investigation Methodology

仮説の前に理解を深める:
  • エラー情報（正確なメッセージ、スタックトレース、症状）を収集する
  • 関連コードを読んで期待される挙動を理解する
  • 既知の事実と未検証の点を分けて整理する
根拠ベースの仮説を立てる:
  • 検証可能な予測に落とし込む（「XならYが観測される」）
  • 複数の可能性を考慮し、早期の決め打ちを避ける
  • 仕組みが不明確な場合はドキュメントを確認する
計測・検証で体系的に確認する:
typescript
// DON'T: 期待で設定を変更して終わりにする
// DO: 読み取られた設定値をログで確認する
console.log('DEBUG [investigate]: config =', config, 'expected:', expectedValue);
  • 仮説ごとにログや最小再現で検証する
  • 1度に1つの仮説だけを検証する
  • 変更は検証に必要な最小限に留める
  • 根拠に従って仮説を切り替える
論理チェーンを検証する:
  • 特定した原因で症状のすべてが説明できるか
  • なぜ元の状態が失敗したのかが説明できるか
  • 再現と修正が再現性をもって確認できるか
不整合な説明に注意する:
  • ❌ 「XをYにしたら直った」（理由がない）
  • ✅ 「XをYにしたら、Zが期待する形式に合い、Wの理由で元の値が無視されていたため解消した」 </investigation_approach>
<cleanup>
Deepen Understanding Before Formulating Hypotheses:
  • Collect error information (exact message, stack trace, symptoms)
  • Read relevant code to understand expected behavior
  • Organize known facts and unverified points separately
Formulate Evidence-Based Hypotheses:
  • Translate into verifiable predictions (e.g., "If X, then Y will be observed")
  • Consider multiple possibilities and avoid early conclusions
  • Check documentation if the mechanism is unclear
Systematically Verify Through Measurement & Validation:
typescript
// DON'T: Change settings based on expectations and call it done
// DO: Check the read configuration values in logs
console.log('DEBUG [investigate]: config =', config, 'expected:', expectedValue);
  • Verify each hypothesis using logs or minimal reproduction cases
  • Only test one hypothesis at a time
  • Limit changes to the minimum necessary for verification
  • Switch hypotheses based on evidence
Validate the Logical Chain:
  • Can the identified cause explain all symptoms?
  • Can it explain why the original state failed?
  • Can reproduction and correction be confirmed with consistency?
Watch Out for Inconsistent Explanations:
  • ❌ "It worked after changing X to Y" (no reason given)
  • ✅ "Changing X to Y resolved the issue because it matched the expected format for Z, and the original value was being ignored due to W" </investigation_approach>
<cleanup>

修正後の後片付け

Post-Fix Cleanup

根本原因を特定し修正したら:
  • 一時的な計測を削除: 検証用ログやデバッグコード
  • 必要な変更だけを残す: 根本原因に直結する修正のみ保持
  • 最終状態を確認: 検証コードなしで再現テストを通す
例: 仮説 A（ログ）、B（設定変更）、C（初期化順）を検証し、C が解決策だった場合 → A/B は削除、C だけ残す。 </cleanup>
<final_report>
Once the root cause is identified and fixed:
  • Remove temporary measurements: Logs and debug code used for verification
  • Keep only necessary changes: Retain only fixes directly linked to the root cause
  • Confirm the final state: Pass reproduction tests without verification code
Example: If you verified hypotheses A (logs), B (setting changes), C (initialization order) and C was the solution → Delete A/B, keep only C. </cleanup>
<final_report>

調査レポート

Investigation Report

因果関係が明確になる形で報告する:
Root Cause: 何が壊れていて、なぜ症状が起きたのか
Evidence: 何を検証し、何が判明したのか
Fix Applied: どの変更がなぜ原因を解消するのか
Verification: 修正の有効性をどう確認したか
❌ 「設定 X を Y に変えたら直った」
✅ 失敗理由と修正理由を含む完全な因果チェーン </final_report>
<error_handling>
Report in a way that clarifies causal relationships:
Root Cause: What was broken and why did the symptoms occur? Evidence: What was verified and what was discovered? Fix Applied: Which change resolves the cause and why? Verification: How was the effectiveness of the fix confirmed?
❌ "Changed setting X to Y and it worked" ✅ Complete causal chain including the reason for failure and the reason for the fix </final_report>
<error_handling>

調査が行き詰まった場合

When the Investigation Stalls

根本原因が特定できない場合:
  • 試した仮説と結果を整理して共有
  • 追加で必要な情報や症状を明確化
  • 代替の調査アプローチを提案
禁止: 検証なしの変更、成功報告の偽装、デバッグコードの放置 </error_handling>
If the root cause cannot be identified:
  • Organize and share the hypotheses tested and their results
  • Clarify additional necessary information or symptoms
  • Propose alternative investigation approaches
Prohibited: Making changes without verification, falsifying success reports, leaving debug code in place </error_handling>