Issue Refinement
既存の GitHub Issue を明確化・具体化し、テンプレートに準拠した形式に改善するナレッジベーススキルです。
目的
このスキルは以下を提供します：
- •Issue 内容の改善: 曖昧な表現を具体的に
- •8項目の詳細確認: ユーザーへの体系的なヒアリング
- •受け入れ条件の測定可能化: 曖昧な条件を具体的な基準に変換
- •テンプレート準拠: 標準フォーマットへの整形
いつ使用するか
プロアクティブ使用（自動で検討）
以下の状況では、ユーザーが明示的に要求しなくても使用を検討：
- •Issue 品質改善の議論
- •「この Issue をもっと具体的に」
- •「受け入れ条件を明確にしたい」
- •曖昧な Issue の明確化
明示的な使用（ユーザー要求）
- •
/issue-refine <番号>コマンドの実行時
プロセス
全体フロー
code
/issue-refine {number}
│
├─ ステップ 1: Issue 情報取得
│
├─ ステップ 2: 改善対象選択
│ ├─ 本文全体
│ ├─ 受け入れ条件のみ
│ └─ タイトルと概要
│
├─ ステップ 2.5: 8項目の詳細確認
│ ├─ 背景・目的
│ ├─ 実装スコープ
│ ├─ 連携・依存関係
│ ├─ 優先度・期限
│ ├─ ユースケース
│ ├─ 受け入れ条件詳細
│ ├─ 実装時の注意点
│ └─ 関連 Issue
│
├─ ステップ 3: 改善案生成
│ └─ 収集情報を反映
│
├─ ステップ 4: 差分表示・確認
│ ├─ 適用する
│ ├─ 修正して適用
│ └─ スキップ
│
└─ ステップ 5: Issue 更新
8項目の詳細確認
Issue の不明点・曖昧な点を明確化するため、以下の8項目を順番に確認：
- •背景・目的: なぜこの機能/修正が必要か
- •実装スコープ: 何をやる/やらないか
- •連携・依存関係: 他機能との関係
- •優先度・期限: 緊急度と時間軸
- •ユースケース: 具体的な使用シナリオ
- •受け入れ条件詳細: 完了判断基準
- •実装時の注意点: 技術的制約
- •関連 Issue: 関連情報
活用ツールの使用方法
gh CLI
bash
# Issue 情報取得
gh issue view {issue_number} --json number,title,body,state,labels,url
# タイトル更新
gh issue edit {issue_number} --title "{new_title}"
# 本文更新
gh issue edit {issue_number} --body "$(cat <<'EOF'
{new_body}
EOF
)"
# 更新履歴コメント追加
gh issue comment {issue_number} --body "更新内容..."
リソース
このスキルには以下のリソースが含まれています：
./guide.md
Issue ブラッシュアップの詳細ガイド：
- •8項目の詳細確認フロー
- •AskUserQuestion の質問設計
- •改善案生成ガイドライン
- •差分表示形式
./template.md
改善用テンプレート：
- •Issue テンプレート
- •受け入れ条件の書き方
- •改善前後の差分表示形式
使用例
例1: 単一 Issue のブラッシュアップ
状況: 曖昧な Issue を明確化したい
処理:
bash
/issue-refine 123
- •Issue 情報取得
- •改善対象: 本文全体
- •8項目の詳細確認（AskUserQuestion）
- •改善案生成
- •差分表示・確認
- •Issue 更新
期待される出力:
markdown
## ブラッシュアップ結果 ### Issue #123 - **タイトル改善**: より具体的に変更 - **受け入れ条件**: 5項目を測定可能な形式に変換 ### 改善内容 - 概要: 「処理が遅い」→「APIレスポンスが3秒以上かかる」 - 受け入れ条件: 「パフォーマンス改善」→「平均レスポンス500ms以下」
例2: 複数 Issue のブラッシュアップ
状況: project.md に紐づく全 Issue を改善
処理:
bash
/issue-refine @src/market_analysis/docs/project.md
- •project.md から Issue 番号を抽出
- •各 Issue を順番に処理
- •「同じ設定で続行」オプションを提供
品質基準
必須（MUST）
- • Issue 情報が取得されている
- • 改善対象が選択されている
- • 8項目の詳細確認が完了している
- • 改善案が生成されている（確認情報を反映）
- • ユーザー確認が完了している
推奨（SHOULD）
- •受け入れ条件が測定可能な形式になっている
- •関連 Issue がリンクされている
- •テンプレートに準拠している
出力フォーマット
差分表示
markdown
## Issue #{number}: {title}
### タイトル
- **改善前**: {old_title}
- **改善後**: {new_title}
### 本文の変更
#### 概要
```diff
- 処理が遅い
+ API レスポンスが 3 秒以上かかるケースがある
受け入れ条件
diff
- [ ] パフォーマンスが改善される - [ ] テストが通る + [ ] 平均レスポンスタイムが 500ms 以下になる + [ ] 95パーセンタイルが 1 秒以下になる + [ ] make test が成功する + [ ] make check-all が成功する
code
### 改善サマリー ```markdown ### 改善サマリー - **タイトル改善**: より具体的な表現に変更 - **概要改善**: 問題の具体化と影響範囲の明記 - **受け入れ条件**: 4 条件を測定可能な形式に変換 - 曖昧 → 具体的: 2 件 - 新規追加: 2 件
エラーハンドリング
| ケース | 対処 |
|---|---|
| GitHub 認証エラー | gh auth login を案内 |
| Issue が存在しない | エラーメッセージを表示、次の Issue へ |
| Issue 更新権限なし | 権限不足を通知 |
| 本文が空の Issue | テンプレートを適用して新規作成 |
| closed Issue | 警告を表示、続行するか確認 |
完了条件
このスキルは以下の条件を満たした場合に完了とする：
- • 引数が正しく解析されている
- • Issue 情報が取得されている
- • 改善対象が選択されている
- • 8項目の詳細確認が完了している
- • 改善案が生成されている（確認情報を反映）
- • ユーザー確認が完了している
- • 承認された Issue が更新されている
- • 結果が表示されている
重要な注意事項
- •ステップ 2.5 は必須: Issue の不明点を明らかにするため、必ずユーザーに詳細を確認すること
- •情報の反映: 収集した情報は、改善案に漏れなく反映すること
- •測定可能性: 受け入れ条件は、ユーザー確認情報を元に必ず測定可能な形式にすること
- •関連情報: 関連 Issue、優先度、スコープなどの情報は必ず備考セクションに記載すること
関連スキル
- •issue-creation: Issue の作成
- •issue-implementation: Issue の自動実装
- •issue-sync: コメントからの同期
参考資料
- •
CLAUDE.md: プロジェクト全体のガイドライン - •
.claude/commands/issue-refine.md: /issue-refine コマンド定義