fix-hard

クイック概要

目的: 並列サブエージェント調査を使用して、複雑なバグを体系的に診断して修正します。

ワークフロー:

1. 偵察 — scout/researcher サブエージェントを使用して、問題を並列に探索します
2. 診断 — コードパス全体のエビデンスを使用して根本原因を追跡します
3. 計画 — 影響分析を含む修正計画を作成します
4. 修正 — 修正を実装して検証します

主要ルール:

• デバッグマインドセット: すべての主張には file:line エビデンスが必要です
• 複数の仮説の並列調査にサブエージェントを使用します
• 複雑な修正を実装する前に必ず計画を作成します

デバッグマインドセット（非交渉）

懐疑的になりましょう。批判的思考と順序立てた思考を適用します。すべての主張には追跡可能な証拠と信頼度パーセンテージが必要です（アイデアは80%以上であることが望ましい）。

• 最初の仮説が正しいと仮定してはいけません — 実際のコードトレースで検証します
• すべての根本原因の主張には file:line エビデンスが含まれている必要があります
• コードトレースで根本原因を証明できない場合は、「仮説、未確認」と述べます
• 仮定に疑問を持つ: 「これが本当の原因ですか？」→ 実際の実行パスを追跡します
• 完全性に挑戦する: 「他に寄与する要因はありますか？」→ 関連するコードパスをチェックします
• 証拠なしに「修正するはずです」はありません — 修正が追跡された根本原因に対応することを確認します

⚠️ 必須: 信頼度とエビデンスゲート

必須 重要 必読 注意 すべての主張に対して、エビデンスリスト + file:line 証拠付きで Confidence: X% を宣言してください。 95%以上 自由に推奨 | 80-94% 注記付き | 60-79% 不明点を列挙 | 60%未満 停止 — より多くのエビデンスを収集してください。

ウルトラシンク これらの問題の計画と修正を開始するために、オーケストレーションプロトコル、コア責任、サブエージェントチーム、開発ルールに従います: <issues>$ARGUMENTS</issues>

ワークフロー:

ユーザーがスクリーンショットまたはビデオを提供する場合は、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、レビュー、テスト、ドキュメント化のステップがスキップされないことが保証されます。
• 「/prove-fix」 — コードトレースで修正の正確性を証明します
• 「/test」 — 修正を検証するテストを実行します
• 「スキップ、手動で続行」 — ユーザーが決定します

ワークフロー内にある場合はスキップします — ワークフローがシーケンス処理を処理します。

[重要] TaskCreate を使用して、開始前にすべての作業を小さなタスクに分割します — ファイル読み取りの各タスクを含みます。これにより、長いファイルからのコンテキスト損失が防止されます。簡単なタスクの場合、AIはユーザーにスキップするかどうかを尋ねる必要があります。

• docs/project-reference/domain-entities-reference.md — ドメインエンティティカタログ、関係、クロスサービス同期（タスクがビジネスエンティティ/モデルに関わる場合は読む）（関連する場合は直接読む、フック注入の会話テキストに依存しない）

スキルバリアント: /fix のバリアント — 複雑な問題に対するサブエージェントによる深い調査。

<!-- SYNC:root-cause-debugging -->

根本原因デバッグ — 体系的アプローチ、推測と確認はしません。

1. 再現 — エビデンス（エラーメッセージ、スタックトレース、スクリーンショット）で問題が存在することを確認します
2. 分離 — 二分探索 + グラフトレースを使用して、特定のファイル/関数/行に絞ります
3. トレース — 入力から障害ポイントまでのデータフローをたどります。実際のコードを読み、推測しないでください。
4. 仮説 — 信頼度%で理論を形成します。エビデンスがそれをサポート/矛盾することを述べます
5. 検証 — ターゲット化されたgrep/読みで仮説をテストします。一度に1つの変数です。
6. 修正 — 症状ではなく根本原因に対処します。グラフ connections を使用して修正が呼び出し元を破らないことを確認します

決してしないこと: エビデンスなしで推測します。症状ではなく原因を修正します。再現ステップをスキップします。

<!-- /SYNC:root-cause-debugging --> <!-- SYNC:nested-task-creation -->

ネストされたタスク展開契約 — ワークフローステップ呼び出しの場合、[Workflow] ... 行は親コンテナのみです。子スキルは引き続き表示フェーズタスクを作成します。

1. TaskList を最初に呼び出します。一致するアクティブな親ワークフロー行が存在する場合は、nested=true を設定して parentTaskId を記録します。そうでない場合は、スタンドアロンで実行します。
2. フェーズ作業前に、宣言されたフェーズごとに1つのタスクを作成します。ネストされた場合、件名に [N.M] $skill-name — phase というプレフィックスを付けます。
3. ネストされた場合、TaskUpdate(parentTaskId, addBlockedBy: [childIds]) で親をリンクします。
4. オーケストレータは、その子スキルまたはサブエージェントを呼び出す前に、子スキルのフェーズリストを事前に展開し、ワークフロー行をリンクする必要があります。
5. ワーク前に正確に1つの子を in_progress にマークし、エビデンス書き込み直後に completed にマークします。
6. すべての子タスクが完了するか、理由を明記して明示的にキャンセルされた後でのみ、親を完了します。

ブロック対象: TaskList 完了、子フェーズ作成、ネストされた場合は親リンク、最初の子が in_progress にマーク。

<!-- /SYNC:nested-task-creation --> <!-- SYNC:project-reference-docs-guide -->

プロジェクト参照ドキュメントゲート — タスク追跡ブートストラップ後、ターゲット/ソースファイル読み取り、grep、編集、分析の前に実行します。プロジェクトドキュメントはジェネリックフレームワークの仮定をオーバーライドします。

1. スコープを特定: ファイルタイプ、ドメインエリア、操作。
2. トリガー別の必須ドキュメント: 常に docs/project-reference/lessons.md; ドキュメント検索 docs-index-reference.md; レビュー code-review-rules.md; バックエンド/CQRS/API backend-patterns-reference.md; ドメイン/エンティティ domain-entities-reference.md; フロントエンド/UI frontend-patterns-reference.md; スタイル/デザイン scss-styling-guide.md + design-system/README.md; 統合テスト integration-test-reference.md; E2E e2e-test-reference.md; フィーチャードキュメント/仕様 feature-docs-reference.md; アーキテクチャ/新しいエリア project-structure-reference.md。
3. 存在する必須ドキュメントはすべて読み、存在しないドキュメントは適用されないようにスキップします。[Injected: <path>] などの会話テキストを、現在のコンテキストにドキュメントが含まれていることの証拠として信頼しないでください。
4. ターゲット作業前に、Reference docs read: ... | Missing/not applicable: ... と述べます。

ブロック対象: スコープ評価、必須ドキュメント確認/読み取り、lessons.md 確認、引用発行。

<!-- /SYNC:project-reference-docs-guide --> <!-- SYNC:task-tracking-external-report -->

タスク追跡と外部レポート永続化 — 実行前にこれをブートストラップします。その後、ターゲット/ソースワーク前にプロジェクト参照ドキュメントプリフェッチを実行します。

1. ターゲットファイル読み取り、grep、編集、分析前に、小さなタスク分解を作成します。コンテキスト損失時は、現在のタスクリストを最初に検査します。
2. ワーク前に1つのタスクを in_progress にマークし、エビデンス直後に completed にマークします。バッチ遷移は決してしません。
3. 計画/レビューワークの場合、最初の調査結果前に plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md を作成します。
4. 各ファイル/セクション/決定の後に調査結果を追加し、最後にレポートファイルから総合します。
5. 最終出力は Full report: plans/reports/{filename} を引用します。

ブロック対象: タスク分解存在、計画/レビュー作業用レポートパス宣言、最初の調査結果が次の調査結果前に永続化。

<!-- /SYNC:task-tracking-external-report --> <!-- SYNC:critical-thinking-mindset -->

批判的思考マインドセット — 批判的思考と順序立てた思考を適用します。すべての主張には追跡可能な証拠が必要で、80%以上の信頼度で行動します。 アンチハルシネーション: 推測を事実として提示しないでください — すべての主張のソースを引用し、不確実性を自由に認め、出力を自己チェック、独立して相互参照、自分の確信性に懐疑的に — 根拠のない確実性はすべてのハルシネーションの根です。

<!-- /SYNC:critical-thinking-mindset --> <!-- SYNC:understand-code-first -->

コードを最初に理解する — ハードゲート: 既存コードを読むまで、変更、計画、修正をしないでください。

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. 重大でないタスクの調査を .ai/workspace/analysis/ に記述（3つ以上のファイル）
6. 実装前に分析ファイルを再読 — メモリだけで作業しない
7. 既存パターンが機能している場合、新しいパターンを発明しません — 正確に一致させるか、偏差を記録します

ブロック対象: - [ ] ターゲットファイル読み取り - [ ] 3つ以上のパターンをgrep - [ ] グラフトレース（graph.dbが存在する場合） - [ ] エビデンスで仮定を検証

<!-- /SYNC:understand-code-first --> <!-- SYNC:evidence-based-reasoning -->

エビデンスベースの推論 — 推測は禁止されています。すべての主張に証拠が必要です。

1. すべての主張に対して file:line、grep結果、またはフレームワークドキュメントを引用します
2. 信頼度を宣言: >80%で自由に行動、60-80%で最初に検証、<60%で推奨しません
3. アーキテクチャ変更にはクロスサービス検証が必要です
4. 「十分なエビデンスがありません」は有効で期待される出力です

ブロック対象: - [ ] エビデンスファイルパス（file:line）- [ ] grep検索実施 - [ ] 3つ以上の類似パターン見つかった - [ ] 信頼度レベル述べた

証拠なしで禁止: 「明らかに」、「思うに」、「すべきです」、「おそらく」、「これはなぜなら」 不完全な場合 → 出力: "不十分なエビデンス。検証済み: [...]. 未検証: [...]."

<!-- /SYNC:evidence-based-reasoning --> <!-- SYNC:estimation-framework -->

見積もりフレームワーク — ボトムアップ優先; SP 導出; 可能性があれば ≥3d の場合、最小-最大範囲で出力します。スタック非依存。ベースライン: 3-5年開発、1日6時間生産。AI見積もりはClaudeコード + プロジェクトコンテキストを仮定します。

方法:

1. ブラストラディウスパス（以下）— コードとテストコストを駆動
2. フェーズを分解 → 時間/フェーズ → bottom_up_hours = Σ phase_hours
3. likely_days = ceil(bottom_up_hours / 6) × productivity_factor
4. リスクマージン（ベース + 追加）を合計 → max_days = likely_days × (1 + margin)
5. min_days = likely_days × 0.9
6. likely_days ≥3 の場合は範囲として出力; <3 は単一ポイント許可（マージンを記録）
7. man_days_ai = 同じ範囲 × AI高速化
8. story_points は SP-Days 経由で likely_days から導出 — ドライバーではありません。不同意 >50% → ボトムアップを信頼

生産性係数: 0.8 強力なスキャフォルディング+コード生成+AIフック · 1.0 成熟デフォルト · 1.2 弱いパターン · 1.5 グリーンフィールド

コストドライバーヒューリスティック（作業タイプ行の前に適用）:

• UI が支配的 CRUD/ビジネスアプリ — バックエンド 1.5-3x（状態、検証、レスポンシブ、a11y、ポリッシュ）
• バックエンド優位のみ: マルチアグリゲート不変、クロスサービスコントラクト、スキーママイグレーション、重いクエリ/パフォーマンス、新しいイベントフロー

再利用対作成軸（主要レバー、レイヤーごと）:

UI層	コスト
既存画面のコンポーネントを再利用	0.1-0.3d
既存画面に制御/列を追加	0.3-0.8d
コンポーネントを新規画面に構成	1-2d
新規画面、カスタムレイアウト/状態/検証	2-4d
新規共有/共通コンポーネント（テーマ化、テスト済み）	3-6d+

バックエンド層	コスト
既存場所からクエリ/ハンドラを再利用	0.1-0.3d
既存ハンドラ/エンティティへの小さな更新	0.3-0.8d
既存リポジトリ/モデルの新規クエリ	0.5-1d
既存アグリゲートの新規コマンド/ハンドラ（追加）	1-2d
新規アグリゲート/エンティティ（リポジトリ、検証、イベント）	2-4d
新規クロスサービスコントラクト またはスキーママイグレーション	2-4d 各
マルチアグリゲート不変 / 重いドメインルール	3-5d

ルール: UI+バックエンド+テスト全体でレイヤーを合計し、生産性係数を適用します。再利用はレイヤーをショートサーキット — コールアウトします。

テストスコープドライバー（test_count を明示的に計算 — "+tests" 手波は#1失敗）:

ドライバー	カウント
ハッピーパスジャーニー	1/ストーリー / AC メインフロー
状態マシン遷移	到達可能な遷移 × 許可されたアクター
マルチエンティティ状態コンボ	state(A) × state(B) — 到達可能のみ、直積ではない
認可マトリックス	（所有者、非所有者、昇格、未認証）× 各ミューテーション
検証ルール	1 / 必須フィールド / 境界 / フォーマット / クロスフィールド
UI状態（新規画面/ダイアログごと）	happy、loading、empty、error、partial — 存在するもののみ
負のパス / 不変	1 / 違反可能なビジネスルール

テストレイヤー（従来、セットアップ+アサート+フレーク含む）	コスト
1-5ケース、再利用フィクスチャ	0.3-0.5d
6-12ケース、1新規フィクスチャ	0.5-1d
13-25ケース、マルチエンティティセットアップ	1-2d
26-50ケース または 新規状態マシンカバレッジ	2-3d
>50ケース または 完全E2Eジャーニー	3-5d

テスト乗数: 新規フィクスチャ/シードハーネス +0.5d · クロスサービス/バスアサーション +0.3d 各 · UI E2E ×1.5 · 各新規ロール +1-2ケース

ブラストラディウス（必須プリパス — コードとテストに影響）:

1. 直接変更されたファイル/コンポーネント — カウント
2. このうち、「複雑」（>500 LOC、マルチハンドラ、中央、頻繁に変更）— カウント
3. ダウンストリームコンシューマー（呼び出し元、イベントサブスクライバー、クロスサービス）— リスト
4. 共有/共通コード（マルチアプリブラスト）— はい/いいえ
5. リグレッションスコープ — 再テストが必要な領域

ルール: 複雑なタッチ → risk_factors を追加します。各ダウンストリームコンシューマー → +1-3リグレッションケース。ブラスト >5エリア または >2複雑 → 見積もり前に分割を再評価します。

リスクマージン（最大境界を駆動）:

likely_days	ベースマージン
<1d trivial	+10%
1-2d small additive	+20%
3-4d real feature	+35%
5-7d large	+50%
8-10d very large	+75%
>10d	+100% AND 分割フラグ SHOULD SPLIT

リスク係数追加（追加 — enumerate in risk_factors）:

| 係数 | +マ