name: sdd-troubleshooting description: SDDスキルで作成したシステムの動作不良や問題について、問題事象を確認し、根本原因を分析し、仕様と照らし合わせて修正方針を立て、ユーザー承認後にタスク分割を行います。修正方針は必ずユーザーの合意を得てから次のステップに進みます。 version: "1.0.0"

SDDトラブルシューティングスキル

SDDワークフローで作成されたシステムの問題を体系的に分析し、仕様に基づいた修正方針を策定します。

概要

このスキルは、ユーザーから報告された動作不良や問題に対して、以下のプロセスで対応します：

1. 問題事象の確認
      ↓
2. 根本原因の分析
      ↓
3. 仕様との照合
      ↓
4. 修正方針の策定
      ↓
5. ★ ユーザーへの修正方針承認 ★（必須ゲート）
      ↓
6. タスク分割・docs/tasks/への追加

主な機能

問題事象の詳細な確認と再現手順の把握
コード調査による根本原因の特定
docs/requirements/、docs/design/との仕様照合
修正方針の策定と影響範囲の特定
ユーザー承認プロセス（必須）
修正タスクの分割とdocs/tasks/への追加

このスキルを使用する場面

問題報告時

ユーザーがシステムの動作不良を報告した場合
期待動作と実際の動作に差異がある場合
バグや不具合が発見された場合

仕様との乖離確認

実装が仕様通りか確認したい場合
要件定義や設計との整合性を検証したい場合

修正計画の策定

問題の修正方針を決定したい場合
修正に伴う影響範囲を把握したい場合

ワークフロー詳細

ステップ1: 問題事象の確認

ユーザーから問題が報告されたら、以下の情報を収集します：

収集する情報

項目	内容	例
現象	何が起きているか	「保存ボタンを押してもデータが保存されない」
期待動作	本来どう動くべきか	「保存ボタンを押すとデータが永続化される」
再現手順	どうすれば再現できるか	「1. フォームに入力 2. 保存ボタンをクリック」
発生環境	どの環境で起きるか	「本番環境のみ」「特定ブラウザのみ」
発生頻度	常に起きるか	「常に」「特定条件下で」「まれに」
エラー情報	エラーメッセージ等	コンソールエラー、ログ、スタックトレース

確認の形式

問題の詳細を確認させてください：

【報告された現象】
- [ユーザーが報告した内容]

【確認事項】
1. 期待される動作は何ですか？
2. 再現手順を教えてください
3. どの環境で発生しますか？
4. 発生頻度はどの程度ですか？
5. エラーメッセージやログはありますか？

ステップ2: 根本原因の分析

問題事象が確認できたら、コードベースを調査して根本原因を特定します：

調査プロセス

関連コードの特定
- エラーメッセージやスタックトレースから該当箇所を特定
- 機能に関連するファイルを調査
コードフローの追跡
- 入力から出力までの処理フローを確認
- 条件分岐やエラーハンドリングを確認
原因の特定
- 問題を引き起こしているコードを特定
- なぜその問題が発生するかを明確化

分析結果の記録形式

【根本原因分析】

■ 調査したファイル
- [ファイルパス1]: [調査内容]
- [ファイルパス2]: [調査内容]

■ 原因箇所
- ファイル: [ファイルパス]
- 行番号: [行番号]
- 問題のコード:

[該当コード]


■ 原因の説明
[なぜこのコードが問題を引き起こしているかの説明]

■ 発生メカニズム
1. [ステップ1]
2. [ステップ2]
3. → 問題が発生

ステップ3: 仕様との照合

根本原因が特定できたら、docs/requirements/とdocs/design/を参照して仕様との照合を行います：

照合プロセス

要件定義との照合（docs/requirements/）
- 関連するユーザーストーリー（US-XXX）を確認
- 受入基準を確認
- 非機能要件（NFR-XXX）を確認
設計との照合（docs/design/）
- 関連するコンポーネント設計を確認
- API設計を確認
- 技術的決定事項（DEC-XXX）を確認
乖離の分類
- 実装バグ: 仕様は正しいが実装が間違っている
- 仕様バグ: 仕様自体に問題がある
- 仕様漏れ: 仕様に記載がない

照合結果の記録形式

【仕様照合結果】

■ 関連する要件
- [REQ-XXX]: [要件の内容]
  → 照合結果: [一致/乖離/該当なし]

- [US-XXX]: [ユーザーストーリー]
  → 受入基準との照合: [一致/乖離]

■ 関連する設計
- [コンポーネント名]: [設計内容]
  → 照合結果: [一致/乖離/該当なし]

■ 乖離の分類
- [ ] 実装バグ（仕様は正しいが実装が間違っている）
- [ ] 仕様バグ（仕様自体に問題がある）
- [ ] 仕様漏れ（仕様に記載がない）

■ 詳細
[乖離の詳細説明]

ステップ4: 修正方針の策定

仕様との照合結果を踏まえて、修正方針を策定します：

修正方針の検討項目

修正アプローチ
- どのように修正するか
- 複数のアプローチがある場合は比較
修正対象
- 修正が必要なファイル/コンポーネント
- コードの変更内容
影響範囲
- 修正による影響を受ける機能
- 副作用の可能性
リスク評価
- 修正に伴うリスク
- リスク軽減策
仕様更新の要否
- 仕様バグ/漏れの場合、どのドキュメントを更新するか

修正方針の記録形式

【修正方針案】

■ 問題サマリー
[問題の簡潔な説明]

■ 根本原因
[原因の簡潔な説明]

■ 修正アプローチ
[推奨アプローチ]:
- [修正内容1]
- [修正内容2]

[代替アプローチ]（該当する場合）:
- [代替案の内容]
- メリット: [メリット]
- デメリット: [デメリット]

■ 修正対象ファイル
1. [ファイルパス1]: [変更内容の概要]
2. [ファイルパス2]: [変更内容の概要]

■ 影響範囲
- [影響を受ける機能1]
- [影響を受ける機能2]

■ リスク評価
- リスク: [リスクの内容]
- 軽減策: [リスク軽減策]

■ 仕様更新
- [ ] 不要
- [ ] 要件定義の更新が必要: [対象ファイル]
- [ ] 設計の更新が必要: [対象ファイル]

■ テスト方針
- [テスト項目1]
- [テスト項目2]

ステップ5: ユーザーへの修正方針承認（必須ゲート）

重要: 修正方針が策定されたら、必ずユーザーの承認を得てから次のステップに進みます。

承認プロセス

修正方針の提示
- ステップ4で策定した修正方針を提示
- 選択肢がある場合は比較表を提示
AskUserQuestionツールによる承認確認
- 必ずAskUserQuestionツールを使用して承認を求める
- 単純なyes/noではなく、具体的な選択肢を提示
承認の記録
- ユーザーの承認内容を記録
- 追加の要望があれば反映

承認確認の形式

修正方針について承認をお願いします。

【修正方針サマリー】
- 問題: [問題の概要]
- 原因: [原因の概要]
- 修正内容: [修正の概要]
- 影響範囲: [影響範囲の概要]

上記の修正方針で進めてよろしいでしょうか？

AskUserQuestionの使用例

修正アプローチに選択肢がある場合：

質問: 修正アプローチを選択してください
選択肢:
A) [推奨アプローチ名]（推奨）
   - 説明: [アプローチの説明]
   - メリット: [メリット]

B) [代替アプローチ名]
   - 説明: [アプローチの説明]
   - メリット: [メリット]

C) 修正方針を再検討
   - 説明: 別のアプローチを検討します

承認後の確認事項

【承認内容】
- 承認日時: [日時]
- 承認されたアプローチ: [選択されたアプローチ]
- 追加の要望: [あれば記載]

修正タスクの作成に進みます。

ステップ6: タスク分割

ユーザー承認後、修正内容をタスクに分割してdocs/tasks/に追加します：

タスク分割の原則

適切な粒度
- AIエージェント作業時間で20-40分程度
- 1タスク1責務
依存関係の明確化
- 先行タスクの明示
- 並列実行可能なタスクの識別
受入基準の設定
- テスト可能な基準
- 完了条件の明確化

タスクファイルの形式

# TASK-XXX: [タスク名]

## 基本情報

| 項目 | 内容 |
|-----|------|
| ID | TASK-XXX |
| タイプ | bugfix |
| ステータス | TODO |
| 優先度 | High/Medium/Low |
| 見積もり | XX分 |
| 依存タスク | TASK-YYY（該当する場合） |

## 背景

### 問題の概要
[問題の簡潔な説明]

### 根本原因
[原因の簡潔な説明]

### 関連する仕様
- [REQ-XXX]: [要件の内容]
- [DEC-XXX]: [設計決定の内容]

## 実装内容

### 修正対象
- ファイル: [ファイルパス]
- 変更内容: [変更の概要]

### 実装手順
1. [手順1]
2. [手順2]
3. [手順3]

### 注意事項
- [注意点1]
- [注意点2]

## 受入基準

- [ ] [基準1]
- [ ] [基準2]
- [ ] [基準3]
- [ ] 既存のテストが通る
- [ ] 新規テストが追加されている（必要な場合）

## テスト項目

- [ ] [テスト項目1]
- [ ] [テスト項目2]

## 情報の明確性

### 明示された情報
- [情報1]
- [情報2]

### 不明/要確認の情報
- なし（すべて確認済み）

docs/tasks/index.mdの更新

タスク追加後、index.mdも更新します：

## バグ修正タスク

| ID | タスク名 | ステータス | 優先度 | 関連問題 |
|----|---------|-----------|--------|---------|
| TASK-XXX | [タスク名] | TODO | High | [問題の概要] |

ユーザー対話ガイドライン

問題報告の受け取り

ユーザーが問題を報告した際の対応：

問題のご報告ありがとうございます。

内容を確認させてください：
[報告内容の要約]

以下の点を追加で教えていただけますか？
1. [不明点1]
2. [不明点2]

分析中の報告

調査状況をユーザーに報告：

調査の途中経過をお伝えします。

【調査状況】
- 調査したファイル: [ファイル数]件
- 原因の特定: [進捗]

【現時点での所見】
[所見の内容]

引き続き調査を進めます。

修正方針の提示

修正方針を分かりやすく提示：

調査が完了しました。修正方針をご提案します。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【問題サマリー】
[問題の概要]

【根本原因】
[原因の説明]

【修正方針】
[修正内容の説明]

【影響範囲】
[影響を受ける機能]

【所要時間の目安】
[タスク数と見積もり]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

この方針で進めてよろしいでしょうか？

成果物の保存

分析レポートの保存

トラブルシューティングの分析結果は以下に保存します：

docs/
└── troubleshooting/
    └── [YYYY-MM-DD]-[issue-name]/
        ├── analysis.md      # 分析レポート
        └── tasks/           # 生成されたタスク（docs/tasks/にもリンク）

analysis.mdのテンプレート

# トラブルシューティング分析レポート

## 基本情報

| 項目 | 内容 |
|-----|------|
| 報告日 | [YYYY-MM-DD] |
| 分析完了日 | [YYYY-MM-DD] |
| 報告者 | [報告者名] |
| ステータス | 分析完了/修正中/完了 |

## 問題事象

### 報告された現象
[現象の説明]

### 期待動作
[期待される動作]

### 再現手順
1. [手順1]
2. [手順2]
3. [手順3]

### 発生環境
- 環境: [環境名]
- 頻度: [発生頻度]

## 根本原因分析

### 調査したファイル
- [ファイルパス1]
- [ファイルパス2]

### 原因箇所
- ファイル: [ファイルパス]
- 行番号: [行番号]

### 原因の説明
[原因の詳細説明]

## 仕様照合結果

### 関連する要件
- [REQ-XXX]: [照合結果]

### 関連する設計
- [コンポーネント名]: [照合結果]

### 乖離の分類
- [x] 実装バグ / [ ] 仕様バグ / [ ] 仕様漏れ

## 修正方針

### 承認済み修正方針
[承認された修正方針の内容]

### 承認日時
[YYYY-MM-DD HH:MM]

### 修正対象ファイル
1. [ファイルパス1]
2. [ファイルパス2]

## 生成されたタスク

| ID | タスク名 | ステータス |
|----|---------|-----------|
| TASK-XXX | [タスク名] | TODO |

## 備考
[その他の備考]

ベストプラクティス

1. 問題の正確な把握

ユーザーの報告を鵜呑みにせず、再現確認を行う
期待動作と実際の動作の差異を明確化
環境差異による問題かどうかを確認

2. 体系的な原因分析

推測で原因を決めつけない
コードを実際に追跡して確認
複数の原因がある可能性を考慮

3. 仕様との照合の徹底

必ずdocs/requirements/とdocs/design/を参照
仕様の解釈に迷ったらユーザーに確認
仕様漏れの場合は仕様追加も検討

4. 修正方針承認の必須化

必ずユーザーの承認を得てからタスク作成に進む
複数のアプローチがある場合は選択肢として提示
承認内容を記録に残す

5. 影響範囲の慎重な評価

修正による副作用を事前に検討
関連するテストを確認
リグレッションのリスクを評価

SDDワークフローとの統合

このスキルは、sdd-documentationオーケストレーターの一部として機能します：

sdd-documentation
    │
    ├── requirements-defining → docs/requirements/
    ├── software-designing   → docs/design/
    ├── task-planning        → docs/tasks/
    ├── task-executing       → 実装コード
    │
    └── sdd-troubleshooting  → 問題分析・修正タスク（このスキル）

sdd-troubleshooting

SKILL.md