/dev-debug

name: dev-debug
description: This skill should be used when the user asks to "dev-debug", "テストが失敗する", "ビルドエラーを直して", "デバッグ", "debug failing tests", "fix build error", "エラーを修正", "コンパイルエラー", "環境の問題を解決". テスト失敗、ビルドエラー、環境問題など様々なエラーパターンをカテゴリ別に診断し、最小コンテキストで修正する。
argument-hint: '<error description>'

Dev Debug

テスト失敗、コンパイルエラー、環境問題など、様々なエラーパターンに対応する集中デバッグスキル。エラーをカテゴリ分類し、それぞれに最適な診断・修正戦略を適用する。最小コンテキストでの高速解決を目指す。

前提知識

dev-*スキルフロー内の位置

dev-context → dev-plan → dev-impl → dev-verify
                              ↘ [dev-debug] ↗
                                     ↑
                              dev-webtest → [dev-debug webtest] → 「/dev-webtest retest で再テストしてください」
                                     ↑                                            │
                                     └──────── retest ────────────────────────────┘

dev-impl で解消できないエラーが発生した場合、dev-verify で問題が検出された場合、または dev-webtest で検出された画面系エラーの修正に使用する。

引数フォーマット

/dev-debug                           # 自動検出モード
/dev-debug "エラーメッセージや状況の説明"  # 手動指定モード
/dev-debug webtest                   # webtest エラー修正モード

エラーカテゴリと対応戦略

カテゴリ一覧

| カテゴリ | 例 | 診断アプローチ | 典型的な修正 | |---------|---|-------------|-----------| | **コンパイル/型エラー** | 型不一致、missing import、構文エラー | エラーメッセージの直接分析 | 型定義修正、import追加 | | **テスト失敗** | assertion失敗、タイムアウト | 期待値と実際の差分分析 | ロジック修正 or テスト修正 | | **ランタイムエラー** | null参照、パニック、未処理例外 | スタックトレース分析 | エラーハンドリング追加 | | **環境・設定** | 依存関係エラー、設定ミス、パス問題 | 設定ファイル・環境変数チェック | 設定修正、依存追加 | | **Lint/フォーマット** | スタイル違反、未使用変数 | Lint出力分析 | 自動修正 or コード調整 | | **依存関係** | バージョン競合、パッケージ不足 | lock file/パッケージ分析 | バージョン調整、パッケージ追加 | | **webtest エラー** | 視覚崩れ、a11y違反、レスポンシブ不備、フォームバリデーション不備、シナリオ失敗 | error.md の検出内容・再現手順を分析 | CSS/HTML修正、バリデーション追加、機能バグ修正 |

ワークフロー

Step 1: エラー情報の収集と分類

自動検出モード（引数なし）

1. `docs/dev/context.md` からテスト実行コマンドを取得する 2. テストを実行してエラーを収集する 3. ビルドコマンドがある場合はビルドも実行する

手動指定モード（引数あり、webtest 以外）

ユーザーが提供したエラー情報を分析する。

webtest モード（引数が `webtest`）

1. `docs/dev/webtests/errors/` を Glob で走査し、全 `error.md` を取得する 2. 各 error.md を Read し、frontmatter の `status: open` のものだけ収集する 3. 0件の場合 →「未解決の webtest エラーはありません」と報告して終了 4. `severity` 順にソートする（critical → major → minor） 5. 各エラーを Step 2 の webtest エラー診断 → Step 3 の修正・検証で順次処理する 6. 全エラー処理後、Step 4 で報告する（`/dev-webtest retest` での再テストを案内）

分類判定

エラーメッセージのパターンマッチでカテゴリを判定する:

• `TypeError`, `SyntaxError`, `Cannot find module`, `missing import` → コンパイル/型エラー
• `AssertionError`, `expect(`, `assert`, `test failed` → テスト失敗
• `null`, `undefined`, `panic`, `NullPointerException`, `segfault` → ランタイムエラー
• `ENOENT`, `Permission denied`, `port already in use`, `env` → 環境・設定
• `eslint`, `prettier`, `clippy`, `unused variable` → Lint/フォーマット
• `ERESOLVE`, `version conflict`, `peer dependency` → 依存関係

Step 2: カテゴリ別診断

コンパイル/型エラー

**最小コンテキスト**: エラー箇所のファイルのみ読み込む。

1. エラーメッセージから該当ファイルと行番号を特定する 2. 該当ファイルの関連部分を読み込む（Read tool の offset/limit を活用） 3. 型定義・インターフェースが関係する場合はそれも読み込む 4. 修正案を生成する

テスト失敗

**最小コンテキスト**: テストファイル + 対象実装ファイル。

1. 失敗テストのファイルと名称を特定する 2. テストファイルを読み込み、期待値を確認する 3. 対象の実装ファイルを読み込む 4. 期待値と実際の差分から原因を特定する 5. **判断**: テストが正しいか、実装が正しいかを判断する

• テストが正しい場合 → 実装を修正
• 実装が正しい場合 → テストを修正（ユーザーに確認を推奨）

ランタイムエラー

**最小コンテキスト**: スタックトレースに含まれるファイル。

1. スタックトレースからコールチェーンを特定する 2. 最も関連性の高いファイルから読み込む 3. null/undefined チェックの漏れ、例外ハンドリングの不足を特定する 4. ガード句やエラーハンドリングを追加する

環境・設定

**最小コンテキスト**: 設定ファイル群。

1. Explore サブエージェント（haiku）で設定ファイルを探索する 2. 環境変数、パス設定、ポート設定等を確認する 3. 必要に応じてユーザーに手動操作を依頼する（AskUserQuestion） 4. AI単独で解決できない場合は明確に伝達する

Lint/フォーマット

**最小コンテキスト**: Lint出力のみ。

1. Lint/フォーマッターの自動修正コマンドがあれば実行する 2. 自動修正できない場合は手動で修正する 3. 修正後に再度Lintを実行して確認する

依存関係

**最小コンテキスト**: パッケージ定義ファイル + lock file。

1. パッケージマネージャのエラー出力を分析する 2. 依存ツリーの競合を確認する 3. 互換性のあるバージョンを提案する 4. 必要に応じてユーザーに確認する（破壊的変更がある場合）

webtest エラー

**最小コンテキスト**: error.md + 関連するソースファイル。

error.md の `step` フィールドに応じて診断アプローチを切り替える:

| step | 主な修正対象 | 診断アプローチ | |------|------------|-------------| | `3-visual` | CSS、テンプレート | error.md の検出内容からレイアウト崩れの原因を特定し、CSS/テンプレートを修正 | | `4-a11y` | HTML属性 | 不足している alt、label、aria 属性、heading 階層を特定して追加 | | `5-responsive` | メディアクエリ、CSS | 問題のビューポートサイズに対応するメディアクエリやレイアウト CSS を修正 | | `6-form` | バリデーションロジック | サーバー/クライアントのバリデーション処理を特定して修正。XSS/SQLi はサニタイズ処理を追加 | | `2a-scenario` / `2b-monkey` | 機能実装 | 再現手順と期待される状態から機能バグを特定し、実装を修正 |

1. error.md の「検出内容」「再現手順」「期待される状態」を読み取る 2. Explore サブエージェント（haiku）で関連ソースファイルを特定する 3. 上記テーブルに従い修正案を生成する 4. 修正を適用する（Step 3 へ進む）

Step 3: 修正の適用と検証

1. 修正案を適用する 2. カテゴリに応じた検証コマンドを実行する:

• コンパイル/型エラー → ビルド実行
• テスト失敗 → 失敗していたテストを実行
• ランタイムエラー → 関連テストを実行
• 環境・設定 → 環境チェックコマンド
• Lint → Lint再実行
• 依存関係 → インストール + ビルド

3. 修正が不十分な場合は Step 2 に戻る（**最大3サイクル**）

Step 4: 回帰テストと報告

1. 修正対象のエラーが解消されたことを確認する 2. 全テストを実行し、回帰がないことを確認する 3. 結果をユーザーに報告する

**報告フォーマット**（通常モード）:

## dev-debug 結果

### 検出されたエラー
- カテゴリ: [エラーカテゴリ]
- 原因: [根本原因の説明]

### 適用した修正
- [ファイル](パス): [修正内容]

### 検証結果
- 対象エラー: 解消
- 回帰テスト: passed / failed

### 確信度
- 🔵/🟡/🔴: [修正の確信度と理由]

**報告フォーマット**（webtest モード）:

## dev-debug webtest 結果

### 修正したエラー
| # | error.md | severity | step | 修正内容 |
|---|----------|----------|------|---------|
| 1 | docs/dev/webtests/errors/.../ | critical | 2a-scenario | [修正内容] |

### 修正できなかったエラー
| # | error.md | severity | step | 理由 |
|---|----------|----------|------|------|
（なければ「なし」）

### 次のステップ
`/dev-webtest retest` で再テストし、修正が反映されているか確認してください。

サイクル制限と escalation

3サイクルで解決できない場合:

1. これまでの診断結果と試行した修正をユーザーに報告する 2. 考えられる追加の原因仮説を提示する 3. ユーザーに次のアクションを相談する（AskUserQuestion）:

• 追加情報の提供
• 手動での確認依頼
• アプローチの変更

Intent コメントルール

コード修正時に、既存の Intent コメント（🔵🟡🔴）を維持し、修正箇所には適切に追加・更新する。

修正時の対応

• **既存の Intent コメントがある関数を修正する場合**: コメント内容が修正後も正確であれば維持する。修正により意図が変わった場合はコメントを更新する
• **新しい関数・メソッドを追加する場合**: dev-impl と同じルールで Intent コメントを付与する（public 関数は必須）
• **デバッグ修正特有の判断がある場合**: 修正理由を Intent コメントに反映する

// 🟡 Intent: nil チェックを追加。元のコードではリポジトリが nil を返すケースが
//    未考慮だったため、エラーとして返却するガード句を追加。
func (s *TodoService) GetByID(ctx context.Context, id string)