diagnose-bug

バグを診断する

症状から修正に飛びつかないでください。実際に何が起きているのか、そもそも不具合なのか、そしてその理由をまず確かめます。

ゲート

以下の4項目がこのスキルの要点です。以降のプロセスは、これらを満たすためのものです。

1. 編集前に再現する。 再現可能なシグナルで症状を確認するまでは、製品に変更を加えません。再現できない場合は、試したことと必要なことを伝え、推測で修正してはいけません。
2. 変更前に仮説を立てる。 原因候補はそれぞれ、反証可能な予測として示し、修正を書く前に検証します。
3. 同じシグナルで検証する。 再現手順を再実行し、症状がなくなったことを確認して、修正が確かめられます。/verification-evidence を適用します。
4. このバグに集中する。 作業中に見つけたほかの問題は報告し、同じ変更では修正しません。

プロセス

1. 症状を言い換える

報告内容を具体的に記録します。何が起きたのか、何が期待されていたのか、どこで起きたのか、既知の入力、環境、タイミング、最近の変更は何かを捉えます。観察された事実と推測を分けます。依頼が添えられていないエラーやログの貼り付けも報告として扱い、そこに示されている内容を言い換えます。

2. 分類する：不具合、設計、または環境

原因を探す前に、その期待自体を確認します。報告された動作は、システムが意図どおりに動いている結果かもしれません。

• 設計 — コード、ドキュメント、設定、または以前に承認された計画で、その動作が意図されています（未認証アクセスをブロックする認証ゲート、レート制限、ダウンロードを拒否するゲート付きモデルなど）。意図がどこで定められているかを示します。
• 環境または設定 — システム自体は正しく、ユーザーのセットアップ、認証情報、デプロイ先、またはデータに問題があります（環境変数の不足、ローカルとリモートのデータベースの違い、古いビルドなど）。
• 不具合 — 動作が意図された設計に反しています。
• 不明 — リポジトリから意図を確認できません。

設計または環境の問題と判明した場合は、理由と根拠、そしてユーザーが変更すべきもの（ユーザーのセットアップ、または設計自体の変更を望む場合は /plan-it への機能リクエスト）を説明して、ここで終わります。意図された動作を「修正」してはいけません。意図が不明な場合は、根拠を添えてユーザーに質問します。どちらかを勝手に選ぶ許可ではありません。

3. フィードバックループを作る

付近のコードを示すだけでなく、ユーザーの症状そのものを示す、最も速く信頼できるシグナルを見つけます。リポジトリの検証スキルが症状のある画面を操作する場合は、その Doctor を実行し、Launch と Drive の手順を通じて症状に到達します。状況に合うものを選びます。以下は選択肢であり、順番に実行するものではありません。

1. 既存の失敗するテスト、または対象を絞った新しい回帰テスト。
2. 最小限のコマンド、スクリプト、または CLI 呼び出し。
3. 実行中のシステムに対する HTTP リクエスト、UI 操作、またはブラウザー自動化。
4. 実際の入力、ログ、トレース、ペイロード、またはスナップショットの再生。
5. 対象モジュールを囲む、一時的なハーネス。
6. 症状が断続的な場合の、入力の反復または生成。
7. 自動化がまだできない場合の、手動での再現手順。

テストやハーネスの作成はファイルの変更です。依頼者が編集を許可している場合に限り作成します。読み取り、実行、クエリにはその許可は不要ですが、共有システムや本番システムへの書き込みは、再現のためであっても常に承認が必要です。

4. 再現して最小化する

ループを実行して症状を確認します。次に、残る入力、設定、手順がすべて欠かせない要素になるまでシナリオを絞り込みます。症状を再現できない場合は、どの根拠から環境の問題またはすでに修正済みと判断できるかを伝えます。

5. 追跡して仮説を立てる

関連するエントリーポイント、状態の変化、IO、エラーパスを通じて動作を追跡します。原因候補に順位をつけ、それぞれ次の形式で示します。

If <cause> is true, then <probe or change> should show <result>.

最も有力なものから、一度に1つの変数だけを変えて検証します。以前の診断が間違っていたかどうかをユーザーに尋ねられた場合は、その診断を擁護するのではなく、仮説として改めて検証します。

6. 修正して検証する

修正が依頼され、原因が確認できた場合は、原因を取り除く最小限の変更を加えたうえで、手順 3 のシグナルを再実行し、症状がなくなったことを示します。原因を検出できる回帰テストがある場合は、維持してください。リポジトリに検証スキルがある場合は、修正が触れる Where it lives のパスが記載された機能ファイルすべてと、この診断で判明した起動手順や注意点を、同じ差分で更新してください。修正に設計上の判断が必要な場合や、この不具合の範囲を超える場合は、作業を中止して /plan-it に引き継いでください。

出力

- Symptom: <restated>
- Classification: <defect / design / environment / unknown> — <evidence>
- Reproduction: <signal and result, or what blocked it>
- Cause: <confirmed hypothesis and the evidence>
- Fix: <change made, or "diagnosis only">
- Verification: <same signal rerun, its evidence kind, runs and results, uncovered conditions — or "unverified" with why it could not be rerun or did not settle>
- Other issues found: <reported, not fixed>
- Verify skill: <what this diagnosis had to discover about running the project, and — if a fix was made — the feature-file updates in the fix's diff; or "nothing new">

完了条件

報告では、証拠を示して挙動を分類します。設計または環境の問題の場合は、説明と次の手順を明記し、プロダクトコードは変更しません。不具合の場合は、症状を再現済み（または阻害要因を明記）であり、テスト済みの仮説で原因を説明します。さらに、修正が依頼されている場合は、修正後に同じ手順で再現を試み、症状が再発しないことを確認し、手順 6 の要件どおりに検証スキルを更新し、ほかに見つかった問題があれば修正せずに報告します。