| name | personal-clarify-issue |
| description | 既存の GitHub Issue を整理・再構成します。ユーザーが Issue を「整理して」「構造化して」「書き直して」「わかりやすくして」「clarify して」などと依頼したときに使用してください。 |
| compatibility | Claude Code |
| allowed-tools | Read(*), Bash(fd *), Bash(rg *), Bash(gh repo view *), Bash(gh issue view *), Bash(gh issue edit *), Bash(gh issue list *), Bash(gh pr view *), Bash(gh pr list *), Bash(gh label list *), Bash(git config --local --get *), Bash(git config --local convention.language *) |
personal-clarify-issue
目的
既存の GitHub Issue を読み取り、内容を保持しながら構造・表現・明確さを改善する。
このスキルは、以下のような状態の Issue を整理する。
- 書き殴られた状態で構造がない
- 再現手順や完了条件が抜けている
- 「何をする Issue か」がタイトルだけでは分からない
- 複数の関心事が混在している
ユーザーが Issue を「整理して」「構造化して」「書き直して」「わかりやすくして」「clarify して」などと依頼したときに使う。
スコープ
このスキルがやること:
- 既存 Issue の本文を構造化・再構成する
- コードベースや関連 Issue・PR を調べて、空欄を積極的に埋める
- 短い質問で答えられる不明点はユーザーに確認して埋める
- どうしても分からない情報だけを
未確認事項 として残す
- タイトルが不明瞭な場合は改善案を提示し、ユーザーの確認を取ってから更新する
- GitHub Issue を実際に編集する
このスキルがやらないこと:
- 著者の意図・主張を変える
- 既存 Issue を削除・クローズする
- 新規 Issue を作成する
- ラベルを新規作成する
- 元の本文にない情報を勝手に追加する
基本方針
著者の意図を忠実に保ちながら、内容を能動的に明確化する。
「clarify（明確化）」するスキルである以上、空欄や 未確認 を残すことは最後の手段であり、デフォルトの選択肢ではない。調べれば分かること・聞けば分かることは積極的に埋める。
情報の解釈に迷ったときは「変更しない」を選ぶ。推測で内容を補ってはいけない。
リポジトリローカルの Issue テンプレートが存在する場合、そのセクション構成を参考にする。
Issue 読み取り手順
gh issue view <issue-number> --json number,title,body,labels,url で Issue を取得する- Issue の種別を判定する（Feature / Improvement / Bug）
- 適切なテンプレート構造を選ぶ
- 現在の本文を各セクションにマッピングする
Issue 種別の分類
現在の Issue 内容を読み取り、以下のいずれかへ分類する。
Feature
新しい能力・機能・画面・API・振る舞いを追加する Issue。
典型的なシグナル:
- 「できるようにしたい」
- 「追加したい」
- 「対応したい」
addsupportimplementnew
Improvement
既存の機能、UX、性能、保守性、運用、分かりやすさを改善する Issue。
典型的なシグナル:
- 「使いにくい」
- 「遅い」
- 「分かりにくい」
- 「改善したい」
improveoptimizerefactor
Bug
壊れている、期待通りでない、誤っている、意図した挙動と違うものを修正する Issue。
典型的なシグナル:
- 「動かない」
- 「エラーになる」
- 「壊れている」
- 「期待と違う」
bugfixregression
テンプレート選択
リポジトリローカルのテンプレートが存在する場合、そのセクション構成を参考にする。
.github/ISSUE_TEMPLATE/
リポジトリにテンプレートがない場合は、このスキルの fallback テンプレートを使う。
Feature -> templates/feature.md
Improvement -> templates/improvement.md
Bug -> templates/bug.md
情報のマッピング方針
既存の本文から情報を抽出し、適切なセクションに移す。
- 元の本文にある情報: 適切なセクションへ移動する
- 元の本文に複数セクションにまたがる情報: もっとも適切なセクションに配置し、残りを
未確認事項 に記載する
- 元の本文にない情報: 以下の順で対処する
1. コードベース・関連 Issue・PR から調べて埋める（後述）
2. ユーザーに短い質問をして埋める（後述）
3. どうしても分からない場合のみ `未確認` と書くか `未確認事項` に残す
元の本文にない情報を推測だけで創作してはいけない。
能動的な情報収集
元の本文に情報が不足している場合、以下の順で埋める努力をする。
コードベース・関連 Issue・PR から調べる
以下のような情報はコードベースや関連 Issue・PR を調べれば分かることが多い。
- 現在の実装や挙動（コードを読む）
- 関連する変更の経緯（関連 Issue・PR を読む）
- 既存のアーキテクチャや制約（コードベースを調べる）
- エラーメッセージの意味や原因（コードを読む）
調べ方の例:
rg -uuu "キーワード" .
gh issue list --search "キーワード"
gh pr list --search "キーワード"
ユーザーに質問して埋める
コードベースを調べても分からない情報で、ユーザーが即答できそうなものは質問する。
質問するかどうかの判断基準:
- ユーザーが数秒で答えられそうか
- 回答がないと Issue として成立しないか
- 時間のかかる調査が必要な質問ではないか
質問するときのルール:
- 一問一答で聞く（一度に複数の質問をまとめて投げない）
- 実装時に詰めればよい細かい不明点は質問せず
未確認事項 に残す
未確認事項として残してよいもの
以下のような情報は 未確認事項 に残してよい。
- 調べるのに時間がかかる（設計判断、仕様確認など）
- ユーザーが意図的に後回しにしていると読み取れる
- 実装時に詰めればよい細かい不明点
未確認事項 は「このスキルが手を尽くして埋めきれなかった情報」だけを残す場所。何でもとりあえず入れる場所ではない。
タイトルの扱い
タイトルが以下の状態の場合は、改善案を提示してユーザーに確認を取る。
- 抽象的すぎる（例: 「バグ修正」「対応」「検討」）
- 動詞がなく Issue の目的が分からない
- 種別と内容が一致していない
ユーザーが確認した場合のみタイトルを更新する。
タイトルが十分に明確な場合は変更しない。
Issue 編集手順
- 対象 Issue を取得する
- Issue 種別を判定する
- テンプレートを選択する
- 既存の本文を各セクションにマッピングする
- 空欄セクションに対して、コードベース・関連 Issue・PR から情報を調べて埋める
- それでも埋まらない項目があればユーザーに一問一答で質問する
- 残った空欄だけを
未確認事項 に列挙する
- タイトルが不明瞭な場合は改善案をユーザーに確認する
- 更新後の内容をユーザーに提示し、承認を得る（後述の「更新前の確認」）
gh issue edit <issue-number> --body <新しい本文> で本文を更新する- タイトルも変更する場合は
--title <新しいタイトル> を追加する
- 更新後の Issue URL を返す
更新前の確認
gh issue edit を実行する前に、必ず以下を提示してユーザーの承認を得る。
- 対象 Issue（番号と現在のタイトル）
- 更新後のタイトル（変更する場合。手順8で確認済みならその旨を明記する）
- 更新後の本文（全文）
承認を得るまで gh issue edit を実行しない。
ユーザーから修正の指示があれば、内容を反映してから再度提示し、承認を得る。
Fallback テンプレート
Fallback テンプレートはこのファイルと同階層の templates/ に置く。
templates/feature.md
templates/improvement.md
templates/bug.md
これらは、リポジトリに適切な Issue テンプレートが存在しない場合にのみ使う。
