issues-workflow

GitHub Issues 優先ワークフロー

デフォルト：すべてのコンテンツ、階層、追跡には GitHub Issues のみを使用します。 任意：リポジトリ間の可視化のみに Projects v2 をリンクします。

自己進化型スキル：このスキルは使用を通じて改善されます。指示が誤っている、パラメーターにずれが生じている、または回避策が必要だった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

重要な原則：すべては Issues で管理します

GitHub Issues = コンテンツ + 階層 + ステータス + 履歴。 GitHub Projects v2 = 可視化レイヤーのみ（コンテンツも履歴もありません）。

サブイシュー（2025 年 4 月に GA）により、Issues は階層をネイティブに扱えるようになりました。Projects v2 は、任意の可視化ダッシュボードに用途が限定されます。

Issues と Projects v2 の比較

機能	Issues（デフォルト）	Projects v2（可視化のみ）
コンテンツ	本文、コメント、コードブロック	なし（Issues へのリンクのみ）
階層	サブイシュー（親ごとに 100 件）	フラットなリスト
ステータス	オープン／クローズ + ラベル	カスタムフィールド（履歴なし）
編集履歴	編集ごとの差分をすべて記録	なし
タイムライン	すべての変更を記録	ステータス変更のみ（30 日間の制限）
検索	全文検索 + 30 種類以上のフィルター	限定的
CLI	gh issue list/view/create	gh project（Classic PAT のみ）
リポジトリ間	手動（--repo A --repo B）	1 つのダッシュボードで表示

それぞれを使う場面

┌─────────────────────────────────────────────────────────────┐
│                 ISSUES-FIRST WORKFLOW                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ALWAYS use Issues for:                                     │
│   ├── All content (findings, analysis, conclusions)          │
│   ├── Hierarchy (parent + sub-issues)                        │
│   ├── Status tracking (labels: status:in-progress)           │
│   ├── Categorization (labels: research:regime, priority:P0)  │
│   └── Filtering (gh issue list --label X --state Y)          │
│                                                              │
│   OPTIONALLY use Projects v2 for:                            │
│   ├── Cross-repo dashboard (single view across repos)        │
│   ├── Kanban visualization (drag-and-drop board)             │
│   ├── Roadmap timeline (visual date-based view)              │
│   └── Stakeholder reporting (Status Updates feed)            │
│                                                              │
│   NEVER put in Projects v2:                                  │
│   ├── Research findings (no edit history)                    │
│   ├── Analysis details (lost on update)                      │
│   ├── Any text content (use Issue body/comments)             │
│   └── Anything you need to track changes for                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘

判断フロー

Need to track work?
├── Single repo, <50 issues → Issues only (skip Projects)
├── Single repo, 50+ issues → Issues + optional Project for kanban
├── Multiple repos → Issues + Project for cross-repo dashboard
└── Stakeholder visibility → Issues + Project Status Updates

このスキルを使う場面

次のような場合にこのスキルを使用します。

• サブイシューを使ったイシュー階層を設定するとき（デフォルトのワークフロー）
• リポジトリ間の可視化ダッシュボードを作成するとき
• Issues から Projects への自動リンクを設定するとき
• ステークホルダー向けのステータス更新を設定するとき

覚えておいてください：すべてのコンテンツは Issues に保存します。Projects v2 は読み取り専用の可視化レイヤーです。

呼び出し方法

スラッシュコマンド：/gh-tools:issues-workflow

自然言語でのトリガー：

• 「この親イシューのサブイシューを作成して」
• 「イシュー階層を設定して」
• 「リポジトリ間のダッシュボードを作成して」
• 「可視化のためにイシューをプロジェクトにリンクして」

Issues 優先ワークフロー（デフォルト）

サブイシュー：ネイティブの階層（2025 年 4 月に GA）

サブイシューを使えば、Projects v2 の階層は不要です。構造化された作業にはすべてサブイシューを使用します。

サブイシューを使う場面

ユースケース	例	サブイシューを使う理由
調査の分解	親：「マイクロストラクチャーを調査」→ サブ：個別のパターン	各パターンの検証済み／無効化済みを追跡できる
エピックの分解	親：「ユーザー認証」→ サブ：ログイン、ログアウト、パスワードリセット	進捗バーに完了率が表示される
複数ステップの調査	親：「パフォーマンス問題をデバッグ」→ サブ：プロファイリング、メモリ、CPU	サブごとに異なる担当者を割り当てられる
段階的な作業	親：「v2.0 リリース」→ サブ：フェーズ 1、フェーズ 2、フェーズ 3	タイムラインに沿って自然に順序付けられる

サブイシューを使用しない場合

状況	代わりに使用するもの	理由
シンプルなチェックリスト（5項目未満）	イシュー本文内の Markdown チェックボックス	手間が少なく、本文内で編集できます
リポジトリをまたぐ依存関係	イシュー参照（See org/repo#123）	サブイシューは同じリポジトリ内のみです
緩やかな関連	本文内の「Related to #X」	サブイシューは包含関係を示します
単発タスク	ラベルを付けた単一のイシュー	過度に構造化しないためです

サブイシューの作成

# Create parent issue
gh issue create --title "Research: Range Bar Microstructure" \
  --label "research:parent" --repo terrylica/rangebar-py

# Create sub-issues (reference parent in body or use UI)
gh issue create --title "Regime detection patterns" \
  --body "Parent: #100" --label "research:sub" --repo terrylica/rangebar-py

構成例：

#100 Research: Range Bar Microstructure (parent)
├── #101 Regime detection patterns - Invalidated ✗
├── #102 Cross-threshold correlations - Validated ✓
├── #103 Duration normalization - In Progress
└── #104 Microstructure features v7.0 - Open

サブイシューの機能

• 進捗バー：親イシューに、視覚的なバーとともに「X of Y completed」と表示されます
• 双方向リンク：サブイシューのサイドバーに「Parent issue」が表示され、親イシューにはすべてのサブイシューが一覧表示されます
• 自動追跡：サブイシューをクローズすると、親イシューの進捗が更新されます
• ネスト：最大8階層まで可能です（サブサブサブイシュー）
• 上限：親イシューあたり100件のサブイシュー

移行に関する注意：タスクリストブロックは2025年4月30日に廃止されました。サブイシューが公式の代替機能です。移行ツールはないため、手動で変換する必要があります。

ラベルによるステータス管理（Projects 不要）

Project のカスタムフィールドの代わりにラベルを使用します。

ラベルのパターン	用途	例
status:*	ワークフローの状態	status:in-progress
priority:*	緊急度	priority:P0
research:*	調査の分類	research:validated
type:*	イシューの分類	type:hypothesis

# Filter by status
gh issue list --label "status:in-progress" --repo terrylica/rangebar-py

# Filter by research outcome
gh issue list --label "research:validated" --state all

# Combined filters
gh issue list --label "research:regime,status:complete" --state closed

イシューの種類（2025年にGA）

組織レベルで標準化できます（組織のみ。個人アカウントでは利用できません）。

# Configure at: Organization Settings → Issues → Issue Types
# Personal accounts: Use labels instead (type:hypothesis, type:finding)

Projects v2：可視化レイヤー（任意）

Projects v2 は、リポジトリをまたいだ可視化にのみ使用します。すべてのコンテンツは引き続き Issues に保持されます。

Projects v2 を使用する場合

ユースケース	Projects v2 が役立つ理由
リポジトリ横断ダッシュボード	複数のリポジトリを単一のビューで確認できます
カンバンボード	ドラッグ＆ドロップで視覚的にワークフローを管理できます
ロードマップのタイムライン	日付に基づく視覚的な計画を立てられます
ステークホルダー向けステータス	ステータス更新フィード（ON_TRACK など）

Projects v2 を使用しない場合

• 50件未満のイシューがある単一リポジトリ（gh issue list のフィルターを使用してください）
• 編集履歴が必要な場合（Projects にはありません）
• コンテンツの保存が必要な場合（Issue の本文やコメントを使用してください）
• バージョン追跡が必要な場合（Projects では以前の値が失われます）

イシューの Projects への自動リンク

イシューを自動的にリンクして、Projects を同期した状態に保ちます。

方法1：ラベルのプレフィックス規則

ラベル	自動リンク先
project:research	Research Findings
project:dev	Active Development

方法2：設定ファイル（.github/project-links.json）：

{
  "mappings": [
    {
      "labels": ["research:regime", "research:validated"],
      "projectNumber": 2
    }
  ],
  "owner": "terrylica"
}

ステータス更新（ステークホルダーとのコミュニケーション）

# Create status update via GraphQL
gh api graphql -f query='
mutation($projectId: ID!, $body: String!, $status: ProjectV2StatusUpdateStatus!) {
  createProjectV2StatusUpdate(input: {
    projectId: $projectId
    body: $body
    startDate: "2026-02-01"
    status: $status
  }) {
    statusUpdate { id status body }
  }
}' -f projectId="PVT_xxx" -f body="Research phase complete" -f status="ON_TRACK"

# Status values: ON_TRACK | AT_RISK | OFF_TRACK | COMPLETE | INACTIVE

トークンの要件

重要：Projects v2 API には、project スコープを持つ Classic PAT が必要です。

# Check token type
~/.claude/tools/bin/gh-token-for-repo | head -c 10
# ghp_ = Classic PAT (supports Projects)
# github_pat_ = Fine-grained (NO Projects support)

Project コマンドのリファレンス

# List/create/view projects
gh project list --owner <owner>
gh project create --owner <owner> --title "Dashboard Name"
gh project view <number> --owner <owner>

# Link issues to project (for visualization)
gh project item-add <project-number> --owner <owner> \
  --url https://github.com/<owner>/<repo>/issues/<number>

# Bulk link by label
gh issue list --repo terrylica/rangebar-py \
  --label "research:regime" --json url --jq '.[].url' | \
while read url; do
  gh project item-add 2 --owner terrylica --url "$url"
done

GitHub Issues：機能の完全なリファレンス

イシューの基本コマンド

# Create issue
gh issue create --title "Title" --body "Body" --label "label1,label2"

# Create with body file (alternative for very long content)
gh issue create --title "Title" --body-file /tmp/issue-body.md

# View issue
gh issue view <number> --repo owner/repo

# List with filters
gh issue list --label "research:validated" --state all --assignee @me

# Edit issue
gh issue edit <number> --add-label "status:complete" --remove-label "status:in-progress"

# Close/reopen
gh issue close <number> --reason completed
gh issue reopen <number>

高度なフィルタリング（30以上の修飾子）

# By multiple labels (AND logic)
gh issue list --label "research:regime,priority:P0"

# By milestone
gh issue list --milestone "Research Phase 1"

# By date
gh issue list --search "created:>2025-01-01 updated:<2025-12-01"

# By author/assignee
gh issue list --author @me --assignee username

# Full-text search
gh issue list --search "microstructure in:title,body"

# Combine everything
gh issue list \
  --label "research:validated" \
  --state closed \
  --search "regime created:>2025-06-01" \
  --json number,title,labels

イシューの関連付け

# Reference in body (creates link in timeline)
"Related to #45"
"Closes #123"
"Fixes #456"

# Cross-repo reference
"See terrylica/other-repo#789"

# Sub-issue (parent reference in body)
"Parent: #100"

タイムラインと履歴

# View full timeline (all events)
gh api repos/owner/repo/issues/123/timeline --paginate

# View edit history (via web UI or API)
gh api repos/owner/repo/issues/123 --jq '.body_html'

# Comment with preserved history
gh issue comment <number> --body "Update: new findings"

マイルストーン（Project のイテレーションの代替）

# List milestones
gh api repos/owner/repo/milestones

# Create milestone
gh api repos/owner/repo/milestones -f title="Research Phase 2" -f due_on="2026-03-01"

# Assign issue to milestone
gh issue edit <number> --milestone "Research Phase 2"

ワークフローの例

Issues のみを使う調査ワークフロー

# 1. Create parent research issue
gh issue create \
  --title "Research: Range Bar Microstructure Patterns" \
  --label "research:parent,priority:P1" \
  --body-file /tmp/research-parent.md

# 2. Create sub-issues for each investigation
for topic in "regime-detection" "cross-threshold" "duration-normalization"; do
  gh issue create \
    --title "Sub: $topic analysis" \
    --label "research:sub" \
    --body "Parent: #100"
done

# 3. Track progress via labels
gh issue edit 101 --add-label "research:invalidated"
gh issue edit 102 --add-label "research:validated"
gh issue close 101 --reason "not planned"

# 4. Filter to see status
gh issue list --label "research:sub" --state all --json number,title,state,labels

任意：可視化のために Project に追加

# Only if you need cross-repo dashboard
gh issue list --label "research:validated" --json url --jq '.[].url' | \
while read url; do
  gh project item-add 2 --owner terrylica --url "$url"
done

タイトルの更新：新しいコメントに応じて再評価

原則：GitHub のイシュータイトルは256文字までです。この上限を最大限に活用し、イシューの現在の状態を反映する、情報量の多いタイトルを作成してください。

再評価するタイミング

重要な新情報が追加されたとき（新たな調査結果、ステータスの変更、スコープの拡大、または作業の完了時）に再評価し、必要に応じて issue のタイトルを更新してください。

コマンド

# Check current title length
gh issue view <number> --json title --jq '.title | length'

# Update title (maximize 256 chars based on content)
gh issue edit <number> --title "..."

AI エージェントは、コンテンツの性質に基づいて、情報量を最大化する最適な方法を判断します。

Issue・ブランチ・PR のライフサイクル

issue からマージ済みコードまでの完全なライフサイクルで、issue は自動的にクローズされます。すべての自動化はローカルで行われます — テストや lint に GitHub Actions は使用しません。

推奨ワークフロー

1. Create issue(s)           → gh issue create --title "..." --body "..."
2. Branch from issue         → gh issue develop <N> --checkout
3. Implement + commit        → git commit -m "feat: description"
4. Create PR (with keywords) → gh pr create --body "Closes #N"
5. Merge PR                  → gh pr merge --squash --delete-branch
6. Issue auto-closes         → GitHub handles this automatically

クローズキーワード（マージ時に自動クローズ）

マージ時に issue を自動クローズするには、PR の本文（タイトルではありません）に Closes #N、Fixes #N、または Resolves #N を使用してください。大文字と小文字は区別されません。別のリポジトリを指定する場合は、Closes owner/repo#N を使用します。各 issue に個別のキーワードが必要です — Closes #1, closes #2, fixes #3。

Issue からブランチを作成（gh issue develop）

gh issue develop 214 --checkout              # auto-names branch
gh issue develop 214 --name feat/x --checkout  # custom name

issue に関連付けられたブランチを作成します。このブランチから作成された PR は自動的に関連付けられ、マージ時に issue を自動クローズします。

念には念を入れ、develop とクローズキーワードの両方を使用してください。

完全なリファレンス：Issue・ブランチのライフサイクル詳細 — キーワードの配置ルール、別のリポジトリのクローズ、一括クローズ、ブランチのクリーンアップ

GFM のレンダリングに関するアンチパターン

issue／PR のコメントで、#N を単独で使用しないでください。GitHub は、issue N が存在する場合、文章、テーブル、リスト内を問わず、あらゆる #N に自動でリンクを設定します。この動作は予測しにくく、一貫性がありません（リンクされる番号もあれば、されない番号もあります）。

• issue を参照する場合：明示的な完全 URL を使用します → [Issue 13](https://github.com/owner/repo/issues/13)
• issue 番号以外の数字の場合：バッククォートで囲んでリンクを抑制します → `#1`
• バックスラッシュ \#1 はテーブルのセル内では機能しません

6 つのアンチパターンの詳細については、完全なリファレンスを参照してください：GFM アンチパターンのリファレンス

トラブルシューティング

問題	原因	解決方法
テーブル内の #N が自動リンクされる	GFM の自動参照機能	バッククォートで囲んだコードスパンを使用します：`#1`（詳細）
"Resource not accessible"	Fine-grained PAT	Projects v2 では Classic PAT を使用します
サブ issue がリンクされない	本文の形式が正しくない	正確な構文「Parent: #123」を使用します
ラベルが正しくフィルタリングされない	ラベル名の誤字	gh label list で正確な名前を確認します
長い本文が途中で切り詰められる	GitHub API の 65536 文字制限	コンテンツを短くするか、複数のコメントに分けます
タイトルが短すぎる／曖昧	制限を十分に使っていない	文脈を伝えるため、256 文字の上限を最大限に活用します

リファレンス

• gh-tools Issue Create スキル
• Issue・ブランチのライフサイクル — クローズキーワード、gh issue develop、ローカル優先の自動化
• GFM アンチパターン
• フィールドタイプのリファレンス
• 自動リンク設定
• GraphQL クエリのリファレンス
• GitHub Issues のドキュメント

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功していない場合は、失敗の原因となった手順またはエラーテーブルを修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して一致させます。
3. 回避策が必要でしたか？ — 別のフラグや追加手順など、その場で工夫する必要があった場合は、次回の実行で同じ回避策が不要になるよう、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測で更新しないでください。