---
name: smart-issue-resolve
description: >
  GitHub Issue ID を受け取り、Issue を読み込んでブランチを作成・チェックアウトし、実装に着手する。
  既存の実装計画（smart-issue-plan が作成したコメント or `[実装計画]` Issue）があれば参照する。
  作業完了後に smart-commit の使用を提案する（勝手にコミット・push はしない）。
  ユーザーが「Issue やって」「#123 に取り掛かる」「/smart-issue-resolve #123」と言ったら起動する。
  smart-issue-plan（計画のみ作成）とは別物。実装まで踏み込むときに使う。
disable-model-invocation: true
argument-hint: "#issue-number [-p 追加指示]"
allowed-tools: Read, Bash, Glob, Grep, Edit, Write, AskUserQuestion
---

# Smart Issue Resolve

GitHub Issue を起点にブランチ作成→実装→完了案内までを行う。

## 引数の解析

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

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

例: `/smart-issue-resolve #42 -p テストも書いて` → Issue 番号: 42、プロンプト: 「テストも書いて」

## ツール選択

GitHub API 操作には **GitHub MCP ツール**を優先する（`issue_read`, `search_issues`, `add_issue_comment` 等）。`gh` CLI との混在を避ける。コードベース探索には Glob, Grep, Read を使用する。

## 手順

### 1. Issue の読み取り

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

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

コンテキストに残すのは **タイトル・本文（要件・受け入れ基準部分）・ラベル** のみ。他のフィールド（イベント履歴、関係の薄いコメント等）は破棄する。本文が長い場合は要件・受け入れ基準だけ抽出する。

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

smart-issue-plan が作成した計画があれば、実装前に参照する。

- Issue のコメントに「## 実装計画」を含むものがないか `issue_read` のコメント一覧から確認する
- `search_issues` で「[実装計画] <タイトルのキーワード>」を検索する

**レスポンスの絞り込み**（コンテキスト圧迫回避）:
- `issue_read` のコメント一覧からは、「## 実装計画」を含むコメント本文のみ保持する（他コメント・イベント履歴は破棄）
- `search_issues` の結果は各ヒットの URL・タイトル・作成日のみ保持する（本文は該当 Issue を開くときに再取得）

計画が見つかった場合は **実装手順・影響範囲・リスク** のセクションをコンテキストに残し、以降の実装で参照する。計画が古くてコード現況と乖離している兆候（計画で言及されたファイルが存在しない等）があれば、ユーザーに「計画を更新しますか？（`/smart-issue-plan #<番号>`）」と提案して判断を仰ぐ。

### 3. 作業ツリーの状態確認

現在のブランチ・未コミット変更・ローカルブランチ一覧を取得。

- **未コミット変更あり** → ユーザーに通知、続行なら `git stash push -m "smart-issue-resolve: <元ブランチ名> の退避"` で **メッセージ付き** stash する（手順 5 の分岐判定に使う）
- **デフォルトブランチ以外にいる** → 別作業中の可能性をユーザーに確認

stash する場合は **元ブランチ名・変更内容の概要** をユーザーに提示し、「現 Issue の作業の続き」「無関係な作業の退避」のどちらかを確認してフラグを記録する（手順 5 の分岐に使う）。判別がつかない場合は「無関係な作業の退避」として扱う（誤って pop してマージ衝突を起こすリスクを避ける）。

### 4. ブランチ名の決定

プロジェクト側に独自のブランチ命名規則（CLAUDE.md・AGENTS.md・README 等で明示されている場合）があればそちらを優先する。規則がなければ以下のデフォルトを使う:

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

| ラベル/内容 | type | 例 |
|-------------|------|----|
| bug | `fix` | `fix/issue-134-login-error` |
| feature / enhancement | `feature` | `feature/issue-42-add-oauth` |
| refactoring | `refactor` | `refactor/issue-78-extract-utils` |
| documentation | `docs` | `docs/issue-55-update-api-docs` |
| test | `test` | `test/issue-61-add-unit-tests` |
| その他 | `chore` | `chore/issue-99-update-deps` |

**ブランチ名のルール**:
- **kebab-case**（小文字 + ハイフン区切り）、ASCII 英数字 + ハイフン + スラッシュのみ（日本語・全角文字は使わない）
- `{説明}` は英語、3〜5 語以内
- 本スキルでは Issue 番号が引数で確定しているため `issue-{番号}` は必ず含める
- マイルストーン分割がある場合は末尾に `-m{番号}` を付ける（例: `feature/issue-42-add-oauth-m1`）

**既存ブランチの扱い**:
- 同じ Issue 番号のブランチがローカル・リモートに **1 件** 既存 → チェックアウトか新規作成かユーザーに確認する
- **複数件** 既存（マイルストーン分割等で `-m1` `-m2` に分かれている場合） → 一覧をユーザーに提示し、対象ブランチをチェックアウトするか新規作成するか選択させる

### 5. ブランチ作成・チェックアウト

ユーザー承認後、デフォルトブランチを最新にしてから新規ブランチを作成する。デフォルトブランチは `git symbolic-ref refs/remotes/origin/HEAD` で取得する（`origin/main` / `origin/master` / `origin/develop` 等を自動判別）。取得できない場合はユーザーに確認する。

stash の復元は手順 3 で記録したフラグに基づいて分岐する:

- **現 Issue の作業の続き** → 新ブランチ上で `git stash pop`
- **無関係な作業の退避** → 新ブランチ上では pop せず stash に残す。「元のブランチに戻ってから `git stash list` / `git stash pop` で復元してください」と案内する

### 6. 作業の実行

以下の流れで実装する:

1. **計画の参照** — 手順 2 で取得した計画があれば、その実装手順・影響範囲を基準にする
2. **コードベース調査** — 計画がない場合、または計画が粗い場合は、以下の観点で Issue の要件に関連するファイル・モジュールを特定する（推測ではなく実際のコード構造に基づく）:
   - **エントリポイント**: ルーティング定義・コンポーネント定義・コマンドハンドラなど起点を Grep/Glob で特定
   - **依存グラフ**: エントリポイントから import/require を辿り、変更が波及するファイル群を特定
   - **既存パターン**: 類似機能の実装を Read で確認し、踏襲すべき構成・命名・テストパターンを把握
   - **境界条件**: 外部 API・DB スキーマ・lint / 型チェック設定など品質ゲートの制約を確認
3. **実装前のベースライン確認** — 関連領域のテストがあれば変更前に一度実行し、既存の失敗と今回の変更による失敗を切り分けられるようにする。全テスト実行は時間がかかるので、関連ディレクトリ・関連モジュールにスコープを絞る。テストが特定できない / フレームワークが不明な場合は、代わりに手動確認方針（再現手順・確認すべき画面や API レスポンス等）をユーザーに提示・合意してから着手する
4. **実装** — Issue の要件・受け入れ基準に沿って変更を加える。`-p` の指示も反映する
5. **動作確認** — 実装後に同じスコープのテストを再実行し、既存テストの壊れがないこと・新規要件を満たすことを確認する。手動確認方針を採用した場合は確認結果（実施内容と結果）を完了案内に含める

スコープは Issue 記載内容（と計画があればその範囲）に限定する。Issue 内容が不明確なら実装前にユーザーに確認する。

実装中にコンテキスト圧縮で Issue 要件や計画の内容が失われた場合は、作業を一時停止して手順 1〜2 を再実行してから再開する（誤った前提のまま実装を続行しない）。

### 7. 完了案内

以下のサマリを提示する:

```
作業が完了しました。

## 変更サマリ
- 変更ファイル: <ファイル一覧>
- 実装した要件: <Issue の受け入れ基準に対する対応内容を箇条書きで>
- 動作確認: <実行したテストと結果、または手動確認した内容>

次のステップ:
1. コミット → `/smart-commit`
2. PR 作成 → `/smart-pr`
```

**勝手にコミット・push しない** — ユーザーの明示的指示を待つ。

## 注意事項

- `--no-verify` は使わない / force push はしない / push はしない
- Issue と関係のない変更を混ぜない（混ざった場合は smart-commit 側で分割する旨を案内する）