/zen:sprint:list

Sprint/Iteration の一覧を表示する

---

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

前提条件

• zen-config.yml の iteration.enabled が true であること
• GitHub Projects に Iteration フィールドが存在すること

Iteration が無効な場合:

Iteration 機能は無効化されています。

有効にするには:
1. GitHub Projects で Iteration フィールドを作成
2. zen-config.yml の iteration.enabled を true に設定
3. /zen:init を再実行

詳細は /zen:workflow を参照してください。

---

Phase 1: 設定とフィールド情報の取得

1.1 zen-config.yml の読み込み

# zen-config.yml から iteration 設定を読み込み
# iteration.enabled が false の場合は上記のメッセージを表示して終了

1.2 Project ID の取得

gh api graphql -f query='
query($owner: String!, $number: Int!) {
  user(login: $owner) {
    projectV2(number: $number) {
      id
    }
  }
}' -f owner="{owner}" -F number={project_number}

1.3 Iteration フィールドと全イテレーションの取得

gh api graphql -f query='
query($projectId: ID!) {
  node(id: $projectId) {
    ... on ProjectV2 {
      fields(first: 20) {
        nodes {
          ... on ProjectV2IterationField {
            id
            name
            configuration {
              iterations {
                id
                title
                startDate
                duration
              }
            }
          }
        }
      }
    }
  }
}' -f projectId="{project_id}"

---

Phase 2: イテレーション状態の判定

2.1 現在日時との比較

各イテレーションについて状態を判定:

アルゴリズム:
1. 今日の日付を取得
2. 各イテレーションについて:
   - endDate = startDate + duration (days)
   - 今日 < startDate → "future" (予定)
   - startDate <= 今日 < endDate → "current" (現在)
   - endDate <= 今日 → "past" (過去)

2.2 各イテレーションの Issue 数を取得

gh api graphql -f query='
query($projectId: ID!, $iterationId: String!, $fieldId: ID!) {
  node(id: $projectId) {
    ... on ProjectV2 {
      items(first: 100, filter: {
        field: { fieldId: $fieldId, iterationId: $iterationId }
      }) {
        totalCount
        nodes {
          fieldValues(first: 10) {
            nodes {
              ... on ProjectV2ItemFieldSingleSelectValue {
                name
                field { ... on ProjectV2SingleSelectField { name } }
              }
            }
          }
        }
      }
    }
  }
}' -f projectId="{project_id}" -f iterationId="{iteration_id}" -f fieldId="{iteration_field_id}"

---

Phase 3: 一覧表示

3.1 デフォルト表示（現在 + 次回 + 直近の過去）

Sprint 一覧

  [現在] Sprint 3 (2025-01-06 - 2025-01-19)
         Issue: 5件 (完了: 2, 進行中: 2, 未着手: 1)

  [次回] Sprint 4 (2025-01-20 - 2025-02-02)
         Issue: 3件 (すべて未着手)

  [過去] Sprint 2 (2024-12-23 - 2025-01-05)
         Issue: 8件 (すべて完了)

合計: 3 スプリント表示 (全 5 スプリント)

3.2 フィルタオプション

オプション	説明
--all	すべてのイテレーションを表示
--current	現在のイテレーションのみ
--past	過去のイテレーションのみ
--upcoming	今後のイテレーションのみ

3.3 現在のイテレーションがない場合

Sprint 一覧

現在アクティブなスプリントがありません。

  [次回] Sprint 4 (2025-01-20 - 2025-02-02)
         Issue: 3件 (すべて未着手)

  [過去] Sprint 3 (2025-01-06 - 2025-01-19)
         Issue: 5件 (すべて完了)

ヒント: GitHub Projects でイテレーションの期間を確認してください。

---

Phase 4: 次のアクション提示

次のアクション:
- `/zen:sprint:current` で現在のスプリント詳細を表示
- `/zen:sprint:plan` でスプリント計画を実行
- `/zen:issue:list --sprint current` で現在スプリントの Issue 一覧

---

エラーハンドリング

Iteration フィールドが見つからない場合

エラー: Iteration フィールドが見つかりません

対処:
1. GitHub Projects ({project_url}) で Iteration フィールドを作成
2. フィールド名を zen-config.yml の iteration.field_name に設定
3. /zen:init を再実行

イテレーションが1つも設定されていない場合

Iteration が設定されていません

GitHub Projects ({project_url}) で Iteration を追加してください:
1. Iteration フィールドをクリック
2. "Add iteration" を選択
3. 開始日と期間を設定

API エラー時

GraphQL API 呼び出しが失敗した場合:

1. リトライ: ネットワークエラー時は最大 3 回リトライ（指数バックオフ）
2. フォールバック: API が利用不可の場合、警告を表示してスキップ
3. エラー報告: 具体的なエラーメッセージと対処法を表示

詳細は GraphQL ヘルパー を参照。

---

使用可能なツール

• Bash: gh コマンド実行
• Read: 設定ファイル読み取り

---

参照

• GraphQL ヘルパー - 共通クエリパターン