personal-clarify-issue Skill

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。

典型的なシグナル:

「できるようにしたい」
「追加したい」
「対応したい」
add
support
implement
new

Improvement

既存の機能、UX、性能、保守性、運用、分かりやすさを改善する Issue。

典型的なシグナル:

「使いにくい」
「遅い」
「分かりにくい」
「改善したい」
improve
optimize
refactor

Bug

壊れている、期待通りでない、誤っている、意図した挙動と違うものを修正する Issue。

典型的なシグナル:

「動かない」
「エラーになる」
「壊れている」
「期待と違う」
bug
fix
regression

テンプレート選択

リポジトリローカルのテンプレートが存在する場合、そのセクション構成を参考にする。

.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 "キーワード" .

# 関連 Issue を探す
gh issue list --search "キーワード"

# 関連 PR を探す
gh pr list --search "キーワード"

ユーザーに質問して埋める

コードベースを調べても分からない情報で、ユーザーが即答できそうなものは質問する。

質問するかどうかの判断基準:

ユーザーが数秒で答えられそうか
回答がないと Issue として成立しないか
時間のかかる調査が必要な質問ではないか

質問するときのルール:

一問一答で聞く（一度に複数の質問をまとめて投げない）
実装時に詰めればよい細かい不明点は質問せず 未確認事項 に残す

未確認事項として残してよいもの

以下のような情報は 未確認事項 に残してよい。

調べるのに時間がかかる（設計判断、仕様確認など）
ユーザーが意図的に後回しにしていると読み取れる
実装時に詰めればよい細かい不明点

未確認事項 は「このスキルが手を尽くして埋めきれなかった情報」だけを残す場所。何でもとりあえず入れる場所ではない。

タイトルの扱い

タイトルが以下の状態の場合は、改善案を提示してユーザーに確認を取る。

抽象的すぎる（例: 「バグ修正」「対応」「検討」）
動詞がなく Issue の目的が分からない
種別と内容が一致していない

ユーザーが確認した場合のみタイトルを更新する。

タイトルが十分に明確な場合は変更しない。

Issue 編集手順

対象 Issue を取得する
Issue 種別を判定する
テンプレートを選択する
既存の本文を各セクションにマッピングする
空欄セクションに対して、コードベース・関連 Issue・PR から情報を調べて埋める
それでも埋まらない項目があればユーザーに一問一答で質問する
残った空欄だけを 未確認事項 に列挙する
タイトルが不明瞭な場合は改善案をユーザーに確認する
gh issue edit <issue-number> --body <新しい本文> で本文を更新する
タイトルも変更する場合は --title <新しいタイトル> を追加する
更新後の Issue URL を返す

Fallback テンプレート

Fallback テンプレートはこのファイルと同階層の templates/ に置く。

templates/feature.md
templates/improvement.md
templates/bug.md

これらは、リポジトリに適切な Issue テンプレートが存在しない場合にのみ使う。

Agent Skills: personal-clarify-issue

Install this agent skill to your local

Skill Files