/zen:issue:start

Issue の作業を開始する（ブランチ作成、Status 更新、作業メモリ初期化）

---

このコマンドを実行したら、以下のフェーズを順番に実行してください。

引数

引数	説明
<issue_number>	作業を開始する Issue 番号（必須）

---

Phase 0: Epic/Sub-issues 判定

0.1 Issue 情報の取得

指定された Issue の詳細情報を取得:

gh issue view {issue_number} --json number,title,body,state,labels,milestone,projectItems

0.2 Milestone 確認

Issue が Milestone に紐づいている場合:

この Issue は Milestone "{milestone_name}" に含まれています。
Milestone には他に {count} 件の Issue があります。

この Issue から作業を開始しますか？

0.3 Sub-issues 確認

Issue に子 Issue（Sub-issues）がある場合、以下を確認:

gh api graphql -f query='
query($owner: String!, $repo: String!, $number: Int!) {
  repository(owner: $owner, name: $repo) {
    issue(number: $number) {
      trackedIssues(first: 10) {
        nodes {
          number
          title
          state
        }
      }
    }
  }
}' -f owner="{owner}" -f repo="{repo}" -F number={issue_number}

子 Issue がある場合:

この Issue には {count} 件の子 Issue があります:

| # | タイトル | 状態 |
|---|---------|------|
| #{number} | {title} | {state} |

親 Issue から開始するか、子 Issue を選択してください。

オプション:
- この Issue (#XX) から開始
- 子 Issue を選択

---

Phase 1: Issue 品質検証

1.1 品質スコア判定

Issue の内容を分析し、品質スコアを判定:

スコア	基準	判定条件
A	すべての項目が明確	What/Why/Where/Scope すべて明記
B	主要項目が明確、一部推測可能	What/Why が明確、Where/Scope は推測可能
C	基本情報のみ、補完が必要	What のみ明確、詳細不足
D	情報不足、作業開始前に補完必須	タイトルのみ、本文なしまたは不明確

1.2 品質チェック項目

以下の項目を確認:

項目	確認内容	必須/推奨
What	何をするか明記されているか	必須
Why	なぜ必要か説明されているか	推奨
Where	どのファイル/領域を変更するか	推奨
Scope	影響範囲が明確か	推奨
Acceptance	完了条件が明確か	推奨

1.3 スコア C/D の場合の対応

品質スコアが C または D の場合、AskUserQuestion で補完:

Issue #{number} の情報を補完してください。

現在の情報:
- タイトル: {title}
- 本文: {body_preview}

不足している情報:
- {missing_items}

質問: この Issue で具体的に何を達成しますか？
オプション:
- 既存の情報で作業開始（自分で判断）
- 情報を追加してから開始
- Issue を編集してから再度実行

---

Phase 2: 作業準備

2.1 ブランチ名生成

zen-config.yml のパターンに従ってブランチ名を生成:

branch:
  pattern: "{type}/issue-{number}-{slug}"
  types:
    feature: "feat"
    bugfix: "fix"
    documentation: "docs"
    refactor: "refactor"
    chore: "chore"

生成ルール:

1. type: Issue のラベルまたはタイトルから推定
   • bug, bugfix → fix
   • documentation, docs → docs
   • refactor → refactor
   • chore, maintenance → chore
   • その他 → feat
2. number: Issue 番号
3. slug: タイトルから生成（小文字、スペースをハイフンに、特殊文字削除、30文字以内）

2.2 既存ブランチ確認

同名ブランチが存在するか確認:

git branch --list "{branch_name}"
git branch -r --list "origin/{branch_name}"

既に存在する場合:

ブランチ {branch_name} は既に存在します。

オプション:
- 既存ブランチに切り替え
- 別名でブランチを作成（サフィックス追加）
- キャンセル

2.3 ブランチ作成

git checkout -b {branch_name}

2.4 GitHub Projects Status 更新

Project のアイテム ID を取得し、Status を "In Progress" に更新:

# プロジェクト番号を取得（zen-config.yml または検出）
gh project list --owner @me --format json

# Issue のプロジェクトアイテム情報を取得
gh api graphql -f query='
query($owner: String!, $repo: String!, $number: Int!) {
  repository(owner: $owner, name: $repo) {
    issue(number: $number) {
      projectItems(first: 10) {
        nodes {
          id
          project {
            id
            number
          }
        }
      }
    }
  }
}' -f owner="{owner}" -f repo="{repo}" -F number={issue_number}

# Status フィールド情報を取得
gh project field-list {project_number} --owner @me --format json

# Status を "In Progress" に更新
gh project item-edit --project-id {project_id} --id {item_id} --field-id {status_field_id} --single-select-option-id {in_progress_option_id}

2.5 作業メモリコメント初期化

Issue に作業メモリコメントを追加:

gh issue comment {issue_number} --body "$(cat <<'EOF'
## 🧘 zen 作業メモリ

### セッション情報
- **開始**: {timestamp}
- **ブランチ**: {branch_name}
- **最終更新**: {timestamp}

### 進捗
- [ ] 実装開始
- [ ] テスト追加
- [ ] ドキュメント更新

### 変更ファイル
<!-- 自動更新 -->
_まだ変更はありません_

### 決定事項・メモ
<!-- 重要な判断や発見 -->

### 次のステップ
1. Issue の内容を確認
2. 実装を開始
EOF
)"

タイムスタンプ形式: YYYY-MM-DDTHH:MM:SS+09:00 (ISO 8601)

---

Phase 3: 実装計画生成

3.1 Issue 内容の分析

Phase 1 で検証した品質スコアと抽出済み情報を活用し、実装計画を生成するための分析を行う:

要素	抽出内容	Phase 1 との関係
What	何をするか（タイトル・概要から）	Phase 1.2 で検証済み
Why	なぜ必要か（背景・目的から）	Phase 1.2 で検証済み
Where	どこを変更するか（変更内容・影響範囲から）	Phase 1.2 で検証済み、ここで具体化
Scope	影響範囲（影響範囲・チェックリストから）	Phase 1.2 で検証済み、ここで具体化

注意: Phase 1 で品質スコア C/D として補完された情報も含めて分析する。

3.2 変更対象ファイルの特定

Issue の内容に基づいて、変更が必要なファイルを特定:

1. Issue 本文に明記されているファイルパス
2. codebase 探索による関連ファイルの検出
3. 複雑度に応じたファイル数の推定

探索方法（Claude Code のツールを使用）:

ツール	用途	例
Glob	ファイルパターン検索	**/*.md, commands/**/*.md
Grep	キーワード検索	関連する関数名、クラス名、設定キー
Read	ファイル内容確認	候補ファイルの詳細確認

注意: bash コマンドではなく、Claude Code の専用ツールを使用してコードベースを探索する。

3.3 実装計画の生成

以下の形式で実装計画を生成:

## 実装計画

### 変更対象ファイル
| ファイル | 変更内容 |
|---------|---------|
| {file_path} | {change_description} |

### 実装順序
1. {step_1}
2. {step_2}
3. ...

### 注意点・考慮事項
- {consideration_1}
- {consideration_2}

3.4 ユーザー確認

AskUserQuestion で計画を確認:

上記の実装計画で進めますか？

オプション:
- 計画を承認（推奨）
- 計画を修正
- スキップ（計画なしで進める）

各選択肢の後続処理:

選択肢	後続処理
計画を承認	→ 3.5 で作業メモリに記録 → Phase 4 へ進む
計画を修正	ユーザーの追加指示を受けて計画を再生成 → 3.4 に戻る
スキップ	3.5 をスキップ → Phase 4 へ直接進む（計画は記録されない）

注意: 実装作業自体は Phase 4 完了後に開始する。このフェーズでは計画の確認と記録のみを行う。

3.5 作業メモリへの記録

承認された計画を作業メモリコメントに追記:

# 作業メモリコメントの ID を取得（より堅牢な方法）
comment_id=$(gh api repos/{owner}/{repo}/issues/{issue_number}/comments \
  --jq '.[] | select(.body | contains("🧘 zen 作業メモリ")) | .id')

# コメント ID を使用して更新
gh api repos/{owner}/{repo}/issues/comments/{comment_id} \
  -X PATCH \
  -f body="$(cat <<'EOF'
## 🧘 zen 作業メモリ

### セッション情報
- **開始**: {timestamp}
- **ブランチ**: {branch_name}
- **最終更新**: {timestamp}

### 実装計画
{implementation_plan}

### 進捗
- [ ] 実装開始
- [ ] テスト追加
- [ ] ドキュメント更新

### 変更ファイル
<!-- 自動更新 -->
_まだ変更はありません_

### 決定事項・メモ
<!-- 重要な判断や発見 -->

### 次のステップ
1. 実装計画に沿って作業開始
EOF
)"

注意:

• コメント ID を明示的に取得することで、他のコメントが間に追加されても正しいコメントを更新できる
• ユーザーが「スキップ」を選択した場合、このフェーズは省略し、Phase 4 に進む

---

Phase 4: 作業開始案内

4.1 完了報告

作業開始の準備完了を報告:

Issue #{number} の作業を開始しました

タイトル: {title}
ブランチ: {branch_name}
Status: In Progress

作業メモリを初期化しました。

4.2 プロジェクト種別に応じたガイダンス

zen-config.yml の project.type に応じて案内:

generic

次のステップ:
1. 実装を進める
2. `/zen:issue:update` で進捗を記録
3. 完了後 `/zen:pr:create` で PR 作成

webapp

次のステップ:
1. 変更が必要な領域を確認:
   - フロントエンド: src/components, src/pages
   - バックエンド: src/api, src/services
   - データベース: migrations, models
2. 実装を進める
3. `/zen:issue:update` で進捗を記録
4. 完了後 `/zen:pr:create` で PR 作成

library

次のステップ:
1. 破壊的変更の有無を確認
2. 公開 API への影響を検討
3. 実装を進める
4. テストを追加
5. `/zen:issue:update` で進捗を記録
6. 完了後 `/zen:pr:create` で PR 作成

cli

次のステップ:
1. コマンドインターフェースへの影響を確認
2. 後方互換性を検討
3. 実装を進める
4. `/zen:issue:update` で進捗を記録
5. 完了後 `/zen:pr:create` で PR 作成

documentation

次のステップ:
1. ドキュメント構成を確認
2. 実装を進める
3. リンク切れがないか確認
4. `/zen:issue:update` で進捗を記録
5. 完了後 `/zen:pr:create` で PR 作成

4.3 続行確認

作業案内表示後に AskUserQuestion で続行確認:

作業の準備が整いました。どうしますか？

オプション:
- 実装を開始する（推奨）: 実装計画に沿って作業を開始します
- 後で作業する: このセッションを終了し、後で作業を再開します

各選択肢の後続処理:

選択肢	後続処理
実装を開始する（推奨）	実装計画に沿って実装作業を開始（計画をスキップした場合は Issue 内容に基づいて作業）
後で作業する	「作業を中断しました」メッセージを表示して終了。次回 /zen:issue:start {number} で再開可能（ブランチ・作業メモリは保持）

---

エラーハンドリング

Issue が見つからない場合

エラー: Issue #{number} が見つかりません

考えられる原因:
- Issue 番号が間違っている
- Issue が削除されている
- リポジトリが異なる

対処:
1. `gh issue list` で Issue 一覧を確認
2. 正しい Issue 番号で再実行

Issue が既にクローズされている場合

警告: Issue #{number} は既にクローズされています

オプション:
- Issue を再オープンして作業開始
- キャンセル

ブランチ作成に失敗した場合

エラー: ブランチ {branch_name} の作成に失敗しました

考えられる原因:
- 未コミットの変更がある
- ブランチ名が不正

対処:
1. `git status` で状態を確認
2. 変更をコミットまたはスタッシュ
3. 再度実行

Projects が設定されていない場合

警告: GitHub Projects が設定されていません

Status の更新をスキップします。
Projects を使用するには `/zen:init` を実行してください。

---

使用可能なツール

• Bash: gh コマンド、git コマンド実行
• Read: 設定ファイル読み取り
• AskUserQuestion: ユーザー確認・明確化
• Grep: コードベース検索