---

name: verify-first-debugging description: 【必須】バグ修正時は常にこのフレームワークを使用すること。仮説より先に確認を積み上げ、根本原因から修正する6 Phase体系。

VERIFY-FIRST Debugging Framework

目的: 安易な修正を防ぎ、根本原因から確実にバグを修正する思考フレームワーク

このSkillは、brainbaseで過去に発生した11ケースの実バグから抽出した「確認積み上げ型」のデバッグ手法を体系化したものです。

Core Principle

「仮説を出す前にまず何が正しいのか、どこからが間違っているのかというその分離をする」 — 佐藤圭吾, 2025-12-31 Settings Modalデバッグセッションより

ベテランと新人の差（思考の外付け化）

ベテラン開発者の思考:

1. まず期待値を明確化
2. 各コンポーネントの実際の動作を確認
3. 期待と実際のギャップを積み上げる
4. 確認した事実から根本原因を特定
5. 根本から修正

新人開発者の思考（アンチパターン）:

1. ❌ 「CSSに定義がある → HTMLにもあるだろう」と推測
2. ❌ 表面的な症状だけ見て安易に修正
3. ❌ 確認せずに変更を重ねる
4. ❌ なぜ直らないのか深掘りしない
5. ❌ 同じ箇所を何度も触る

→ VERIFY-FIRST Frameworkでベテランの思考を再現

Framework Overview

CopyPhase 1: REPRODUCE & DEFINE EXPECTED
  └── 期待値を明確化
  └── 再現手順を確立

Phase 2: LOCATE AFFECTED COMPONENTS
  └── 影響範囲を特定
  └── 関連ファイル・関数を列挙

Phase 3: VERIFY COMPONENT RELATIONSHIPS
  ├── 3A: UI Bugs → HTML/CSS/PARENT CONSISTENCY
  ├── 3B: Runtime Errors → VARIABLE LIFECYCLE
  ├── 3C: Logic/Data → DATA FLOW
  ├── 3D: Infrastructure → DATA ARCHITECTURE
  ├── 3E: Refactoring → CODE-TEST SYNC
  ├── 3F: Config → CONFIG PROCESSING
  ├── 3G: AWS/Infrastructure → DEPLOYMENT OPERATIONS
  │   ├── 3G-1: CLI Command Syntax
  │   ├── 3G-2: Deployment Workflow Safety
  │   └── 3G-3: Infrastructure State Consistency
  └── 3H: Security → THREAT CONTAINMENT

Phase 4: VERIFY PREREQUISITES
  └── 前提条件を確認
  └── 依存関係を検証

Phase 5: IDENTIFY ROOT CAUSE (from confirmed facts)
  └── 確認した事実から根本原因を特定
  └── 仮説ではなく確認済み事実ベース

Phase 6: FIX AT ROOT
  └── 根本原因から修正
  └── 表面的な対処療法を避ける

---

Orchestrator Responsibilities

このSkillはOrchestrator Skillとして動作し、6つのPhaseを管理し、各PhaseでSubAgentを起動します。

Phase Management

6つのPhaseを順次実行:

1. Phase 1: REPRODUCE & DEFINE EXPECTED (agents/phase1_reproduce.md)
2. Phase 2: LOCATE AFFECTED COMPONENTS (agents/phase2_locate.md)
3. Phase 3: VERIFY COMPONENT RELATIONSHIPS (バグタイプに応じて3-5個のSubAgentを選択的に並列実行)
   • agents/phase3a_ui_consistency.md (UI Bugs)
   • agents/phase3b_variable_lifecycle.md (Runtime Errors)
   • agents/phase3c_data_flow.md (Logic/Data)
   • agents/phase3d_data_architecture.md (Infrastructure)
   • agents/phase3e_code_test_sync.md (Refactoring)
   • agents/phase3f_config_processing.md (Config)
   • agents/phase3g_deployment_operations.md (AWS/Infrastructure)
   • agents/phase3h_threat_containment.md (Security)
4. Phase 4: VERIFY PREREQUISITES (agents/phase4_prerequisites.md)
5. Phase 5: IDENTIFY ROOT CAUSE (agents/phase5_root_cause.md, opus model使用)
6. Phase 6: FIX AT ROOT (agents/phase6_fix.md)

Phase間のデータ受け渡し:

• Phase 1成果物 → Phase 2入力: 期待動作、再現手順
• Phase 2成果物 → Phase 3入力: 影響範囲、関連ファイル、エラーメッセージ
• Phase 3成果物 → Phase 4入力: 構造的不整合、検証結果
• Phase 4成果物 → Phase 5入力: 前提条件の充足状況
• Phase 5成果物 → Phase 6入力: 根本原因、Why×3の結果

Review & Replan Logic

各Phase完了後、Orchestratorが成果物をレビューし、必要に応じてリプランを実行します。

Review実施の4ステップ

Step 1: ファイル存在確認

Copytarget:
  - 成果物ファイルの存在確認
  - 空ファイルでないことの確認
  - 最終更新時刻がPhase開始時刻以降であることの確認

criteria:
  - file exists AND not empty
  - last_modified >= phase_start_time

判定:
  - ✅ PASS: 全ファイルが存在し、空でない
  - ❌ FAIL: ファイル不在 or 空ファイル → リプラン（Critical）

Step 2: Success Criteriaチェック

Copytarget:
  - 各PhaseのSuccess Criteriaが定義されているか
  - 各Criteriaが達成されているか

criteria:
  - Phase 1: [✅] 期待動作が1文で明確 (expected: YES, actual: ?)
  - Phase 1: [✅] 100%再現手順がある (expected: YES, actual: ?)
  - Phase 2: [✅] ファイル名・行番号を特定 (expected: YES, actual: ?)
  - Phase 3: [✅] バグタイプに応じた検証を実施 (expected: YES, actual: ?)
  - Phase 4: [✅] 前提条件を確認 (expected: YES, actual: ?)
  - Phase 5: [✅] Why×3を実施 (expected: YES, actual: ?)
  - Phase 6: [✅] 根本原因から修正 (expected: YES, actual: ?)

判定:
  - ✅ PASS: 全Success Criteriaを満たす
  - ⚠️ MINOR: 一部Criteriaを満たさない（警告+進行許可）
  - ❌ CRITICAL: 重要Criteriaを満たさない → リプラン必須

Step 3: 差分分析（要件との整合性）

Copytarget:
  - 期待値（要件・設計）vs 実際（成果物）の差分
  - VERIFY-FIRST基準への準拠

criteria:
  - Phase 1: 期待動作は1文で書けているか → [✅/❌]
  - Phase 2: git blame実施済みか → [✅/❌]
  - Phase 3: 適用ケースと実際のバグタイプが一致しているか → [✅/❌]
  - Phase 5: 仮説ではなく確認済み事実ベースか → [✅/❌]
  - Phase 6: 根本原因に対する修正か → [✅/❌]

判定:
  - ✅ PASS: 差分なし or 許容範囲内
  - ⚠️ MINOR: 軽微な差分（記録して進行）
  - ❌ CRITICAL: 重大な差分 → リプラン必須

Step 4: リスク判定とアクション決定

Copyリスクレベル:
  - Critical: 要件を満たさない、次Phaseの実行が不可能
  - Minor: 改善余地あり、次Phaseは実行可能
  - None: 問題なし

アクション:
  - Critical → リプラン実行（Subagentへ修正指示）
  - Minor → 警告記録 + 次Phaseへ進行
  - None → 承認 + 次Phaseへ進行

Replan実行フロー

Copy1. Issue Detection（問題検出）
   - Success Criteriaの不合格項目を特定
   - 差分の詳細化（期待値 vs 実際）
   - リスクレベルの判定（Critical/Minor/None）

2. Feedback Generation（フィードバック生成）
   - 何が要件と異なるか（差分の明示化）
   - どう修正すべきか（修正方向の提示）
   - 修正チェックリストの作成（具体的なタスク化）

3. Replan Prompt Creation（リプランプロンプト作成）
   - 元のタスク + フィードバック
   - Success Criteriaの再定義（修正後の期待値）
   - 修正実装のガイドライン

4. Subagent Re-execution（Subagent再実行）
   - Task Tool経由で同じSubagentを再起動
   - リプランプロンプトを入力
   - 修正成果物を取得

5. Re-Review（再レビュー）
   - 修正成果物を同じ基準で再評価
   - PASS → 次Phaseへ
   - FAIL → リトライカウント確認
     - リトライ < Max (3回) → ステップ1へ戻る
     - リトライ >= Max → 人間へエスカレーション

Error Handling

Phase実行失敗時のフォールバック:

CopyCase A: SubAgent起動失敗
  - 原因: Task Tool エラー、タイムアウト
  - 対処: 30秒待機後、再試行（最大3回）
  - 失敗時: 人間へエスカレーション

Case B: 成果物不足
  - 原因: 必要な情報が不足
  - 対処: AskUserQuestionで追加情報を取得
  - 例: "バグの再現手順を教えてください"

Case C: バグタイプ判定不能
  - 原因: Phase 2で影響範囲を特定できない
  - 対処: 全8つのSubAgentを順次実行（フォールバック）
  - 注: 並列実行はリスクが高いため、順次実行

Max Retries超過時のエスカレーション:

Copy条件:
  - リプラン実行回数が3回を超過
  - 同じCritical判定が繰り返し発生

アクション:
  1. 現在までの成果物を保存（/tmp/verify-first-bugs/{BUG_ID}/）
  2. ユーザーに状況を報告
     - どのPhaseで失敗したか
     - 何を試したか（リプラン履歴）
     - どの情報が不足しているか
  3. ユーザーの判断を仰ぐ
     - 手動で修正する
     - 追加情報を提供してリトライ
     - VERIFY-FIRSTをスキップして直接修正

Parallel Execution (Phase 3)

Phase 3では、バグタイプに応じて3-5個のSubAgentを選択的に並列実行します。

バグタイプ選択ロジック

CopyPhase 2の結果を分析:
  - 影響範囲（HTML/CSS/JS/Config/AWS/Security等）
  - エラーメッセージのパターン
    - undefined, null reference → 3B (Variable Lifecycle)
    - layout, overflow, display → 3A (UI Consistency)
    - API error, AWS CLI → 3G (Deployment Operations)
    - Malware, security → 3H (Threat Containment)
  - 最終変更履歴（git blame結果）
    - リファクタリング直後 → 3E (Code-Test Sync)
    - 設定ファイル変更 → 3F (Config Processing)

関連度スコアリング（0-10点）:
  - 影響範囲が一致: +5点
  - エラーパターンが一致: +3点
  - git blame履歴が一致: +2点

上位3-5個のバグタイプを選択:
  - 例: UIバグ（HTML/CSS影響）
    → 3A (10点), 3F (5点), 3B (2点) を選択
  - 例: Runtime Error（undefined）
    → 3B (10点), 3C (8点), 3D (3点) を選択

並列実行戦略

Copy1. Phase 2完了後、バグタイプ選択ロジックを実行
   - 上位3-5個のSubAgentを選択

2. 選択されたSubAgentを並列起動
   - Task Tool で同時に起動（Promise.allSettled pattern）
   - 各SubAgentに30秒タイムアウト設定
   - 成果物は /tmp/verify-first-bugs/{BUG_ID}/phase3_{type}.md に保存

3. 結果集約
   - 全SubAgentの結果を収集
   - Critical判定があるか確認
   - 失敗したSubAgentは無視（Promise.allSettledのため）

4. 2段階検証（必要に応じて）
   - 1回目の結果でCritical判定なし
   - 残りのバグタイプから追加で2-3個選択
   - 再度並列実行
   - 最大でも5-6個の実行に留める（システムロックアップ防止）

5. Phase 4へ進行
   - Critical判定があったバグタイプの結果を優先
   - 構造的不整合、検証結果をPhase 4へ引き継ぎ

並列実行の制限理由

Copy制限事項:
  - Claude Codeの並列タスク上限: 10個
  - 各SubAgentのトークンオーバーヘッド: ~20,000トークン
  - 24個並列実行時のシステムロックアップリスク

選択的並列実行のメリット:
  - リソース効率: 8個全部（160,000トークン）→ 3-5個（60,000-100,000トークン）で60-80%削減
  - 実行時間: 30秒以内（タイムアウト設定）
  - 安定性: システムロックアップリスク低減

フォールバック:
  - バグタイプ判定不能 → 全8個を順次実行（並列はリスク高）
  - タイムアウト発生 → 該当SubAgentをスキップして継続

---

Workflow Overview

このセクションでは、各Phaseの入力・出力・Success Criteriaを詳細に定義します。

Phase 1: REPRODUCE & DEFINE EXPECTED

SubAgent: agents/phase1_reproduce.md

目的: 「あるべき姿」と「再現手順」を明確化し、次Phase以降の基礎を確立する

Input（入力）:

Copyfrom_user:
  - bug_description: バグの簡易説明（ユーザーからの初期報告）
  - reproduction_steps_hint: 再現手順のヒント（任意）
  - expected_behavior_hint: 期待動作のヒント（任意）

from_orchestrator:
  - bug_id: BUG-XXX形式のID
  - work_dir: /tmp/verify-first-bugs/{BUG_ID}/

Process（処理）:

Copy1. バグの期待動作を明確化
   - ユーザーの報告から「あるべき姿」を抽出
   - 1文で書けるレベルまで具体化
   - 曖昧な表現（「速く」「きれいに」等）を定量化

2. 100%再現手順を確立
   - ステップごとに記述
   - 環境要因（ブラウザキャッシュ、サーバー再起動等）を排除
   - 期待結果と実際の結果を対比

3. 成果物を保存
   - {work_dir}/phase1_reproduce.md に保存
   - 期待動作、再現手順、実際の結果を記載

Output（出力）:

Copydeliverable:
  - file: {work_dir}/phase1_reproduce.md
  - content:
      - expected_behavior: 期待動作（1文）
      - reproduction_steps: 再現手順（ステップごと）
      - actual_result: 実際の結果（期待との差分）
      - environment: 実行環境（ブラウザ、OS、バージョン等）

to_next_phase:
  - expected_behavior: Phase 2で影響範囲を特定する際の基準
  - reproduction_steps: Phase 2でブラウザDevTools等で確認する手順

Success Criteria（成功基準）:

Copymandatory:
  - SC-1: 期待動作が1文で明確に書かれている
  - SC-2: 100%再現する手順が存在する
  - SC-3: 期待結果と実際の結果が対比されている

optional:
  - SC-4: 環境要因が排除されている（キャッシュクリア等実施済み）
  - SC-5: 再現率が明記されている（100%、80%等）

---

Phase 2: LOCATE AFFECTED COMPONENTS

SubAgent: agents/phase2_locate.md

目的: 問題が発生している具体的な場所（ファイル・関数・行番号）を特定する

Input（入力）:

Copyfrom_phase1:
  - expected_behavior: 期待動作
  - reproduction_steps: 再現手順
  - actual_result: 実際の結果

from_orchestrator:
  - bug_id: BUG-XXX
  - work_dir: /tmp/verify-first-bugs/{BUG_ID}/

Process（処理）:

Copy1. エラーメッセージからファイル名・行番号を特定
   - ブラウザConsoleのエラースタックトレース
   - サーバーログのエラーメッセージ
   - ネットワークタブのHTTPエラー

2. ブラウザDevToolsで該当DOM要素を特定
   - Elements タブで要素検査
   - CSS定義の確認
   - HTML構造の確認

3. git blameで最終変更者・コミットを確認
   - いつ、誰が、何を変更したか
   - 変更の意図（コミットメッセージ）
   - 関連する変更（前後のコミット）

4. 影響範囲の特定
   - HTML/CSS/JS/Config/AWS/Security のどれに該当するか
   - エラーメッセージのパターン分類
   - 関連ファイルの列挙

5. 成果物を保存
   - {work_dir}/phase2_locate.md に保存

Output（出力）:

Copydeliverable:
  - file: {work_dir}/phase2_locate.md
  - content:
      - affected_files: 影響を受けているファイル一覧（パス、行番号）
      - error_messages: エラーメッセージ一覧（コンソール、ログ等）
      - git_blame_result: git blame結果（最終変更者、コミットID、日時）
      - impact_scope: 影響範囲（HTML/CSS/JS/Config/AWS/Security）
      - error_pattern: エラーパターン（undefined/layout/API error等）

to_next_phase:
  - impact_scope: Phase 3でバグタイプを選択する際の基準
  - error_pattern: Phase 3でバグタイプを選択する際の基準
  - git_blame_result: Phase 3でバグタイプを選択する際の基準
  - affected_files: Phase 3で検証対象とするファイル

Success Criteria（成功基準）:

Copymandatory:
  - SC-1: ファイル名・行番号が特定されている
  - SC-2: 影響範囲（HTML/CSS/JS等）が分類されている
  - SC-3: エラーメッセージが記録されている

optional:
  - SC-4: git blame結果が記録されている
  - SC-5: 関連ファイルが列挙されている（5ファイル程度）

---

Phase 3: VERIFY COMPONENT RELATIONSHIPS（選択的並列実行）

SubAgents: agents/phase3{a-h}_*.md（8ファイル、実行時は3-5個を選択）

目的: バグタイプに応じた検証を実施し、構造的不整合を検出する

Phase 3 共通仕様

Input（入力）:

Copyfrom_phase2:
  - affected_files: 影響を受けているファイル一覧
  - error_messages: エラーメッセージ一覧
  - git_blame_result: git blame結果
  - impact_scope: 影響範囲
  - error_pattern: エラーパターン

from_orchestrator:
  - bug_id: BUG-XXX
  - work_dir: /tmp/verify-first-bugs/{BUG_ID}/
  - selected_bug_type: 3A | 3B | 3C | 3D | 3E | 3F | 3G | 3H

Process（処理）:

Copy1. バグタイプ選択ロジック（Orchestratorが実行）
   - Phase 2の結果を分析（impact_scope, error_pattern, git_blame_result）
   - 関連度スコアリング（0-10点）
     - 影響範囲が一致: +5点
     - エラーパターンが一致: +3点
     - git blame履歴が一致: +2点
   - 上位3-5個のバグタイプを選択

2. 選択されたSubAgentを並列起動
   - Task Tool で同時起動（Promise.allSettled pattern）
   - 各SubAgentに30秒タイムアウト設定

3. 各SubAgentが検証を実施
   - バグタイプに応じた検証項目をチェック
   - 構造的不整合を検出
   - Critical判定（要修正）/ Minor判定（警告）/ None判定（問題なし）

4. 結果集約（Orchestratorが実行）
   - 全SubAgentの結果を収集
   - Critical判定があるか確認
   - Critical判定があったSubAgentの結果を優先

5. 2段階検証（必要に応じて）
   - 1回目の結果でCritical判定なし
   - 残りのバグタイプから追加で2-3個選択
   - 再度並列実行
   - 最大でも5-6個の実行に留める

6. 成果物を保存
   - {work_dir}/phase3_{type}.md に保存（選択された各バグタイプ）
   - {work_dir}/phase3_summary.md に統合結果を保存

Output（出力）:

Copydeliverable:
  - files:
      - {work_dir}/phase3_summary.md: 統合結果
      - {work_dir}/phase3_{type}.md: 各バグタイプの検証結果
  - content:
      - bug_type: 適用したバグタイプ（3A-3H）
      - verification_result: 検証結果（Critical/Minor/None）
      - structural_inconsistencies: 構造的不整合の詳細
      - evidence: 検証の根拠（grep結果、ファイル内容等）

to_next_phase:
  - verification_result: Phase 4で前提条件を確認する際の基準
  - structural_inconsistencies: Phase 5で根本原因を特定する際の材料

Success Criteria（成功基準）:

Copymandatory:
  - SC-1: 3-5個のバグタイプで検証が実施されている
  - SC-2: 各バグタイプの検証結果（Critical/Minor/None）が明確
  - SC-3: 構造的不整合が検出された場合、その詳細が記録されている

optional:
  - SC-4: 2段階検証が実施されている（必要に応じて）
  - SC-5: 全SubAgentの実行時間が30秒以内

---

Phase 3A: UI Consistency（agents/phase3a_ui_consistency.md）

適用ケース: レイアウト崩れ、スタイル不適用、要素が表示されない

検証項目:

Copy1. HTMLとCSSの対応確認
   - grep -r "クラス名" public/  # CSS定義あり？
   - grep -r "クラス名" public/modules/  # HTML生成してる？
   - 差分検出: CSSにあるのにHTMLで生成されていない = 構造的不整合

2. 親要素のレイアウトモード確認
   - 親要素が display: flex → 子要素は flex: 1 または min-height: 0 が必要
   - 親要素が display: grid → 子要素は grid-area 等の指定が必要
   - 親要素が position: relative → 子要素の position: absolute 動作を確認

3. スクロール階層の確認
   - overflow: hidden の親 → sticky positioning が機能しない
   - overflow: auto のネスト → スクロールが多重化していないか

Critical判定基準:

Copycritical:
  - CSSに定義があるがHTMLで生成されていない
  - 親要素のレイアウトモードと子要素の期待が不一致
  - スクロール階層が不適切（sticky不動作等）

---

Phase 3B: Variable Lifecycle（agents/phase3b_variable_lifecycle.md）

適用ケース: undefined, null reference, scope errors

検証項目:

Copy1. 変数の宣言を確認
   - grep -n "const 変数名" ファイル名
   - 宣言がない = undefinedエラーの原因

2. 変数のスコープを確認
   - ブロックスコープ（{}）内で宣言 → 外側で参照不可
   - 関数スコープ内で宣言 → 外側で参照不可

3. 非同期処理の順序を確認
   - await なしで Promise を参照 → undefined
   - コールバック内で変数参照 → スコープ外の可能性

Critical判定基準:

Copycritical:
  - 変数宣言が存在しない
  - スコープ外で変数を参照している
  - 非同期処理の順序が不適切（await不足等）

---

Phase 3C: Data Flow（agents/phase3c_data_flow.md）

適用ケース: データ変換バグ、計算ロジックエラー、フィルタ不動作

検証項目:

Copy1. 入力データを確認
   - 実際のデータ形式を確認（cat ファイル名 | grep）
   - 例: priority: high, medium, low, highest, critical, normal

2. コードの期待値を確認
   - grep -n "value=" ファイル名
   - 例: <option value="HIGH">
   - 差分検出: 実際は high、コード期待は HIGH = Case mismatch

3. データ変換ロジックを確認
   - フィルタ処理、マッピング処理、集計処理を確認
   - enum値の不足、変換ロジックの欠落を検出

Critical判定基準:

Copycritical:
  - 入力データとコード期待値が不一致（Case mismatch等）
  - データ変換ロジックが欠落している
  - enum値が不足している

---

Phase 3D: Data Architecture（agents/phase3d_data_architecture.md）

適用ケース: データ保存場所の混在、ディレクトリ構造の問題

検証項目:

Copy1. データ保存場所を確認
   - echo $BRAINBASE_ROOT  # 個人データ
   - echo $PROJECTS_ROOT  # プロジェクトコード
   - ls -la で実際の配置を確認

2. データ混在を検出
   - 個人データとプロジェクトコードが同じディレクトリ
   - git pull でデータ消失のリスク

3. 分離された構造を設計
   - BRAINBASE_ROOT: 個人データ専用
   - PROJECTS_ROOT: プロジェクトコード専用

Critical判定基準:

Copycritical:
  - 個人データとプロジェクトコードが混在
  - 環境変数が未設定でパスが不明
  - ディレクトリ構造が意図と異なる

---

Phase 3E: Code-Test Sync（agents/phase3e_code_test_sync.md）

適用ケース: リファクタリング後のテスト失敗

検証項目:

Copy1. 実装変更を確認
   - git diff HEAD~1 ファイル名
   - 例: getTasks() の戻り値が配列からPromise<配列>に

2. テストの期待値を確認
   - grep -A10 "getTasks" tests/unit/
   - 差分検出: テスト期待は同期的配列、実装は非同期Promise

3. 不整合のカテゴリ分類
   - 状態管理の変更
   - UI構造の変更
   - API仕様の変更
   - ロジック変更
   - サービス構造の変更

Critical判定基準:

Copycritical:
  - テストの期待値と実装が不一致
  - リファクタリング後にテストが未更新
  - 実装変更の影響範囲がテストでカバーされていない

---

Phase 3F: Config Processing（agents/phase3f_config_processing.md）

適用ケース: 設定ファイルのテンプレート展開、環境変数未展開

検証項目:

Copy1. 設定ファイルの生値を確認
   - cat _codex/projects/xxx/01_config.yml | grep path
   - 例: path: "${PROJECTS_ROOT:-/path}/xxx"

2. 展開後の値を確認
   - echo $PROJECTS_ROOT
   - 例: /Users/ksato/workspace/projects

3. テンプレート展開処理を確認
   - grep -A5 "expandEnvVars" lib/config-loader.js
   - 差分検出: テンプレート展開処理がない

Critical判定基準:

Copycritical:
  - テンプレート展開処理が実装されていない
  - 環境変数が未展開のまま使用されている
  - デフォルト値が不適切

---

Phase 3G: Deployment Operations（agents/phase3g_deployment_operations.md）

適用ケース: AWS CLI失敗、Lambda環境変数更新失敗、デプロイエラー

検証項目:

Copy1. CLI構文確認
   - aws lambda update-function-configuration --help
   - 期待構文と実際の構文を対比
   - クォート位置、JSON形式を確認

2. デプロイワークフローの安全性確認
   - バックアップ存在確認
   - Diffステップ確認
   - 整合性チェック確認

3. インフラ状態の整合性確認
   - API Schema Matching（期待構造 vs 実際構造）
   - Code-Data Schema Sync（コード期待値 vs データ実際値）

Critical判定基準:

Copycritical:
  - CLI構文が不正確（クォート位置誤り、JSON形式誤り等）
  - バックアップ/Diff/整合性チェックが不足
  - API Schema不一致

---

Phase 3H: Threat Containment（agents/phase3h_threat_containment.md）

適用ケース: セキュリティインシデント、脆弱性修正、アクセス制御

検証項目:

Copy1. Malware still present?
   - find / -name "*.malware" 2>/dev/null
   - ps aux | grep -i suspicious

2. Data exfiltration occurred?
   - grep -r "POST\|upload" /var/log/
   - tcpdump分析

3. All attack vectors closed?
   - netstat -tulpn | grep LISTEN
   - iptables -L -n
   - aws ec2 describe-security-groups

4. Forensic artifacts preserved?
   - ls -la /tmp/env_backup_*.json
   - ls -la /var/log/audit/

Critical判定基準:

Copycritical:
  - Malwareが残存している
  - データ流出の痕跡がある
  - 攻撃ベクトルが閉鎖されていない

---

Phase 4: VERIFY PREREQUISITES

SubAgent: agents/phase4_prerequisites.md

目的: 前提条件（ツール・環境変数・ファイル・権限）が満たされているか確認

Input（入力）:

Copyfrom_phase3:
  - verification_result: Phase 3の検証結果
  - structural_inconsistencies: 構造的不整合

from_orchestrator:
  - bug_id: BUG-XXX
  - work_dir: /tmp/verify-first-bugs/{BUG_ID}/

Process（処理）:

Copy1. 必要なツール・ライブラリの確認
   - which コマンド でツール存在確認
   - npm list / pip list でライブラリ確認

2. 環境変数の確認
   - echo $変数名 で設定値確認
   - 未設定の場合はエラー報告

3. ファイル・ディレクトリの存在確認
   - ls -la でファイル存在確認
   - 権限確認（読み取り/書き込み/実行）

4. 成果物を保存
   - {work_dir}/phase4_prerequisites.md に保存

Output（出力）:

Copydeliverable:
  - file: {work_dir}/phase4_prerequisites.md
  - content:
      - tool_check: ツール確認結果（installed/not installed）
      - env_var_check: 環境変数確認結果（set/not set, value）
      - file_check: ファイル存在確認結果（exists/not exists, permission）
      - missing_prerequisites: 不足している前提条件一覧

to_next_phase:
  - missing_prerequisites: Phase 5で根本原因を特定する際の材料

Success Criteria（成功基準）:

Copymandatory:
  - SC-1: 必要なツール・ライブラリが確認されている
  - SC-2: 環境変数の設定状況が確認されている
  - SC-3: ファイル・ディレクトリの存在が確認されている

optional:
  - SC-4: 不足している前提条件が明確化されている

---

Phase 5: IDENTIFY ROOT CAUSE

SubAgent: agents/phase5_root_cause.md（opus model使用）

目的: Phase 1-4で確認した事実から根本原因を特定する

Input（入力）:

Copyfrom_phase1:
  - expected_behavior: 期待動作
  - reproduction_steps: 再現手順

from_phase2:
  - affected_files: 影響ファイル
  - error_messages: エラーメッセージ

from_phase3:
  - verification_result: 検証結果
  - structural_inconsistencies: 構造的不整合

from_phase4:
  - missing_prerequisites: 不足している前提条件

from_orchestrator:
  - bug_id: BUG-XXX
  - work_dir: /tmp/verify-first-bugs/{BUG_ID}/

Process（処理）:

Copy1. 確認した事実を時系列で並べる
   - Phase 1: 期待動作、再現手順
   - Phase 2: 影響ファイル、エラーメッセージ
   - Phase 3: 構造的不整合
   - Phase 4: 前提条件の不足

2. 表面的症状と根本原因を区別
   - 表面的症状: "overflow-y: auto が効かない"
   - 根本原因: "HTMLとCSSの構造不整合"

3. Why を3回繰り返す
   - Q1: なぜXXXが動作しない？
   - A1: YYYが原因
   - Q2: なぜYYYが発生した？
   - A2: ZZZが原因
   - Q3: なぜZZZが発生した？
   - A3: 根本原因

4. 成果物を保存
   - {work_dir}/phase5_root_cause.md に保存
   - 根本原因、Why×3の結果、表面的症状との対比を記載

Output（出力）:

Copydeliverable:
  - file: {work_dir}/phase5_root_cause.md
  - content:
      - confirmed_facts: 確認した事実（時系列）
      - surface_symptom: 表面的症状
      - root_cause: 根本原因
      - why_chain: Why×3の結果

to_next_phase:
  - root_cause: Phase 6で修正する対象

Success Criteria（成功基準）:

Copymandatory:
  - SC-1: Why×3が実施されている
  - SC-2: 根本原因が確認済み事実ベースで特定されている
  - SC-3: 表面的症状と根本原因が区別されている

optional:
  - SC-4: 仮説ではなく確認済み事実ベースであることが明記されている

---

Phase 6: FIX AT ROOT

SubAgent: agents/phase6_fix.md

目的: 根本原因から修正し、表面的な対処療法を避ける

Input（入力）:

Copyfrom_phase5:
  - root_cause: 根本原因
  - why_chain: Why×3の結果

from_orchestrator:
  - bug_id: BUG-XXX
  - work_dir: /tmp/verify-first-bugs/{BUG_ID}/

Process（処理）:

Copy1. 根本原因に対する修正を実施
   - 表面的対処療法を避ける
   - 根本原因を直接解決する修正

2. 副作用の確認
   - 他の機能への影響を確認
   - テストを実行して副作用を検出

3. テストを追加
   - バグを再現するテストケース
   - 根本原因を検証するテストケース

4. 同じパターンの問題がないか確認
   - grep -r で類似コードを検索
   - 同じ構造的不整合が他にないか確認

5. 成果物を保存
   - {work_dir}/phase6_fix.md に保存
   - 修正内容、テスト追加、副作用確認結果を記載

Output（出力）:

Copydeliverable:
  - file: {work_dir}/phase6_fix.md
  - content:
      - fix_description: 修正内容（根本原因に対する修正）
      - modified_files: 変更したファイル一覧
      - test_added: 追加したテスト
      - side_effect_check: 副作用確認結果
      - similar_pattern_check: 同じパターンの問題確認結果

to_user:
  - fix_summary: 修正内容のサマリー
  - root_cause: 根本原因
  - verification_phase: どのPhaseで問題を特定したか

Success Criteria（成功基準）:

Copymandatory:
  - SC-1: 根本原因に対する修正が実施されている
  - SC-2: 副作用が確認されている
  - SC-3: テストが追加されている

optional:
  - SC-4: 同じパターンの問題が確認されている
  - SC-5: 表面的対処療法ではないことが明記されている

---

Phase 1: REPRODUCE & DEFINE EXPECTED

目的: 「あるべき姿」と「再現手順」を明確にする

Checklist

• バグの期待動作を1文で書けるか？
• 100%再現する手順があるか？
• ブラウザキャッシュ・サーバー再起動等の環境要因を排除したか？

Example（Settings Modal）

Copy期待動作:
  - Overviewタブ: コンテンツの高さに合わせて自動調整（無駄な空白なし）
  - Projectsタブ: ヘッダー固定、データ行がその下でスクロール

再現手順:
  1. http://localhost:3001 を開く
  2. Settings Modal を開く
  3. Overviewタブ: 警告の下に大きな空白がある ❌
  4. Projectsタブ: スクロールするとヘッダーが上に消える ❌

Phase 2: LOCATE AFFECTED COMPONENTS

目的: 問題が発生している具体的な場所を特定

Checklist

• エラーメッセージからファイル名・行番号を特定したか？
• ブラウザDevToolsで該当DOM要素を特定したか？
• git blameで最終変更者・コミットを確認したか？

Example（Settings Modal）

Copy# ブラウザDevToolsで要素検査
.integrity-summary  # ← 250px固定領域を確保（空白の原因）
.config-table-container  # ← CSS定義あり

# 関連ファイルを特定
public/style.css:2526-2565  # .integrity-summary定義
public/modules/settings/settings-core.js:249  # Projects HTML生成

Phase 3: VERIFY COMPONENT RELATIONSHIPS

重要: ここが最も重要なPhase。バグタイプに応じて適切な検証を行う。

3A: UI Bugs → HTML/CSS/PARENT CONSISTENCY

適用ケース: レイアウト崩れ、スタイル不適用、要素が表示されない

検証項目:

Copy# Step 1: HTMLとCSSの対応確認
grep -r "config-table-container" public/  # CSS定義あり？
grep -r "config-table-container" public/modules/  # HTML生成してる？
→ ❌ CSSにあるのにHTMLで生成されていない = 構造的不整合

# Step 2: 親要素のレイアウトモード確認
.settings-panel.active { display: flex; }  # 親がflexbox
→ 子要素は flex: 1 または min-height: 0 が必要
→ ❌ max-height: 400px が機能しない原因

# Step 3: スクロール階層の確認
.settings-content { overflow: hidden; }  # 親が overflow: hidden
→ ❌ sticky positioning が機能しない（親が overflow: visible 必要）

実例: 6dc723e（Flexbox height limit bug）、Settings Modal bug

---

3B: Runtime Errors → VARIABLE LIFECYCLE

適用ケース: undefined, null reference, scope errors

検証項目:

Copy// Step 1: 変数の宣言を確認
grep -n "const projectSelect" public/app.js
→ ❌ 宣言がない（undefinedエラーの原因）

// Step 2: 変数のスコープを確認
{
  const sessionId = '123';
}
console.log(sessionId);  // ❌ ReferenceError: sessionId is not defined

// Step 3: 非同期処理の順序を確認
const data = await fetch('/api/data');
console.log(data.items);  // ✓ await後なので安全

実例: e954dde（Variable undefined bug）

---

3C: Logic/Data → DATA FLOW

適用ケース: データ変換バグ、計算ロジックエラー、フィルタ不動作

検証項目:

Copy# Step 1: 入力データを確認
cat _tasks/index.md | grep "priority:"
→ 実際: priority: high, medium, low, highest, critical, normal

# Step 2: コードの期待値を確認
grep -n "value=" public/index.html
→ コード期待: HIGH, MEDIUM, LOW
→ ❌ Case mismatch

# Step 3: データ変換ロジックを確認
grep -A5 "priorityOrder" public/modules/domain/task/task-service.js
→ { HIGH: 3, MEDIUM: 2, LOW: 1 }
→ ❌ highest, critical が存在しない

実例: 7df3b60（Environment variable path bug）、6f8175e（Priority case mismatch）

---

3D: Infrastructure → DATA ARCHITECTURE

適用ケース: データ保存場所の混在、ディレクトリ構造の問題

検証項目:

Copy# Step 1: データ保存場所を確認
echo $BRAINBASE_ROOT  # /Users/ksato/workspace/shared
ls -la /Users/ksato/workspace/shared/_tasks  # 個人データ
ls -la /Users/ksato/workspace/shared/brainbase-ui/  # プロジェクトコード

# Step 2: データ混在を検出
→ ❌ 個人データとプロジェクトコードが同じディレクトリ
→ git pullでデータ消失のリスク

# Step 3: 分離された構造を設計
BRAINBASE_ROOT=/Users/ksato/workspace/shared  # 個人データ
PROJECTS_ROOT=/Users/ksato/workspace/projects  # プロジェクトコード

実例: 67e4cdf（BRAINBASE_ROOT change bug）

---

3E: Refactoring → CODE-TEST SYNC

適用ケース: リファクタリング後のテスト失敗

検証項目:

Copy# Step 1: 実装変更を確認
git diff HEAD~1 public/modules/domain/task/task-service.js
→ 変更: getTasks() の戻り値が配列からPromise<配列>に

# Step 2: テストの期待値を確認
grep -A10 "getTasks" tests/unit/task-service.test.js
→ ❌ テスト期待: 同期的な配列
→ 実装: 非同期Promise

# Step 3: 不整合のカテゴリ分類
- 状態管理の変更
- UI構造の変更
- API仕様の変更
- ロジック変更
- サービス構造の変更
- View仕様の変更

実例: d9f4dd2（53 failing tests after refactoring）

---

3F: Config → CONFIG PROCESSING

適用ケース: 設定ファイルのテンプレート展開、環境変数未展開

検証項目:

Copy# Step 1: 設定ファイルの生値を確認
cat _codex/projects/brainbase/01_config.yml | grep path
→ path: "${PROJECTS_ROOT:-/path}/brainbase"

# Step 2: 展開後の値を確認
echo $PROJECTS_ROOT
→ /Users/ksato/workspace/projects

# Step 3: テンプレート展開処理を確認
grep -A5 "expandEnvVars" brainbase-ui/lib/config-loader.js
→ ❌ テンプレート展開処理がない
→ "${PROJECTS_ROOT}" がそのまま使われている

実例: c466f26（Config template expansion bug）

---

3G: AWS/Infrastructure → DEPLOYMENT OPERATIONS

適用ケース: AWS CLI失敗、Lambda環境変数更新失敗、デプロイエラー

3G-1: CLI Command Syntax

検証項目:

Copy# Step 1: AWS CLIの期待構文を確認
aws lambda update-function-configuration --help
→ 期待: --environment Variables="$JSON"

# Step 2: スクリプトの構文を確認
grep -n "environment" .github/workflows/update-mana-token.yml
→ ❌ --environment "Variables=$JSON"  # クォート位置が間違い

# Step 3: JSON形式を確認
echo "$UPDATED_VARS" | jq '.'
→ ❌ 複数行JSON（AWSがパースできない）
→ ✓ jq -c で1行JSON化が必要

実例: a95dff5（AWS CLI JSON format bug）

---

3G-2: Deployment Workflow Safety

検証項目:

Copy# Step 1: バックアップ存在確認
ls -la /tmp/env_backup_*.json
→ ❌ タイムスタンプなしのバックアップ（復旧困難）

# Step 2: Diffステップ確認
grep -n "diff" .github/workflows/update-mana-workspace.yml
→ ❌ Diffステップがない（変更内容を確認できない）

# Step 3: Integrity check確認
grep -n "get-function-configuration" .github/workflows/update-mana-workspace.yml
→ ❌ 更新後の整合性チェックがない

実例: 02cb9db（AWS Lambda workflow safety）

---

3G-3: Infrastructure State Consistency

検証項目:

Copy# Case A: API Schema Matching
# AWS Lambda APIの期待構造を確認
aws lambda update-function-configuration --environment file://env.json
→ 期待: { "Variables": { "KEY": "value" } }

# スクリプトの生成構造を確認
cat /tmp/mana-env.json
→ ❌ { "KEY": "value" }  # Variables wrapperがない

# Case B: Code-Data Schema Sync
# コードの期待値を確認
grep "value=" public/index.html
→ <option value="HIGH">

# 実際のデータを確認
cat _tasks/index.md | grep "priority:"
→ priority: high  # ❌ Case mismatch

# Case C: Intent vs Reality Separation
# 永続化すべきフィールド
intendedState: 'active' | 'stopped' | 'archived'

# 計算すべきフィールド
ttydRunning: boolean  # activeSessions.has(id)から計算
→ ❌ state.jsonに ttydRunning が保存されていた

実例: b24e4d0（AWS Lambda JSON schema）、6f8175e（Priority case mismatch）、a5aa3be（State.json computed fields）

---

3H: Security → THREAT CONTAINMENT

適用ケース: セキュリティインシデント、脆弱性修正、アクセス制御

検証項目:

Copy# Step 1: Malware still present?
find / -name "*.malware" 2>/dev/null
ps aux | grep -i suspicious

# Step 2: Data exfiltration occurred?
grep -r "POST\|upload" /var/log/ | grep -v "legitimate"
tcpdump -r capture.pcap | grep -i "data="

# Step 3: All attack vectors closed?
netstat -tulpn | grep LISTEN  # 不審なポート
iptables -L -n  # Firewall rules
aws ec2 describe-security-groups  # AWS Security Groups

# Step 4: Forensic artifacts preserved?
ls -la /tmp/env_backup_*.json  # バックアップ
ls -la /var/log/audit/  # 監査ログ

実例: afa1cf6（DialogAI malware incident response）

---

Phase 4: VERIFY PREREQUISITES

目的: 前提条件が満たされているか確認

Checklist

• 必要なツール・ライブラリがインストールされているか？
• 環境変数が設定されているか？
• ファイル・ディレクトリが存在するか？
• 権限が適切か？

Example

Copy# ツール確認
which jq || echo "jq not installed"
which aws || echo "aws-cli not installed"

# 環境変数確認
echo $PROJECTS_ROOT || echo "PROJECTS_ROOT not set"
echo $BRAINBASE_ROOT || echo "BRAINBASE_ROOT not set"

# ファイル存在確認
ls -la /tmp/mana-env.json || echo "File not found"

# 権限確認
ls -la ~/.aws/credentials || echo "AWS credentials not found"

Phase 5: IDENTIFY ROOT CAUSE (from confirmed facts)

重要: 仮説ではなく、Phase 1-4で確認した事実から根本原因を特定

Checklist

• 確認した事実を時系列で並べたか？
• 表面的な症状と根本原因を区別したか？
• 「なぜ」を3回繰り返したか？

Example（Settings Modal）

Copy確認した事実:
  1. CSS に .config-table-container 定義あり
  2. HTML で .config-table-container を生成していない
  3. <table> を直接生成している
  4. CSSは .config-table-container にスクロール設定している

根本原因:
  settings-core.js で <table> を直接生成しており、
  CSSが期待する .config-table-container wrapper が存在しない

表面的症状:
  ❌ "overflow-y: auto が効かない"（表面）
  ✓ "HTMLとCSSの構造不整合"（根本）

Why を3回繰り返す

CopyQ1: なぜsticky headerが動作しない？
A1: 親要素が overflow: hidden だから

Q2: なぜ親要素が overflow: hidden？
A2: settings-panel.active が overflow-y: auto だから

Q3: なぜsettings-panel.active にスクロールを設定した？
A3: config-table-container が存在せず、代わりに設定したから

→ ROOT CAUSE: config-table-container wrapper が HTML に存在しない

Phase 6: FIX AT ROOT

目的: 根本原因から修正し、表面的な対処療法を避ける

Anti-patterns（やってはいけない）

Copy# ❌ Bad: 表面的な修正
- .settings-panel.active { overflow-y: auto; }
+ .settings-panel.active { overflow: hidden; }
（根本原因を直していない → 別の問題が発生）

# ✓ Good: 根本原因から修正
+ <div class="config-table-container">  # HTML構造を修正
    <table class="config-table">...</table>
+ </div>

Checklist

• 根本原因に対する修正か？（表面的対処療法ではないか？）
• 副作用がないか確認したか？
• テストを追加したか？
• 同じパターンの問題が他にないか確認したか？

Success Criteria

デバッグ時に以下を満たしているか確認:

• Phase 1: 期待動作を1文で書けた
• Phase 2: 影響範囲を特定できた
• Phase 3: バグタイプに応じた検証を実施した
• Phase 4: 前提条件を確認した
• Phase 5: 確認した事実から根本原因を特定した
• Phase 6: 根本原因から修正した
• 同じ箇所を2回以上触っていない
• 「なぜ直らないのか」を深掘りした

Real Bug Case Studies

このフレームワークで解決した実バグ11ケース:

Anti-Pattern Collection（やってはいけない思考パターン）

1. Assumption Trap（推測の罠）

Copy❌ "CSSに定義がある → HTMLにもあるだろう"
✓ "CSSに定義がある → HTMLを確認する"

2. Surface Fix（表面的修正）

Copy❌ overflow-y: auto → overflow: hidden に変更
✓ HTML構造を確認 → wrapper div がないことを発見 → 追加

3. Trial & Error Loop（試行錯誤の無限ループ）

Copy❌ overflow変更 → 直らない → 別のoverflow変更 → 直らない → ...
✓ Phase 3で構造を確認 → 根本原因特定 → 一発修正

4. Ignore User Feedback（ユーザーフィードバック無視）

Copy❌ "何も変わってないよ" と言われても安易な修正を続ける
✓ 深掘りして本当の問題を特定

Usage

このSkillは以下の状況で使用します:

1. バグ修正時（必須）

   • 表面的症状に惑わされず、根本原因から修正

2. レビュー時（推奨）

   • PRの修正が根本原因に対処しているか確認

3. ポストモーテム時（推奨）

   • なぜバグが発生したのか、VERIFY-FIRSTで振り返り

Expected Output

VERIFY-FIRST Frameworkを適用すると、以下のような明確な根本原因特定ができます:

Copy# Bug Analysis Report

## Phase 1: REPRODUCE & DEFINE EXPECTED
✅ 期待動作: Projects tab のヘッダーが固定され、データ行がスクロール
✅ 再現手順: Settings Modal → Projects tab → スクロール → ヘッダーも消える

## Phase 2: LOCATE AFFECTED COMPONENTS
✅ 影響ファイル: public/style.css:2663, public/modules/settings/settings-core.js:249

## Phase 3A: VERIFY HTML/CSS/PARENT CONSISTENCY
✅ CSS定義: .config-table-container { overflow-y: auto; }
❌ HTML生成: <table> を直接生成（wrapper なし）
❌ 構造不整合を検出

## Phase 4: VERIFY PREREQUISITES
✅ lucide icons: loaded
✅ CSS loaded: public/style.css

## Phase 5: IDENTIFY ROOT CAUSE
ROOT CAUSE: settings-core.js で .config-table-container wrapper を生成していない

Why を3回:
Q1: なぜsticky headerが動作しない？
A1: スクロールコンテナが存在しない

Q2: なぜスクロールコンテナが存在しない？
A2: HTMLで .config-table-container を生成していない

Q3: なぜ生成していない？
A3: CSSの定義だけ見て、HTMLを確認しなかった（Assumption Trap）

## Phase 6: FIX AT ROOT
✅ settings-core.js:249 に wrapper div 追加
✅ 根本原因から修正（表面的CSSいじりではない）

References

• CLAUDE.md: Section 1.1-1.5 (Architecture Principles)
• DESIGN.md: UI/UX design patterns
• Git commits: 11 real bug cases (6dc723e, e954dde, 7df3b60, 67e4cdf, d9f4dd2, c466f26, a95dff5, 02cb9db, b24e4d0, 6f8175e, a5aa3be)
• Session: 2025-12-31 Settings Modal debugging session（佐藤圭吾との対話から抽出）

---

最終更新: 2026-01-01 作成者: Claude Code (based on Keigo Sato's debugging session) ステータス: Active