---
name: issue-implement
description: >
  Issueの計画立案 → 実装 → PRレビュー・修正 → コメント整理を一気通貫で行うスキル。
  issue-planner で計画を立て、計画に基づいて実装し、ブランチ作成・コミット・PR作成後に
  pr-review で品質を担保し、最後に comment-cleanup でコメントを整理する。
  ユーザーが「Issue #123 を実装して」「#45 をやって」「このIssue対応して」
  「Issue実装」「implement #123」「これ対応して」「一気にやって」
  「計画から実装までやって」「プラン → 実装 → レビューまでお願い」
  などと言ったときにトリガーする。
  Issue番号やURLと共に実装の依頼があった場合にこのスキルを使うこと。
  計画だけでなく実装まで求められている場合は issue-planner ではなくこちらを使う。
---

# Issue Implement

## Workflow Overview

```text
Phase 1: 計画（issue-plannerに委譲）
  → .issue/{Issue番号}/plan.md, testing.md, (adr.md) を作成

Phase 1.5: デザイン作成（条件付き — フロントエンドのUI画面を新設・変更する場合のみ）
  plan.md から gate 判定 → 既存コードからデザイン言語を抽出（ドラフト提案なし）
  → spec/design/pages/*.html を作成 → レビュー（UI画面の新設・変更がなければスキップ）

Phase 2: 実装
  ブランチ作成 → plan.md に沿って実装 → 検証環境確認 → manual-test スキルでブラウザ検証（シードデータ準備含む）→ コミット → **Draft PR 作成**

Phase 3: レビュー・修正
  → 指摘修正 → 再レビュー（1ラウンドでクリーンなら完了、最大10ラウンド）→ APPROVED で **Ready for review に切替**

Phase 4: スコープ外Issueの起票
  → 全フェーズで見送ったスコープ外の改善・課題をIssueとして起票

Phase 5: コメント整理
  → ブランチの変更ファイル全体を comment-cleanup で整理 → コミット → push

Phase 6: ダッシュボード更新
  → ダッシュボード Issue があれば該当行だけ差分更新（この Issue の (In Progress) と新規起票の挿入のみ）
```

## Phase 1: 計画

`../issue-planner/SKILL.md` を読み、その手順に従って計画を立てる。

計画が完了したら（plan.md, testing.md, 必要に応じて adr.md が作成されたら）、次のフェーズに進む前に testing.md の「確認環境」セクションを検証する。具体的には:

1. testing.md の「実行手順」を読む
2. そこに書かれた各コマンドが CLAUDE.md・README.md・package.json の scripts（全項目）に実在するか、実際にファイルを読んで確認する
3. 変更箇所を実際に触れる状態にするまでに必要な手順が testing.md に揃っているかを確認する。曖昧な逃げ文句（例: 「手動で対応してください」「環境に応じて実行してください」）があれば、該当する正しいコマンドをプロジェクトのドキュメントから確認して置き換える
4. 実在しないコマンドがあれば削除または正しいコマンドに修正する
5. プロジェクト全体のセットアップ手順が含まれていたら削除し、Issue の変更を確認するのに必要なコマンドだけに絞る

検証が済んだら Phase 1.5 に進む。

## Phase 1.5: デザイン作成（条件付き）

Issue が**ユーザーに見える UI 画面を新設・変更する**場合だけ、実装に入る前に新しい画面の HTML モックを作る。画面の絵を先に固めることで、Phase 2 の実装サブエージェントが完成イメージを持って実装でき、手戻りを減らせる。

`references/design-guide.md` を読み、その手順に従う。要点:

- まず `.issue/{Issue番号}/plan.md` から gate 判定する。新規UI画面の追加・既存画面のレイアウト変更がなければ（バックエンド/API/ロジックのみ、軽微な調整など）、判定理由を一言ログに残してそのまま Phase 2 へスキップする。
- 実行する場合、デザインの方向性は**既存実装から抽出する**（ドラフト提案・新規トークン定義はしない）。新規画面が出荷済みのアプリに自然に馴染むことがゴール。
- 成果物は `spec/design/` 配下に出力し、Phase 2 のコミットに含めて実装と一緒に PR へ載せる。

## Phase 2: 実装

`references/implementation-guide.md` を読み、その手順に従って実装する。

実装中に下した非自明な設計判断は `.issue/{Issue番号}/adr.md` に追記する。
実装完了後、残存課題があれば `.issue/{Issue番号}/progress.md` に詳細を記録する。

## Phase 3: レビュー・修正

`references/review-guide.md` を読み、その手順に従ってレビュー・修正を行う。

レビューの成果物は `.issue/{Issue番号}/review/` に保存し、ADR は `.issue/{Issue番号}/adr.md` に追記する。

## Phase 4: スコープ外Issueの起票

実装中・レビューで気づいた、本筋（元Issue）の外にある改善・課題を扱う。本筋の勢いを止めないための整理であって、Issueを量産・細分化する場ではない。

- **簡単なものは起票しない。** 数分で直せるもの、同じファイル・機能・動線の些細な問題は、その場で直す（Phase 2/3 に戻る）。「念のためIssue」はトラッカーを散らかすだけ。
- **割らずにまとめる。** 同じテーマ・原因の気づきは1本に束ねる。スコープの境界を厳密に引くより、まとめて次へ進む。
- **既存へのマージを優先。** `gh issue list --search "{キーワード}"` で関連を探し、近ければコメントで追記。独立した新規だけ `gh issue create` する。

起票・追記がなければそのまま Phase 5 へ。

## Phase 5: コメント整理

`../comment-cleanup/SKILL.md` を読み、その手順に従ってこのブランチで触れたコードのコメントを整理する。

この時点では Phase 2/3 の変更がすべてコミット済みなので、comment-cleanup がデフォルトで見る `git diff`（未コミット分）は空になる。対象は「このブランチがベースブランチに対して加えた変更」全体なので、変更ファイルを明示的に渡す：

1. PR のベースブランチ（通常 `main`）を特定する。
2. `git diff {ベースブランチ}...HEAD --name-only` で変更されたファイル一覧を取得する。
3. その一覧を comment-cleanup の `target` として渡し、各ファイルのコメントを整理する。
4. コメントが変更されたら `chore: コメントを整理` のような単一コミットにまとめて push し、PR を更新する。変更がなければコミットせずスキップする。

レビュー承認後の追加変更になるので、差分はコメントの増減のみに限定する。

## Phase 6: ダッシュボード更新

このリポジトリで Issue ダッシュボードを運用していれば、その全体像を最新化する。ダッシュボードは `Issue Dashboard` というタイトルの GitHub Issue として管理されている。

- **ダッシュボード Issue が存在するときだけ実行する。** 次のコマンドで探し、見つからなければダッシュボード運用をしていないということなので、勝手に新規作成せずスキップする。

  ```bash
  gh issue list --state open --search "Issue Dashboard in:title" --json number,title,body
  ```

  同名タイトルの誤検出を避けるため、本文先頭に `<!-- issue-dashboard -->` マーカーがあるかで最終確認する。
- **issue-dashboard スキルのフル更新は行わない。** 全 Issue・全 PR の再取得や再分析はせず、検出時に取得済みの本文に対して**この実行に関係する行だけ**を直接編集する:
  1. **この Issue の行**に `(In Progress)` を付ける（既に付いていればそのまま。本文に行が無ければ、内容に合う既存セクションに `- #番号 タイトル (In Progress)` の1行を挿入する）。
  2. **この実行で新たに起票した Issue**（Phase 2 のブラウザ検証・Phase 3 の後回し・Phase 4 のスコープ外起票）があれば、それぞれ内容に合う既存セクション（無ければ「その他」）に1行ずつ挿入する。依存先が自明な場合（この Issue から派生した等）のみサブリストを付ける。
  3. それ以外の行・セクション構成・並び順には**一切手を入れない**（フル整理は issue-dashboard スキルを明示的に呼んだときだけ）。
- 編集後の本文を一時ファイルに書き出し、`gh issue edit <ダッシュボード番号> --body-file <一時ファイル>` で反映する。
- 更新対象はダッシュボード Issue 本文だけで、実装ブランチや PR には一切影響しない。

## 完了報告

すべてのフェーズが完了したら、サマリーを出す。

```text
Issue #{Issue番号} の実装が完了しました！

## 計画
- 計画ファイル: .issue/{Issue番号}/plan.md
- 設計判断: .issue/{Issue番号}/adr.md（{あり/なし}）
- 動作確認計画: .issue/{Issue番号}/testing.md
- 残存課題: .issue/{Issue番号}/progress.md（{あり/なし}）

## デザイン
- 実施: {実施（spec/design/pages/ に {数} 画面） / UI画面の新設・変更なしのためスキップ}
- レビュー記録: spec/design/review/（{ラウンド数} / スキップ時はなし）

## 実装
- ブランチ: issue/{Issue番号}/{短い説明}
- PR: #{PR番号}
- コミット数: {数}

## ブラウザ検証
- 成果物: .issue/{Issue番号}/manual-test/（またはスキップ）
- テストケース: {数}件（PASS: {数} / FAIL: {数}）
- 起票したIssue: {Issue一覧、またはなし}

## レビュー
- レビューラウンド: {数}回
- 初回ブロッカー: {数}件
- 修正済み: {数}件
- 最終ステータス: APPROVED
- PR状態: Ready for review（10ラウンド到達時のみ Draft のまま）
- レビューファイル: .issue/{Issue番号}/review/review-001.md 〜 review-{NNN}.md

## スコープ外Issue
- {起票したIssue一覧、またはなし}

## コメント整理
- 整理結果: {消した件数とカテゴリ、またはなし}
- コミット: {コミットハッシュ、またはスキップ}

## ダッシュボード
- 更新: {ダッシュボード Issue の URL / ダッシュボード未運用のためスキップ}
- この Issue の表示: {(In Progress) として反映 / 未運用のためなし}
```

## 原則

- Issueの**意図**を満たすことに集中する。plan.md は手段。意図に沿う小さな修正は plan.md 外でもスコープ内
- メインはオーケストレーションに徹し、実作業（実装・修正）はサブエージェントに委譲する。委譲方式・並列実行・失敗時の扱いは `../_shared/references/subagent-policy.md` に従う