aif-fix

修正 - バグ修正ワークフロー

コードベース内の特定のバグや問題を修正します。即時修正と計画優先の2つのモードに対応しています。デフォルトのワークフローは、リグレッションチェックが必要な場合は常にリグレッション優先です。問題を再現し、報告された動作を確認してから修正を実装し、同じチェックに合格することを確認します。

ワークフロー

標準のリグレッション優先ポリシー

リグレッションチェックとは、報告されたバグを実証する、または期待される動作を検証するための、最小限で有用なテスト、コマンド、フィクスチャ、API 呼び出し、ブラウザーシナリオ、スクリプト、あるいは文書化された手動／ランタイムでの再現手順です。

バグにリグレッションテストが必要な場合は、すべてのワークフローパス（即時修正、計画優先、既存計画の実行）でこのポリシーに従います。

1. 問題を再現する、または期待される動作を示す、最小限のリグレッションチェックを特定します。
2. 実装前にチェックを実行し、失敗するか、報告された問題を再現することを確認します。
3. 根本原因に対処する最小限の修正を実装します。
4. まったく同じチェックを再実行し、合格することを確認します。
5. その後に限り、実施可能であれば関連する既存のチェックを実行し、有用であれば、より広範なテストを提案します。

フォールバックの動作：

• 自動実行可能なチェックがない場合は、最も範囲を絞った手動／ランタイムでの再現手順と、実行可能なチェックが存在しない理由を文書化します。再実行可能な場合は、その文書化された再現手順をステップ4のリグレッションチェックとして扱います。
• 有用なリグレッションチェックがまったくない場合は、実装前にその理由を記録します。HANDOFF_MODE=1 の場合、安全に修正できる妥当な根本原因が調査で見つかったときに限り続行します。それ以外の場合は、タスクをブロック中／再現不能として報告し、実装コードを変更せずに停止します。手動モードの場合は、推定される修正で続行するか、再現手順を調整するか、さらに調査するかを確認します。
• 修正前のリグレッションチェックが予想に反して合格した場合は、再現条件の不一致として扱います。コマンド／チェック、入力、環境に関する前提条件、および確認された結果を記録します。その後、上記と同じ HANDOFF_MODE=1 または手動モードのフォールバックに従います。

後続のワークフローセクションで、このポリシーを重複して記載したり、弱めたりしないでください。後続のステップでは、このセクションを参照し、その場での実行に関する詳細のみを追加してください。

ステップ0（事前）：ハンドオフモードの検出

ハンドオフモード、タスク ID、およびレビュー省略フラグを判定します。呼び出し元がプロンプト内で HANDOFF_MODE、HANDOFF_TASK_ID、HANDOFF_SKIP_REVIEW を明示的なテキストとして渡した場合は、それらの値を使用します。それ以外の場合は、Bash ツールを使用します。

Bash: printenv HANDOFF_MODE || true
Bash: printenv HANDOFF_TASK_ID || true
Bash: printenv HANDOFF_SKIP_REVIEW || true

次に HANDOFF_MODE を確認します。

HANDOFF_MODE が 1 の場合（自律型ハンドオフエージェント）

ハンドオフコーディネーターがステータス遷移と DB への書き込みを直接管理します。MCP ツールは呼び出さないでください。代わりに、次のようにします。

• 対話形式で質問しない： AskUserQuestion を使用しないでください。$ARGUMENTS に --plan-first が含まれている場合は、「計画優先」モードを使用します。それ以外の場合は、デフォルトの「即時修正」モードを使用します。バグにリグレッションチェックが必要な場合は、リグレッション優先の対応と記録を含めてください。
• 計画への注釈（必須）： HANDOFF_TASK_ID が空でない場合は、修正計画ファイルのタイトルより前、必ず最初の行に `` を挿入しなければなりません。**HANDOFF_TASK_ID が設定されているのにこの注釈を省略するのはバグです。完了前に確認してください。**これはステップ1.1（新しい計画の作成）と、あらゆる計画の書き直しの両方に適用されます。

HANDOFF_MODE が 1 ではない場合（手動の Claude Code セッション）

ハンドオフの同期はセッション内で処理します。タスク ID の抽出と MCP 同期のトリガーについては、修正計画ファイルを読み取った後の ステップ0.1 を参照してください。同期間のポイントは次のとおりです。

• 計画優先（ステップ1.1）： "planning" → "plan_ready"（保存後）
• 即時修正（ステップ2→5）： "implementing"（ステップ2の開始時）→ HANDOFF_SKIP_REVIEW=1 の場合は "done"、そうでなければ "review"（ステップ5）
• 既存計画の実行（ステップ0.1→5）： "implementing"（ステップ0.1）→ HANDOFF_SKIP_REVIEW=1 の場合は "done"、そうでなければ "review"（ステップ5）

重要： done を除き、すべての handoff_sync_status 呼び出しで必ず paused: true を渡してください。

新しい FIX_PLAN.md を作成する場合、既存の注釈もハンドオフコンテキストもなければ、注釈を追加しないでください。

ステップ 0：設定の読み込みとパスの解決

最初に: .ai-factory/config.yaml が存在する場合は読み込み、次の項目を解決します。

• パス: paths.description、paths.architecture、paths.rules_file、paths.rules、paths.research、paths.fix_plan、paths.patches。また、research_bundles_dir = <paths.research の親ディレクトリ>/research/ を導出します。
• 言語: プロンプトと要約には language.ui、FIX_PLAN.md とパッチ成果物には language.artifacts、成果物内の人が読む技術用語には language.technical_terms を使用します。
• ルール: rules.base と、名前付きの rules.<area> エントリーを使用します。

config.yaml が存在しない場合は、次のデフォルト値を使用します。

• DESCRIPTION.md: .ai-factory/DESCRIPTION.md
• ARCHITECTURE.md: .ai-factory/ARCHITECTURE.md
• RULES.md: .ai-factory/RULES.md
• rules/: .ai-factory/rules/
• RESEARCH.md: .ai-factory/RESEARCH.md
• FIX_PLAN.md: .ai-factory/FIX_PLAN.md
• patches/: .ai-factory/patches/
• ui_language: en
• artifact_language: en
• technical_terms_policy: keep

解決後の言語値：

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"

technical_terms_policy が keep、translate、mixed のいずれでもない場合は、keep として扱います。english などの旧形式の値も keep として扱います。

すべての AskUserQuestion プロンプト、進捗の更新、修正の要約、テストのプロンプト、次のステップの案内は、ui_language で記述する必要があります。

生成する FIX_PLAN.md と、paths.patches 配下の自己改善パッチファイルは、artifact_language で記述する必要があります。

テンプレートと例は構成を定めるものであり、英語での出力を固定するものではありません。artifact_language が en 以外の場合は、人が読む見出し、ラベル、分析テキスト、修正チェックリストの項目、リスク、予防に関する注記、パッチの説明文を翻訳してから保存します。Handoff 注釈、Markdown 構造、チェックボックスの構文、パス、コマンド、設定キー、コード識別子、パッケージ名、API 名、未加工のエラーメッセージ、コードスニペット、[FIX] などのログ接頭辞、パッチタグは変更しないでください。下流のリサーチ差分チェックで互換性トークンとして解析される ## Research Context、Source:、Active Summary、Updated:、SHA256: はそのまま保持してください。その他の人が読む用語には technical_terms_policy を適用してください。

ステップ 0.1：既存の修正計画を確認する

設定の解決後、ほかの何よりも先に、解決済みの修正計画パス（既定値：.ai-factory/FIX_PLAN.md）を確認します。

ファイルが存在する場合：

• 解決済みの修正計画ファイルを読み込みます
• 修正計画に ## Research Context が含まれている場合、その中に埋め込まれたコピーを確定済みの要件スナップショットとして扱います。最初の Source: / Reference: 行を、正規の ^(?:Source|Reference):\s+\x60([^\x60]+)\x60\s+\( 構文で解析します。以前の形式のパスのみの行については、^(?:Source|Reference):\s+(.+?)\s+\( をフォールバックとして使用します。どちらの形式でも使用可能なパスを特定できない場合に限り、設定済みの paths.research を使用します。
• 解析されたソースが research_bundles_dir 内にある場合、同じディレクトリにある INDEX.md に `` がちょうど1回含まれ、その RESEARCH.md が ## Artifact Index からリンクされていることを確認します。それ以外の場合は WARN [research-drift] を出力します。有効な同一ディレクトリ内の C4／ADR／依存関係アーティファクトは、根拠としてのみ扱います。
• SHA256: がある場合、現在のソーステキストを と の間から厳密に抽出し、HTML コメントブロックを削除して、行順と先頭の空白を保持し、すべての行末の空白を削除し、改行を LF に統一して、末尾を1つの改行で終わらせます。shasum -a 256 または sha256sum を使って標準入力からハッシュを計算します。このダイジェストを正とします。SHA256: がない場合に限り、Updated: をレガシー形式のフォールバックとして使用します。ソースが存在しない、または無効な場合や、リビジョンが一致しない場合は WARN [research-drift] を出力します。ユーザーが明示的にリベースを依頼しない限り、埋め込みの Research Context に基づいて実行します。
• 最初の行に `` があるか、直ちに確認します。
  • 見つかり、かつ HANDOFF_MODE が 1 ではない場合（手動セッション）：タスク ID を抽出します。handoff_sync_status を { taskId: <extracted-id>, newStatus: "implementing", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true } で呼び出します。（新しい計画を作成するのではなく、既存の計画に基づいて実行するため、ステータスは "implementing" です。）
  • 見つかり、かつ HANDOFF_MODE が 1 の場合：同期は Handoff コーディネーターが処理するため、何もしません。
  • 見つからない場合：リンクされた Handoff タスクはありません。このセッションの残りの間、すべての MCP 同期をスキップします。
• ユーザーに「既存の修正計画が見つかりました。計画に基づいて修正を実行します。」と伝えます。
• ステップ 1（問題の聞き取り／モード選択）をスキップしますが、コンテキストを読み込むため、ステップ 0.2 は実行します
• その後、計画をガイドとして使用し、ステップ 2：コードベースを調査するに進みます
• バグに回帰チェックが必要な場合は、既存の計画に方針が含まれていなくても、実装コードを変更する前に回帰優先の標準ポリシーを適用します
• 計画に沿って順番に進めますが、標準の順序を維持します。まず問題を確認し、修正を実装してから、同じ回帰チェックを再実行します
• ステップ 4 で修正を完全に適用して検証した後、解決済みの修正計画ファイルが既定の修正計画パス .ai-factory/FIX_PLAN.md である場合に限り、削除します：

  rm .ai-factory/FIX_PLAN.md
  

• 修正計画がカスタムの paths.fix_plan 値、明示的に指定されたカスタム計画パス、または既定以外の修正計画の場所にある場合は、削除しないでください。そのまま残し、最終サマリーでカスタム修正計画を保持したことを伝えます。
• ステップ 5（追加のテストカバレッジ）とステップ 6（パッチ）に進みます

ファイルが存在せず、かつ $ARGUMENTS が空の場合：

• ユーザーに「修正計画が見つからず、問題の説明もありません。バグの説明（/aif-fix <description>）を入力するか、先に修正計画を作成してください。」と伝えます。
• 停止します。

ファイルが存在せず、かつ $ARGUMENTS が指定されている場合：

• 以下のステップ 0.2 に進みます。

Step 0.2：プロジェクトのコンテキストと過去の経験を読み込む

次に： .ai-factory/DESCRIPTION.md（設定ファイルで指定されたパス）を読み、存在する場合は以下を把握します。

• 技術スタック（言語、フレームワーク、データベース）
• プロジェクトのアーキテクチャ
• コーディング規約

また、 .ai-factory/ARCHITECTURE.md（設定ファイルで指定されたパス）、解決済みの RULES.md のパス、および設定されたルール階層があれば、それらも読み、プロジェクトの構造やローカルの規約に違反する修正を避けてください。

.ai-factory/skill-context/aif-fix/SKILL.md を読みます — ファイルが存在する場合は必須です。

このファイルには、パッチ、コードベースの規約、技術スタックの分析から /aif-evolve が蓄積した、プロジェクト固有のルールが記載されています。これらのルールは現在のプロジェクトに合わせて調整されています。

skill-context ルールの適用方法：

• このスキルの一般的な指示に対するプロジェクトレベルの上書きとして扱います
• skill-context のルールが、この SKILL.md に記載された一般ルールと矛盾する場合は、skill-context のルールを優先します（より具体的なコンテキストを優先する原則です。ネストされた CLAUDE.md ファイルと同じ考え方です）
• 矛盾しない場合は、SKILL.md の一般ルールと skill-context のプロジェクトルールを両方適用します
• skill-context のルールがこのスキルの既定の指示に反しているように見えても、無視しないでください。プロジェクトでの経験から、既定の指示だけでは不十分だと判明したために存在するルールです
• 重要： skill-context のルールは、FIX_PLAN.md のテンプレートやパッチファイルを含め、このスキルのすべての出力に適用されます。Step 1.1 の FIX_PLAN.md テンプレートは基本構造です。skill-context のルールに「手順には X を含める必要がある」や「計画には Y のセクションが必要」とある場合は、テンプレートを必ず拡張してください。skill-context のルールに違反する FIX_PLAN.md やパッチを生成するのは不具合です。

遵守の確認： 出力成果物を生成した後は、必ずすべての skill-context ルールに照らして確認してください。違反があれば、ユーザーに提示する前に出力を修正してください。

パッチによる補完（skill-context がない場合に限る。対象範囲は限定）：

• .ai-factory/skill-context/aif-fix/SKILL.md が存在せず、解決済みのパッチディレクトリが存在する場合：
  • Glob を使用して、<resolved patches dir> 内の *.md ファイルを検索します
  • パッチのファイル名を辞書順に並べ、最後の10 件（10 件未満の場合はそのすべて）を選択します
  • 選択したパッチファイルのみを読みます
  • 繰り返し見られる根本原因と予防策のパターンを優先します
• skill-context が存在する場合、既定ではすべてのパッチを読み込まないでください。
  • タグやファイルが現在の不具合と明らかに一致する場合に限り、最近のパッチの一部を対象を絞って確認してもかまいません

Step 1：問題を理解し、モードを選択する

$ARGUMENTS から、以下を特定します。

• エラーメッセージまたは予期しない動作
• 発生箇所（ファイル、関数、エンドポイント）
• 再現手順（提示されている場合）

不明な点がある場合は、次のように質問します。

To fix this effectively, I need more context:

1. What is the expected behavior?
2. What actually happens?
3. Can you share the error message/stack trace?
4. When did this start happening?

問題を理解した後、AskUserQuestion を使用して、進め方をユーザーに選んでもらいます。

質問：「修正をどのように進めますか？」

選択肢：

1. すぐに修正 — 調査して、ただちに修正を適用します
2. 先に計画 — レビュー用の修正計画を作成し、その後で修正します

選択に応じて：

• 「先に計画」→ Step 1.1：修正計画の作成に進みます
• 「すぐに修正」→ Step 1.1 をスキップし、Step 2：コードベースを調査するに直接進みます

Step 1.1: 修正計画を作成する

Handoff の同期（手動モードのみ）： Handoff タスク ID が判明しており（HANDOFF_TASK_ID または既存の注釈から）、かつ HANDOFF_MODE が 1 ではない場合、handoff_sync_status を { taskId: <id>, newStatus: "planning", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true } で呼び出します。

問題を理解して計画を作成できる程度に、コードベースを調査します。

Step 2 と同じ並行調査アプローチを使用します。問題の領域、関連コード、過去のパターンを同時に調査する Explore エージェントを起動します。

解決済みの調査パスが存在する場合は、修正計画を作成する前に読み込みます。また、research_bundles_dir 直下のバンドルも確認します。ただし、INDEX.md に がちょうど 1 回だけ含まれ、`Status: active` が宣言され、`## Artifact Index` から `RESEARCH.md` へのリンクがある場合に限り、アクティブなものとして扱います。バグに明確に関連するソースを最大 1 つ選択します。選択順は、明示された具体的なパス、完全一致するスラッグ、正規化された `Topic:`、一意の意味的な一致、関連するレガシーファイルの順です。新しさを選択基準にしてはいけません。選択した Active Summary が計画した修正に影響する場合は、その内容を `## Research Context` にコピーし、Source: <selected research path> (Active Summary, Updated: , SHA256: )`` を含めます。調査内容が無関係な場合は、このセクションを省略します。

修正計画に ## Research Context を追加する場合は、ドリフトチェックと同じ正規化アルゴリズムを使用します。一時的なリポジトリアーティファクトを作成せず、正規化したテキストを標準入力またはインラインのシェル入力から shasum -a 256 に渡してダイジェストを計算します。使用できない場合は sha256sum を使います。出力の最初のフィールドを SHA256: として使用します。

エージェントからの応答後、調査結果を統合して以下を特定します。

1. 根本原因（または最も可能性の高い候補）
2. 影響を受けるファイルと関数
3. 影響範囲

解決済みの修正計画ファイルを作成します（既定値：.ai-factory/FIX_PLAN.md）。

修正計画は artifact_language で記述します。以下のテンプレートは必須の構造のみを示しています。artifact_language が en 以外の場合は、Step 0 の安定した技術トークンを保持したまま、保存前に人が読む見出し、ラベル、本文を翻訳します。

書き込む前に： HANDOFF_MODE が 1 で、HANDOFF_TASK_ID が空でない場合、ファイルの最初の行は `` とし、その後に空行を 1 行入れて、以下の計画内容を続けます。手動モードで既存の注釈からタスク ID を抽出した場合は、その ID を保持します。

構造：

# Fix Plan: [Brief title]

**Problem:** [What's broken — from user's description]
**Created:** YYYY-MM-DD HH:mm

## Analysis

What was found during investigation:

- Root cause (or suspected root cause)
- Affected files and functions
- Impact scope

## Fix Checklist

Checklist entries for implementing the fix:

1. [ ] Apply the Canonical Regression-First Policy: add or identify the minimal regression check, or record why no useful check exists
2. [ ] Run the regression check and confirm it reproduces the reported problem, or record the fallback outcome from the policy
3. [ ] Implement the smallest fix for the root cause
4. [ ] Rerun the same regression check and confirm it passes when a rerunnable check exists
5. [ ] Run the closest related existing checks when practical

## Files to Modify

- `path/to/file.ts` — what changes are needed
- `path/to/another.ts` — what changes are needed

## Risks & Considerations

- Potential side effects
- Things to verify after the fix
- Edge cases to watch for

## Test Coverage

- Minimal regression check to confirm the bug before implementation
- Command/check to run before and after the fix
- Additional edge cases worth covering after the regression check passes

## Research Context (optional)

Include only when this fix plan is based on `RESEARCH.md`.
Source: `<selected research path>` (Active Summary, Updated: YYYY-MM-DD HH:MM, SHA256: <active-summary-sha256>)

SHA256: を記入する際は、Step 1.1 の正規化と標準入力によるハッシュ計算のルールを使用します。

計画の作成後、次を出力します。

## Fix Plan Created ✅

Plan saved to the resolved fix plan path.

Review the plan and when you're ready to execute, run:

/aif-fix

Handoff の同期（手動モードのみ）： Handoff タスク ID が判明しており、かつ HANDOFF_MODE が 1 ではない場合、handoff_push_plan を { taskId: <id>, planContent: <full fix plan text> } で呼び出し、続けて handoff_sync_status を { taskId: <id>, newStatus: "plan_ready", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true } で呼び出します。

ここで停止してください。修正を適用してはいけません。

Step 2: コードベースを調査する

Handoff の同期（手動モードの「今すぐ修正」経路のみ）： Handoff タスク ID が判明しており、かつ HANDOFF_MODE が 1 ではない場合、handoff_sync_status を { taskId: <id>, newStatus: "implementing", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true } で呼び出します。

問題を並行して調査するには、subagent_type: Explore を指定して Task ツールを使用します。 これによりメインコンテキストを整理し、複数の観点を同時に調査できます。

Explore エージェントを 2～3 個、同時に起動します。

Agent 1 — Locate the problem area:
Task(subagent_type: Explore, model: sonnet, prompt:
  "Find code related to [error location / affected functionality].
   Read the relevant functions, trace the data flow.
   Thoroughness: medium.")

Agent 2 — Related code & side effects:
Task(subagent_type: Explore, model: sonnet, prompt:
  "Find all callers/consumers of [affected function/module].
   Identify what else might break or be affected.
   Thoroughness: medium.")

Agent 3 — Similar past patterns (if patches exist):
Task(subagent_type: Explore, model: sonnet, prompt:
  "Search for similar error patterns or related fixes in the codebase.
   Check git log for recent changes to [affected files].
   Thoroughness: quick.")

エージェントからの応答後、調査結果を統合して以下を特定します。

• 根本原因（症状だけではありません）
• 影響を受ける可能性のある関連コード
• 既存のエラー処理

代替手段： Task ツールを利用できない場合は、直接調査します。

• Glob/Grep を使って関連ファイルを検索します
• 問題の周辺のコードを読みます
• データフローを追跡します
• 他の箇所に類似したパターンがないか確認します

ステップ 2.5：リグレッションチェックを作成する

実装コードを変更する前に、標準リグレッション優先ポリシーを適用してください。動作のバグ、解析／検証のバグ、API／データのバグ、クラッシュ、リグレッションには、リグレッションチェックを優先してください。バグ修正ではない整理、純粋な静的修正、または調査のみの依頼の場合は、ポリシーが適用されない理由を記録し、通常の修正ワークフローを続けてください。

不正なテスト作成の禁止： これから実装する内容に合わせてテストを調整しないでください。テストでは、外部から期待される動作、または報告された障害条件を記述する必要があります。修正前にテストが成功した場合、再現方法が誤っている、バグがすでに存在しない、または環境が異なる可能性があります。実装コードを変更する前に、標準リグレッション優先ポリシーのフォールバック動作に従って、その不一致に対処してください。

選択したリグレッションチェック、修正前の結果、フォールバックに関する判断を作業メモに記録し、ステップ 4 で同じチェックを再実行または再確認できるようにしてください。

ステップ 3：修正を実装する

ログを追加して修正を適用してください：

// ✅ REQUIRED: Add logging around the fix
console.log("[FIX] Processing user input", { userId, input });

try {
  // The actual fix
  const result = fixedLogic(input);
  console.log("[FIX] Success", { userId, result });
  return result;
} catch (error) {
  console.error("[FIX] Error in fixedLogic", {
    userId,
    input,
    error: error.message,
    stack: error.stack,
  });
  throw error;
}

ログ出力は必須です。理由は次のとおりです：

• ユーザーが修正の動作を確認する必要があります
• 動作しない場合、ログがさらなるデバッグに役立ちます
• フィードバックループ：ユーザーがログを提供し、こちらが修正を重ねます

ステップ 4：修正を検証する

• コードがコンパイル／実行できることを確認します
• ステップ 2.5 でリグレッションチェックを作成、特定、または文書化した場合、同じチェックを再実行または再確認し、修正後の動作を確認します
• ロジックが正しいことを検証します
• リグレッションが発生していないことを確認します
• 実行可能な場合は、リグレッションチェックが成功した後に、最も関連性の高い既存のテストスイートを実行します

ステップ 5：追加のテストカバレッジを提案する

ハンドオフ同期（手動モードのみ — HANDOFF_MODE が 1 の場合は完全にスキップ）： Handoff のタスク ID が判明しており、かつ HANDOFF_MODE が 1 ではない場合：

1. { taskId: <id>, planContent: <fix summary or updated plan> } を指定して handoff_push_plan を呼び出します。
2. HANDOFF_SKIP_REVIEW が 1 の場合：{ taskId: <id>, newStatus: "done", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: false } を指定して handoff_sync_status を呼び出します。
3. それ以外の場合：{ taskId: <id>, newStatus: "review", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true } を指定して handoff_sync_status を呼び出します。

必ず追加のテストカバレッジを提案してください：

ステップ 5 と修正後の出力テンプレートでは、構成のみを定義します。これらのユーザー向け応答に含まれる、人が読むすべてのテキストは ui_language で出力してください。コードスニペット、コマンド、ファイルパス、行番号、[FIX] などのログプレフィックス、AskUserQuestion の選択肢の構造は変更しないでください。

## Fix Applied ✅

The issue was: [brief explanation]
Fixed by: [what was changed]

### Logging Added
The fix includes logging with prefix `[FIX]`.
Please test and share any logs if issues persist.

### Recommended: Add More Test Coverage

If a regression check was created or identified in Step 2.5, this bug is now covered. Consider adding broader coverage to prevent nearby regressions:

\`\`\`typescript
describe('functionName', () => {
  it('should handle [the edge case that caused the bug]', () => {
    // Arrange
    const input = /* the problematic input */;

    // Act
    const result = functionName(input);

    // Assert
    expect(result).toBe(/* expected */);
  });
});
\`\`\`

AskUserQuestion: Would you like me to create the additional test coverage?

Options:
1. Yes, create the test
2. No, skip for now

ユーザーの応答への対応：

• 「はい、テストを作成する」の場合：

  1. 適切なテストディレクトリにテストファイルを作成します（プロジェクトの規約に従ってください）
  2. 提案した追加のテストケースと関連するエッジケースを含めます
  3. テストを実行し、成功することを確認します
  4. その後、ステップ 6：自己改善パッチを作成するに進みます

• 「いいえ、今回はスキップする」の場合：

  • 直接ステップ 6：自己改善パッチを作成するに進みます

ログの要件

すべての修正にログ出力を含める必要があります：

1. ログプレフィックス： フィルタリングしやすいように、[FIX] または [FIX:<issue-id>] を使用します
2. 入力を記録する： 処理対象のデータを記録します
3. 成功を記録する： 修正が機能したことを確認します
4. エラーを記録する： 失敗した場合は、完全なコンテキストを記録します
5. 設定可能にする： 利用可能な場合は LOG_LEVEL を使用します

// Pattern for fixes
const LOG_FIX = process.env.LOG_LEVEL === "debug" || process.env.DEBUG_FIX;

function fixedFunction(input) {
  if (LOG_FIX) console.log("[FIX] Input:", input);

  // ... fix logic ...

  if (LOG_FIX) console.log("[FIX] Output:", result);
  return result;
}

例

例 1：Null 参照エラー

ユーザー： /aif-fix TypeError: Cannot read property 'name' of undefined in UserProfile

アクション：

1. UserProfile コンポーネント／関数を検索します
2. .name にアクセスしている箇所を見つけます
3. null のユーザーケースに対するリグレッションチェックを追加し、失敗することを確認します
4. ログ出力を含めて null チェックを追加します
5. 同じリグレッションチェックを再実行し、成功することを確認します

例 2：API が誤ったデータを返す

ユーザー： /aif-fix /api/orders returns empty array for authenticated users

アクション：

1. 注文 API のエンドポイントを見つけます
2. クエリのロジックを追跡します
3. バグ（誤ったフィルターなど）を見つけます
4. 認証済みユーザーのケースに対する統合回帰チェックを追加するか、既存のものを特定し、失敗することを確認します
5. ログを追加して修正します
6. 同じ回帰チェックを再実行し、成功することを確認します

例 3：フォームのバリデーションが機能しない

ユーザー： /aif-fix email validation accepts invalid emails

アクション：

1. メールアドレスのバリデーションロジックを見つけます
2. 正規表現またはバリデーションライブラリの使用方法を確認します
3. 無効なメールアドレスのケースに対する単体回帰テストを追加し、失敗することを確認します
4. バリデーションを修正します
5. バリデーション失敗時のログを追加します
6. 同じ回帰テストを再実行し、成功することを確認します

重要なルール

1. 最初に修正計画を確認する - 何よりも先に、解決済みの修正計画のパスを必ず確認します
2. 計画モード = 計画のみ - ユーザーが「最初に計画」を選択した場合、計画を作成して停止します。修正はしません
3. 実行モード = 計画に従う - 解決済みの修正計画が存在する場合は、手順に従って実行します。検証済みの実行後、デフォルトの .ai-factory/FIX_PLAN.md である場合に限り削除し、カスタムまたはデフォルト以外の修正計画ファイルは保持します
4. レポートを作成しない - 要約ドキュメントは作成しません（パッチは学習用の成果物であり、レポートではありません）
5. 必ずログを記録する - すべての修正に、フィードバック用のログを記録します
6. 必要な場合は回帰チェックを優先する - バグに回帰テストが必要な場合は、実装コードを変更する前に Canonical Regression-First Policy に従います。再現可能な場合は問題を確認し、修正後に同じ回帰チェックを実施して検証します
7. 実装に合わせてテストを作らない - 回帰テストでは内部実装の形ではなく、報告された動作や期待される動作を定義します
8. 必ず追加のテストを提案する - 必須の回帰チェックに加え、関連する回帰の予防に役立てます
9. 根本原因 - 症状ではなく、実際の問題を修正します
10. 変更は最小限にする - 無関係なコードはリファクタリングしません
11. 一度に一つの修正を行う - 対象範囲を広げません
12. クリーンアップする - 修正の実行が成功した後、解決済みの修正計画ファイルを削除します
13. 所有範囲の境界 - /aif-fix が所有するのは paths.fix_plan と paths.patches です。ユーザーから明示的な依頼がない限り、.ai-factory/DESCRIPTION.md、ロードマップ、ルール、アーキテクチャのコンテキスト成果物は読み取り専用として扱います
14. ログの範囲 - 修正には [FIX] ログの要件を適用します。このコマンド内のコンテキストゲート出力には WARN／ERROR を使用し、他のスキルのグローバルなログポリシーは変更しません

修正後

追加テストについて AskUserQuestion を行う前に、ステップ 5 でこの出力テンプレートを使用します

## Fix Applied ✅

**Issue:** [what was broken]
**Cause:** [why it was broken]
**Fix:** [what was changed]
**Regression check:** [command/check and result, manual/runtime reproduction result, or "not available: <reason>"]

**Files modified:**
- path/to/file.ts (line X)

**Logging added:** Yes, prefix `[FIX]`

ステップ 6：自己改善パッチを作成する

修正のたびに必ずパッチを作成します。 これにより、今後の修正に役立つナレッジベースを構築できます。

パッチを作成する：

1. 存在しない場合はディレクトリを作成します：

   mkdir -p <resolved patches dir>
   

2. 現在のタイムスタンプをファイル名にして、パッチファイルを作成します。 形式： YYYY-MM-DD-HH.mm.md（例：2026-02-07-14.30.md）

3. 次のテンプレートを使用します：

artifact_language でパッチ成果物を記述します。以下のテンプレートは必須の構成のみを示しています。artifact_language が en 以外の場合は、Step 0 の安定した技術トークンを保持したうえで、保存前に人が読む見出し、ラベル、根本原因、解決策、予防策を翻訳します。

# [Brief title describing the fix]

**Date:** YYYY-MM-DD HH:mm
**Files:** list of modified files
**Severity:** low | medium | high | critical

## Problem

What was broken. How it manifested (error message, wrong behavior).
Be specific — include the actual error or symptom.

## Root Cause

WHY the problem occurred. This is the most valuable part.
Not "what was wrong" but "why it was wrong":

- Logic error? Why was the logic incorrect?
- Missing check? Why was it missing?
- Wrong assumption? What was assumed?
- Race condition? What sequence caused it?

## Solution

How the fix was implemented. Key code changes and reasoning.
Include the approach, not just "changed line X".

## Prevention

How to prevent this class of problems in the future:

- What pattern/practice should be followed?
- What should be checked during code review?
- What test would catch this?

## Tags

Space-separated tags for categorization, e.g.:
`#null-check` `#async` `#validation` `#typescript` `#api` `#database`

パッチの例：

# Null reference in UserProfile when user has no avatar

**Date:** 2026-02-07 14:30
**Files:** src/components/UserProfile.tsx
**Severity:** medium

## Problem

TypeError: Cannot read property 'url' of undefined when rendering
UserProfile for users without an uploaded avatar.

## Root Cause

The `user.avatar` field is optional in the database schema but the
component accessed `user.avatar.url` without a null check. This was
introduced in commit abc123 when avatar display was added — the
developer tested only with users that had avatars.

## Solution

Added optional chaining: `user.avatar?.url` with a fallback to a
default avatar URL. Also added a null check in the Avatar sub-component.

## Prevention

- Always check if database fields marked as `nullable` / `optional`
  are handled with null checks in the UI layer
- Add test cases for "empty state" — user with minimal data
- Consider a lint rule for accessing nested optional properties

## Tags

`#null-check` `#react` `#optional-field` `#typescript`

これは任意ではありません。 すべての修正でパッチを生成します。パッチは学習のためのものです。

コンテキストのクリーンアップ

必要に応じてコンテキスト領域を解放するようユーザーに提案します: /clear（完全リセット）または /compact（履歴を圧縮）。

---

やってはいけないこと:

• ❌ ユーザーが「まず計画」を選んだ場合に修正を適用する - 修正計画を作成するだけで停止します
• ❌ 開始時の修正計画チェックをスキップする
• ❌ 修正の実行が成功した後にデフォルトの .ai-factory/FIX_PLAN.md を残す
• ❌ 実行後にカスタム/非デフォルトの修正計画ファイルを削除する
• ❌ レポートやサマリーを生成する（パッチはレポートではありません — それらは学習成果物です）
• ❌ 無関係なコードをリファクタリングする
• ❌ 修正中に機能を追加する
• ❌ ログ記録をスキップする
• ❌ テストの提案をスキップする
• ❌ パッチの作成をスキップする