---

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

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

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

概要

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

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

主な機能

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

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

問題報告時

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

仕様との乖離確認

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

修正計画の策定

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

ワークフロー詳細

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

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

収集する情報

確認の形式

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

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

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

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

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

調査プロセス

1. 関連コードの特定

   • エラーメッセージやスタックトレースから該当箇所を特定
   • 機能に関連するファイルを調査

2. コードフローの追跡

   • 入力から出力までの処理フローを確認
   • 条件分岐やエラーハンドリングを確認

3. 原因の特定

   • 問題を引き起こしているコードを特定
   • なぜその問題が発生するかを明確化

分析結果の記録形式

Copy【根本原因分析】

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

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

[該当コード]

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

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

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

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

照合プロセス

1. 要件定義との照合（docs/requirements/）

   • 関連するユーザーストーリー（US-XXX）を確認
   • 受入基準を確認
   • 非機能要件（NFR-XXX）を確認

2. 設計との照合（docs/design/）

   • 関連するコンポーネント設計を確認
   • API設計を確認
   • 技術的決定事項（DEC-XXX）を確認

3. 乖離の分類

   • 実装バグ: 仕様は正しいが実装が間違っている
   • 仕様バグ: 仕様自体に問題がある
   • 仕様漏れ: 仕様に記載がない

照合結果の記録形式

Copy【仕様照合結果】

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

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

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

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

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

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

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

修正方針の検討項目

1. 修正アプローチ

   • どのように修正するか
   • 複数のアプローチがある場合は比較

2. 修正対象

   • 修正が必要なファイル/コンポーネント
   • コードの変更内容

3. 影響範囲

   • 修正による影響を受ける機能
   • 副作用の可能性

4. リスク評価

   • 修正に伴うリスク
   • リスク軽減策

5. 仕様更新の要否

   • 仕様バグ/漏れの場合、どのドキュメントを更新するか

修正方針の記録形式

Copy【修正方針案】

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

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

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

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

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

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

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

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

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

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

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

承認プロセス

1. 修正方針の提示

   • ステップ4で策定した修正方針を提示
   • 選択肢がある場合は比較表を提示

2. AskUserQuestionツールによる承認確認

   • 必ずAskUserQuestionツールを使用して承認を求める
   • 単純なyes/noではなく、具体的な選択肢を提示

3. 承認の記録

   • ユーザーの承認内容を記録
   • 追加の要望があれば反映

承認確認の形式

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

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

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

AskUserQuestionの使用例

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

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

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

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

承認後の確認事項

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

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

ステップ6: タスク分割

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

タスク分割の原則

1. 適切な粒度

   • AIエージェント作業時間で20-40分程度
   • 1タスク1責務

2. 依存関係の明確化

   • 先行タスクの明示
   • 並列実行可能なタスクの識別

3. 受入基準の設定

   • テスト可能な基準
   • 完了条件の明確化

タスクファイルの形式

Copy# 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も更新します：

Copy## バグ修正タスク

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

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

問題報告の受け取り

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

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

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

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

分析中の報告

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

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

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

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

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

修正方針の提示

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

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

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

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

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

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

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

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

成果物の保存

分析レポートの保存

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

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

analysis.mdのテンプレート

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

## 基本情報

| 項目 | 内容 |
|-----|------|
| 報告日 | [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オーケストレーターの一部として機能します：

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

連携するドキュメント

• 参照: docs/requirements/（仕様照合用）
• 参照: docs/design/（仕様照合用）
• 更新: docs/tasks/（修正タスク追加）
• 作成: docs/troubleshooting/（分析レポート）

リソース

リファレンス

• 分析ガイドライン: references/analysis_guide_ja.md

関連スキル

• 要件定義: requirements-defining/SKILL.md
• 設計: software-designing/SKILL.md
• タスク計画: task-planning/SKILL.md
• タスク実行: task-executing/SKILL.md