fix-hard

［IMPORTANT］ 作業を開始する前に、TaskCreate を使用して、ファイルを読む作業も含め、すべての作業を小さなタスクに分割してください。これにより、長いファイルによるコンテキストの喪失を防げます。簡単なタスクの場合、AI はスキップするかどうかを必ずユーザーに確認してください。

まずコードを理解する — 厳格な必須条件：既存のコードを読むまでは、記述、計画、修正を行わないでください。

1. 類似パターンを3つ以上検索します（grep／glob）。根拠として file:line を示してください
2. 対象領域の既存ファイルを読み、構造、基底クラス、規約を理解します
3. .code-graph/graph.db が存在する場合は、python .claude/scripts/code_graph trace <file> --direction both --json を実行します
4. connections または callers_of を使って依存関係を把握し、対象に依存するものを確認します
5. 重要なタスク（3ファイル以上）の調査内容を .ai/workspace/analysis/ に記録します
6. 実装前に分析ファイルを読み直します。記憶だけに頼って作業してはいけません
7. 既存のパターンが使える場合、新しいパターンを決して作らないでください。既存のものに厳密に従うか、逸脱を記録します

以下が完了するまで作業は禁止です： - [ ] 対象ファイルを読んだ - [ ] 3つ以上のパターンをgrepで検索した - [ ] グラフをトレースした（graph.db が存在する場合） - [ ] 仮定を根拠に基づいて検証した

根拠に基づく推論 — 推測は禁止です。すべての主張には証拠が必要です。

1. すべての主張に file:line、grep の検索結果、またはフレームワークのドキュメントを根拠として示します
2. 確信度を明示します：80%超なら自由に進め、60～80%なら先に検証し、60%未満なら推奨してはいけません
3. アーキテクチャの変更には、サービス間の検証が必須です
4. 「証拠が不十分です」は妥当であり、期待される回答です

以下が完了するまで作業は禁止です： - [ ] 根拠のファイルパス（file:line） - [ ] grep検索を実施した - [ ] 類似パターンを3つ以上見つけた - [ ] 確信度を明示した

証拠なしに使用してはいけない表現： "明らかに"、"私はそう思います"、"～のはずです"、"おそらく"、"これは～が原因です" 未完了の場合 → 次のように出力します："証拠が不十分です。検証済み：[...]。未検証：[...]。"

• docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関係、サービス間同期（タスクにビジネスエンティティ／モデルが関係する場合に読みます）（内容はフックによって自動挿入されます。読む前に [Injected: ...] ヘッダーがあるか確認してください）

見積もり — 修正フィボナッチ数列：1（ごく簡単）→ 2（小規模）→ 3（中規模）→ 5（大規模）→ 8（非常に大規模）→ 13（エピック、分割を推奨）→ 21（分割が必須）。計画のフロントマターに story_points と complexity を出力します。複雑度は自動算出されます：1～2＝低、3～5＝中、8＝高、13以上＝重大。 修正レイヤーの責任 — クラッシュした場所で修正してはいけません。処理の全体を追跡し、責任を持つレイヤーで修正します。

AI のデフォルト動作：場所 A でエラーを確認 → 場所 A を修正。これは誤りです。クラッシュした場所は症状であり、原因ではありません。

修正の前に必ず実施すること：

1. データフロー全体を追跡する — データの発生元からクラッシュした場所まで、すべてのレイヤー（ストレージ → バックエンド → API → フロントエンド → UI）にわたる完全な経路を図示します。不正な状態がクラッシュした場所ではなく、どこで入り込むかを特定します。
2. 不変条件の責任者を特定する — この値が有効であることを保証する契約を持つレイヤーはどれですか？そのレイヤーに責任があります。不変条件を所有する最も低いレイヤーで修正します。不変条件を利用する最も高いレイヤーではありません。
3. 1 つの修正で最大限保護する — 「ここで修正すれば、1 つの変更ですべての下流の利用者を保護できるか？」と確認します。防御チェックを追加するために 3 つ以上のファイルに手を入れる必要があるなら、レイヤーの選択が誤っています。より低いレイヤーで修正します。
4. 迂回経路がないことを確認する — すべてのデータフローが修正箇所を通ることを確認します。次の点を調べます。ファクトリーを経由しない直接構築、再検証を伴わないクローン／スプレッド、ドメインモデルでラップされていない生データ、モデルレイヤー外での変更。

次の条件を満たすまで作業を進めてはいけません： - [ ] データフロー全体（発生元 → クラッシュ）が追跡されている - [ ] 不変条件の責任者が file:line の証拠とともに特定されている - [ ] すべてのアクセス箇所が監査されている（grep の件数） - [ ] 修正レイヤーの妥当性が説明されている（最も多くの利用者を保護できる最も低いレイヤー）

アンチパターン（却下してください）：

• 「クラッシュした場所で修正する」— クラッシュした場所 ≠ 原因の場所です。上流を追跡してください。
• 「すべての利用者に防御チェックを追加する」— 防御が散在しているのは、レイヤーの選択が誤っている証拠です。散在する多数のガードより、権威ある 1 つの修正が優先されます。
• 「両方修正するほうが安全」— 権威あるレイヤーを 1 つ選びます。レイヤーをまたいだ重複チェックは、不変条件の責任者について相反するメッセージを発します。

スキルのバリアント： /fix のバリアントです。複雑な問題について、サブエージェントを使って深く調査します。

クイックサマリー

目標： 複数のサブエージェントによる並行調査を使って、複雑なバグを体系的に診断し、修正します。

ワークフロー：

1. 調査 — scout／researcher サブエージェントを使って、問題を並行して調査します
2. 診断 — 証拠をもとに、コードパスをたどって根本原因を追跡します
3. 計画 — 影響分析を含む修正計画を作成します
4. 修正 — 修正を実装し、検証します

主なルール：

• デバッグの心得：すべての主張に file:line の証拠が必要です
• 複数の仮説を並行して調査するには、サブエージェントを使用します
• 複雑な修正を実装する前に、必ず計画を作成します

根本原因のデバッグ — 推測や試行錯誤ではなく、体系的に進めます。

1. 再現 — 証拠（エラーメッセージ、スタックトレース、スクリーンショット）を使って、問題が存在することを確認します
2. 切り分け — 二分探索とグラフトレースを使って、対象を特定のファイル／関数／行に絞り込みます
3. 追跡 — 入力から失敗箇所までデータフローをたどります。推測せず、実際のコードを読みます。
4. 仮説を立てる — 信頼度（％）を添えて仮説を立てます。仮説を支持する証拠と反証する証拠を示します
5. 検証 — 対象を絞った grep／読み取りで仮説を検証します。一度に変更する変数は 1 つだけです。
6. 修正 — 症状ではなく根本原因に対処します。グラフの connections を使って、修正が呼び出し元を壊さないことを検証します

絶対にしてはいけないこと： 証拠なしに推測する。原因ではなく症状を修正する。再現の手順を省略する。

デバッグの心得（絶対遵守）

懐疑的に考えてください。批判的思考と順序立てた思考を適用します。すべての主張に、追跡可能な証拠と信頼度（％）が必要です（アイデアの信頼度は 80％を超えている必要があります）。

• 最初の仮説が正しいと思い込まず、実際のコードを追跡して検証します
• 根本原因に関するすべての主張に file:line の証拠を含めます
• コードの追跡で根本原因を証明できない場合は、「仮説であり、未確認です」と明記します
• 前提を問い直します：「本当にこれが原因ですか？」→ 実際の実行経路を追跡します
• 完全性を問い直します：「ほかに寄与している要因はありませんか？」→ 関連するコードパスを確認します
• 証拠なしに「これで直るはず」と判断せず、追跡した根本原因に修正が対処していることを検証します

⚠️ 必須：信頼度と根拠のゲート

必ず、すべての主張について、根拠リストと file:line の証拠を添えて Confidence: X% を明記してください。 95％以上：制限なく推奨できます | 80～94％：留保事項を添えます | 60～79％：不明点を列挙します | 60％未満：停止して、さらに証拠を集めてください。

これらの問題の修正を計画して着手するには、オーケストレーションプロトコル、コア責務、サブエージェントチーム、開発ルールに従って徹底的に考えてください。 $ARGUMENTS

ワークフロー：

ユーザーがスクリーンショットや動画を提供した場合は、ai-multimodal スキルを使用して問題をできるだけ詳しく説明し、開発者がその説明から根本原因を容易に予測できるようにしてください。

依頼への対応

すべてを問い直す：AskUserQuestion ツールを使用して、ユーザーの依頼、制約、真の目的を十分に理解するための掘り下げた質問をしてください。決めつけず、100％確信が持てるまで確認してください。

• 質問がある場合は、AskUserQuestion ツールを使用してユーザーに確認してください。
• 質問は一度に1つだけ行い、次の質問に進む前にユーザーの回答を待ってください。
• 質問がない場合は、次のステップに進んでください。

⚠️ 修正前に検証（必須）： 根本原因と計画を作成した後、必ず調査結果と修正案を AskUserQuestion でユーザーに提示し、コードを変更する前に明示的な承認を得てください。黙って修正してはいけません。

問題の修正

複雑な問題を順序立てた思考ステップに分解するには、sequential-thinking スキルを使用してください。 問題に取り組むには、problem-solving スキルを使用してください。 スキルカタログを分析し、作業中に必要な他のスキルを有効にしてください。

1. 問題の根本原因を特定するため、debugger サブエージェントを使用し、調査結果をメインエージェントに報告させてください。 1.5. 調査結果を .ai/workspace/analysis/{issue-name}.analysis.md に書き込んでください。修正を計画する前に、ファイル全体を再読してください。
2. 必要に応じて、根本原因をインターネットですばやく調査するため、researcher サブエージェントを使用し、調査結果をメインエージェントに報告させてください。
3. 報告に基づいた実装計画を作成するため、planner サブエージェントを使用し、その後、メインエージェントに報告させてください。
4. 🛑 根本原因と修正計画を提示 → AskUserQuestion → ユーザーの承認を待つ。
5. その後、/code スラッシュコマンドを使用して、計画を段階的に実装してください。
6. 最終報告：

• 変更内容を要約し、要点を簡潔に説明してください。ユーザーが使い始める方法を案内し、次のステップを提案してください。
• Git リポジトリへのコミットとプッシュを希望するかユーザーに尋ねてください。希望する場合は、git-manager サブエージェントを使用してコミットとプッシュを行ってください。

• 重要： 報告では、簡潔さを優先し、文法上の完全さにこだわらないでください。
• 重要： 未解決の質問がある場合は、報告の末尾に列挙してください。

忘れないでください：

• ビジュアル素材は、必要に応じていつでも ai-multimodal スキルで生成できます。

• 生成した素材は、要件を満たしているか確認するため、必ず ai-multimodal スキルで読み取って分析してください。

• 背景の削除、調整、トリミングなどの画像編集には、必要に応じて media-processing スキルを使用してください。

• 修正後は、必ず /prove-fix を実行してください — 変更ごとに、信頼度スコア付きのコード証跡を作成してください。省略してはいけません。

---

次のステップ（単独実行：必ず AskUserQuestion でユーザーに確認してください。ワークフロー内の場合は省略します。）

必須 — 例外なし： このスキルがワークフロー外で呼び出された場合は、必ず AskUserQuestion を使用して、以下の選択肢をユーザーに提示してください。「簡単そう」「明らか」といった理由で省略してはいけません。判断するのはユーザーです。

• 「完全なワークフローを続行（推奨）」 — ここから最適なワークフローを判断して続行します（修正適用済み）。これにより、修正証明、レビュー、テスト、ドキュメントの手順を省略せずに進められます。
• 「/prove-fix」 — コードの証跡で修正の正しさを証明します
• 「/test」 — テストを実行して修正を検証します
• 「スキップして手動で続行」 — ユーザーが選択します

すでにワークフロー内にいる場合は省略してください。ワークフロー側で順序を管理します。

締めくくりの注意事項

• 重要・必ず注意 作業を始める前に、TaskCreate を使って作業を小さな TODO タスクに分割してください。

• 重要・必ず注意 新しいコードを作成する前に、コードベースを検索して類似パターンを 3 件以上確認してください。

• 重要・必ず注意 主張する内容にはすべて file:line 形式の根拠を示してください（確信度が 80% を超える場合に対応してください）。

• 重要・必ず注意 作業の品質を確認するための最終レビュー用 TODO タスクを追加してください。

• 重要・必ず注意 修正に 3 回失敗したら作業を停止してください。結果を報告し、4 回目を試す前にユーザーに確認してください。 必須・重要・必ず注意 作業を始める前に、次のファイルを読んでください：

• 重要・必ず注意 変更を加える前に、既存のパターンを 3 件以上検索し、コードを読んでください。graph.db が存在する場合は、グラフトレースを実行してください。

• 重要・必ず注意 主張する内容にはすべて file:line 形式の根拠を示してください。対応するのは確信度が 80% を超える場合のみとし、60% 未満の場合は推奨しないでください。

• 重要・必ず注意 計画のフロントマターに story_points と complexity を含めてください。SP が 8 を超える場合は分割してください。

• 重要・必ず注意 データフロー全体を追跡し、クラッシュが発生した箇所ではなく、その処理を所有するレイヤーで修正してください。?. を追加する前に、アクセス箇所をすべて監査してください。