---
name: smart-issue-plan
description: >
  GitHub Issue の実装計画を作成・更新する。コードベースを分析し、影響範囲・実装手順・リスクを整理して
  Issue コメントまたは新規 Issue として投稿する。
  ユーザーが「計画立てて」「実装計画」「設計して」「#123 の計画」「/smart-issue-plan #123」と言ったら起動する。
  smart-issue-resolve（実装着手）とは別物。計画だけ作りたいときに使う。
disable-model-invocation: true
argument-hint: "#issue-number [-p 追加指示]"
allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
---

# Smart Issue Plan

GitHub Issue を分析し、コードベースを探索して実装計画を作成する。既存の計画がある場合は更新する。

## 引数の解析

`$ARGUMENTS` を以下のルールで解析する:

- `-p` より前の部分 → Issue 番号（`#` は除去）
- `-p` より後の部分 → `{プロンプト}`（計画の観点・制約に関する追加指示）
- `-p` がない場合 → `$ARGUMENTS` 全体を Issue 番号として扱い、`{プロンプト}` は空
- Issue 番号が未指定の場合 → AskUserQuestion で Issue 番号を確認する

例: `/smart-issue-plan #42 -p パフォーマンスを重視して` → Issue 番号: 42、プロンプト: 「パフォーマンスを重視して」

## ツール選択

GitHub API 操作には **GitHub MCP ツール**を優先する。コードベース探索には Glob, Grep, Read を使用する。

## 手順

### 1. Issue の読み取り

引数から抽出した Issue 番号で `issue_read` を呼ぶ。以下に該当する場合は通知して終了:

- Issue が存在しない、またはクローズ済み
- Pull Request（`issue_read` の `pull_request` フィールドあり）— PR に対する計画は本スキルの対象外
- Issue 本文が空でラベルも無い — 要件を判断できないため、ユーザーに内容を確認してから進める

コンテキストに残すのは **タイトル・本文（長い場合は要件・受け入れ基準部分のみ）・ラベル・直近 5 件以内のコメント** のみ。他のフィールド（イベント履歴、古いコメント等）は破棄する。

Issue 本文が Figma / Slack / 外部ドキュメントへのリンクに依存している場合、取得可能なら参照する。取得できない場合はユーザーに内容の要点を確認してから手順 4 に進む（推測で計画を作らない）。

### 2. 既存計画の確認

Issue のコメントに「## 実装計画」を含むものがあるか確認する。また `search_issues` で「[実装計画] <タイトルのキーワード>」を検索する。

- **既存計画あり** → 更新モードへ（手順 8）
- **既存計画なし** → 新規作成モードへ（手順 3）

### 3. 出力先の確認

計画を作成する前に、出力先をユーザーに確認する:

- **Issue コメントとして投稿**（デフォルト）
- **新規 Issue として作成** — 計画が大きい場合や、計画自体をタスクとして追跡したい場合に適する

### 4. コードベース探索

Issue の内容から関連するキーワード・ファイルパス・機能領域を特定し、以下の観点でコードベースを探索する。探索は推測ではなく実際のコード構造に基づいて行う。

**4a. エントリポイントの特定**
- Issue が言及する機能・画面・API のエントリポイントを Grep/Glob で探す
- ルーティング定義、コンポーネント定義、コマンドハンドラなど起点となるファイルを見つける

**4b. 依存グラフの把握**
- エントリポイントから import/require を辿り、変更が波及するファイル群を特定する
- 共通モジュール・型定義・設定ファイルへの依存も確認する

**4c. 既存パターンの確認**
- 類似機能がどう実装されているか Read で確認し、踏襲すべきパターンを把握する
- テストの書き方（テストフレームワーク、ディレクトリ構成、命名規則）も確認する

**4d. 境界条件の確認**
- 外部 API・DB スキーマ・設定ファイルなど、変更に制約を与える境界を特定する
- CI/CD パイプライン、lint ルール、型チェック設定など品質ゲートも確認する

### 5. 実装計画の作成

手順 4 の探索結果（主要ファイル・採用パターン・境界条件）を 10 行程度に要約してから計画作成に入る。要約が作れないなら探索が不十分なので 4a〜4d の該当箇所を再実行する。

[assets/plan-template.md](assets/plan-template.md) の構成で計画を作成する。`{プロンプト}` の指示があればそれを計画の観点に反映する。

計画は日本語で記述する。実装の詳細（具体的なコード）は書かず、方針と手順に留める。

**推奨ブランチ名の提案**:

プロジェクト側に独自のブランチ命名規則（CLAUDE.md・AGENTS.md・README 等で明示されている場合）があればそちらを優先し、なければ以下の規則に従って計画内に推奨ブランチ名を記載する。

フォーマット: `{type}/issue-{番号}-{簡潔な説明}`

| prefix      | 用途                             |
| ----------- | -------------------------------- |
| `feature/`  | 新機能・機能追加                 |
| `fix/`      | バグ修正                         |
| `refactor/` | リファクタリング（機能変更なし） |
| `docs/`     | ドキュメントのみの変更           |
| `chore/`    | ビルド・CI・依存関係など雑務     |
| `test/`     | テストの追加・修正               |

ルール:
- **kebab-case**（小文字 + ハイフン区切り）、ASCII のみ
- Issue に紐づく作業は必ず `issue-{番号}` を含める
- 説明部分は **英語・3〜5 語** 程度
- マイルストーン分割がある場合は末尾に `-m{番号}` を付ける

### 6. プレビューと承認

作成した計画の全文をユーザーに提示し、投稿前に承認を得る。

- 影響範囲・手順・リスクに抜けがないかユーザーが確認できる形で出す
- 承認なしに GitHub へ投稿しない（一度投稿したコメントの編集履歴は残るため）
- 修正指示があれば計画を書き直してから再度提示する

### 7. 投稿

手順 3 で決めた出力先に投稿する:

- **Issue コメント** → `add_issue_comment` で投稿
- **新規 Issue** → `issue_write` で「[実装計画] <元タイトル>」として作成し、元 Issue への参照リンクを本文冒頭に記載

投稿後、URL を表示し、実装に着手する場合は `/smart-issue-resolve #<Issue 番号>` を新規セッションで実行するよう案内して終了。

---

### 8. 更新モード

既存の計画コメント/Issue を読み取り、前回の計画からの差分を特定して更新する。

**8a. 変更点の特定**
- `git log --oneline --since="<計画作成日>"` で計画作成後のコミットを確認する（計画コメントのタイムスタンプを基準にする）
- Issue の新しいコメント（要件変更・追加指示）を確認する
- 計画が言及するファイルの現在の状態を Read で確認し、既に実装済みの手順を特定する

**8b. 計画の再評価**
- 実装済みの手順は完了マーク（✅）を付ける
- 要件変更やコード変更により無効になった手順は修正する
- 新たに判明したリスクや依存関係を追加する

**8c. 更新の投稿**
- 更新内容のプレビューをユーザーに提示し、承認を得る（手順 6 と同じ承認ゲート）
- 計画コメントの場合 → 新しいコメントとして更新版を投稿（`add_issue_comment`）し、前回コメントへのリンクを冒頭に記載
- 計画 Issue の場合 → 本文を直接更新（`issue_write`）

## 注意事項

- Issue の要件が不明確な場合は AskUserQuestion でユーザーに確認してから計画を作成する
- コードベース探索が不十分なまま計画を作らない — 手順 4 の各ステップを確実に実行する
- 投稿前に必ず手順 6（または 8c）の承認ゲートを通す — GitHub のコメントは削除しても編集履歴が残るため、誤投稿の影響が大きい
- 計画の更新で既存コメントを直接書き換えない — 新規コメントとして履歴を残す（計画 Issue の本文更新は例外）