# Polish Issue > 作成済みのタスクまたはバグのIssueを調査し、課題、解決方針、検証方法を明確にする。Issueの具体化、実装前調査、要件整理、実装可能性の確認、Issueの磨き込みを依頼されたときに使用する。 - Skill: `shibryo/polish-issue` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add shibryo/polish-issue` - Raw SKILL.md: https://api.skillmd.com/api/skills/shibryo/polish-issue/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: shibryo (https://skillmd.com/u/shibryo) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/shibryo/polish-issue --- # Polish Issue 作成済みのIssueを調査し、記載された変更を実施して検証すれば、元の課題が解決したと判断できる状態にする。 Issueの文章量を増やすことや、すべての項目を埋めることを目的にしない。 課題、原因または現在との差、解決方針、期待する結果、検証方法のつながりを明確にする。 ## 原則 - 一度に一つのIssueを対象とする - Issueの保存場所にかかわらず、現在のIssueを正本として扱う - Issueに書かれた作業を、そのまま課題として扱わない - 確認した事実、仮説、人間による決定を区別する - 不明な情報を推測で補わない - 課題を解決するために必要な最小の変更を選ぶ - 調査の深さを、課題の影響、変更の大きさ、不確実性に合わせる - 形式的な網羅より、重要な判断を変える証拠を優先する - 実装に必要な判断と参照先をIssueへ集約する - コード、テスト、仕様、ログを必要以上にIssueへ複製しない - 実装方法をコード相当の詳細までIssueへ書かない - 実装の完了ではなく、課題の解決を検証できる条件を書く - 元のIssueの意図を黙って変更しない - プロジェクト固有の規約を標準より優先する - Polish完了と実装開始の承認を区別する - 課題を解決する本番実装は行わない ## 入力 次を入力として扱う。 - 対象となる一つのIssue - Issueの本文、コメント、関連Issue、変更履歴 - 対象プロジェクトのコード、テスト、仕様、履歴 - プロジェクト固有のIssue規約 Issueは、意味上の種類として `task` または `bug` のいずれかとする。 ## 出力 次のいずれかを出力する。 - 課題解決までの論理が明確になった更新済みIssue - 保存先へ書き込めない場合の更新案 - 人間の判断が必要な場合の調査結果と質問 - Issueを実装対象として磨くべきではない場合の根拠と推奨 ## 手順 ### 1. プロジェクトの規約を確認する 次の順序で適用する。 1. ユーザーからの明示的な指示 2. プロジェクトに含まれるIssue関連の規約 3. Issue管理先に用意されたテンプレート 4. このSkillの標準 確認対象には、プロジェクトの指示ファイル、Issueテンプレート、既存Issue、ラベル規約を含める。 既存の規約がない場合、このSkillの標準を使用する。 ### 2. Issueを読み直す Issue管理先から、次の最新状態を取得する。 - タイトルと本文 - コメント - 関連Issue - 現在の状態 - 変更履歴 - 担当者やラベルなどのメタデータ 以前取得した内容やローカルの控えだけを信頼しない。 Issueが現在も対応対象であることを確認する。 次が判明した場合は、Issueを更新または終了せず、根拠と推奨する扱いを報告する。 - すでに解決されている - 別Issueと重複している - 現在の状態では再現しない - 前提となる仕様が変更されている - 記載された変更では元の課題を解決できない ### 3. Issueの種類を確認する 次の基準で分類する。 #### task 新しい価値、状態、または振る舞いを実現する。 #### bug 既に期待されている振る舞いと、実際の振る舞いの差異を修正する。 期待する振る舞いが既に存在する場合は `bug`、新しい状態を実現する場合は `task` とする。 分類によってIssueの意味が変わる場合や、どちらにも分類できない場合は、人間へ確認する。 ### 4. 課題を確定する Issueに記載された解決策や作業を、そのまま課題として扱わない。 次を明らかにする。 - 誰または何が影響を受けているか - 現在何が起きているか - なぜ問題なのか - どの根拠から問題だと判断できるか コード、テスト、仕様、ログ、関連Issue、変更履歴、実行結果から事実を確認する。 ### 5. 解決状態を定義する 課題が解決したと判断できる状態を、観測可能な振る舞いとして定義する。 実装方法ではなく、変更後に成立すべき結果を書く。 必要に応じて次を確認する。 - 正常時の振る舞い - 境界条件 - 失敗時の振る舞い - 維持すべき既存の振る舞い - 既存利用者や外部インターフェースとの互換性 ### 6. 現在との差を調査する すべてのIssueで、少なくとも次を行う。 - Issue本文、コメント、関連Issueを確認する - 関連するコード、テスト、またはドキュメントを特定する - 現在の状態と期待する状態を確認する - Issueに記載された方針が課題へ作用するか確認する 課題との関係がある場合は、次も確認する。 - インターフェース、データ、状態の流れ - 類似する既存実装 - 変更履歴と設計意図 - 外部との契約 - 実行時のログや計測結果 調査したファイル、テスト、仕様、変更履歴は、実装者が再確認できる形で示す。 参照先だけを列挙せず、それぞれが課題、原因または差、解決方針のどこを裏付けるかを書く。 次のつながりを根拠付きで説明できるまで調査する。 > 課題 → 原因または差 → 解決方針 → 期待する結果 → 検証方法 ### 7. 必要に応じて調査を広げる 次の場合は調査範囲を広げる。 - Issueの記述と現在の振る舞いが一致しない - 原因または変更箇所を絞り込めない - 外部インターフェースやデータ形式へ影響する - 既存の振る舞いを壊す可能性がある - 複数の解決方針に重要なトレードオフがある - 通常のテストだけでは期待する結果を確認できない - 過去に同様の変更が取り消されている - Issueの要求を実装しても、元の課題が解決しない可能性がある 追加調査によって重要な判断が変わる可能性が低くなった時点で、調査を終了する。 ### 8. 必要に応じて実験する 調査だけでは重要な不確実性を解消できない場合、再現、計測、テスト、または破棄可能な試作を行う。 実験前に次を明確にする。 - 確認する仮説 - 成功または失敗と判断する結果 - 実験によって決定する事項 実験前に、現在の作業ツリーと既存の変更を確認する。 既存の変更と安全に分離できない場合は実験せず、必要な検証と実行できない理由を報告する。 実験終了後は、次を行う。 - 再現手順、実行条件、結果をIssueへ記録する - 実験結果を再確認できる証拠を示す - 実験のためだけに作成した変更を取り除く - ユーザーの既存の変更を維持する 試作コードは、ユーザーが明示的に求めない限り、本番実装として残さない。 ### 9. 解決方針を選ぶ 現在の状態と解決状態の差へ作用する変更方針を選ぶ。 複数の方針がある場合は、次の観点から比較する。 - 課題を解決できるか - 変更範囲を小さく保てるか - 既存の振る舞いを維持できるか - 検証可能か - 不要な複雑さを持ち込まないか Issueには、課題解決に必要な変更の境界を書く。 完成コード相当の疑似コードや、コードから理解できる詳細な処理手順は書かない。 採用しなかった方針は、将来同じ判断が必要になる場合だけ、その理由とともに残す。 ### 10. 対象範囲を決める 課題解決に必要な変更を対象範囲とする。 関連しているだけで、課題解決に不要な変更を混ぜない。 複数の変更が次をすべて満たす場合は、同じIssueに残してよい。 - 同じ課題を解決する - 同じ結果によって完了を判断できる - 一緒に実施する必要がある 課題、完了条件、実施順序を独立して定義できる場合は、Issueの分割を提案する。 新しいIssueは、ユーザーの依頼またはプロジェクトの規約がある場合だけ作成する。 ### 11. 検証方法を決める 実装の存在ではなく、期待する振る舞いを確認する方法を定義する。 可能な限り次を満たす方法を選ぶ。 - 実装前の状態では課題を検出できる - 実装後の状態では期待する結果を確認できる - 課題に関係する境界条件や失敗時の振る舞いを確認できる - 維持すべき既存の振る舞いを確認できる `bug` では、発生していた問題の解消と再発の検知方法を定義する。 `task` では、目的とする新しい振る舞いが利用可能になったことを確認する。 ### 12. Issueを再構成する プロジェクト固有のテンプレートがある場合は、その構造を維持しながら必要な情報を追加する。 プロジェクト固有のテンプレートがない場合は、`references/default-issue-templates.md` を読み、Issueの種類に対応する構造を使用する。 次を守る。 - 調査の時系列ではなく、課題解決に必要な順序で構成する - 元のIssueに含まれる意図と証拠を維持する - 確認した事実と仮説を区別する - 外部の参照先と、実装に関係する要点を書く - 参照先を読まなければ分からない要件や判断を残さない - 必要のない見出しや空の定型項目を追加しない ### 13. 人間の判断が必要か確認する コード、テスト、仕様、履歴、関連Issue、実行結果から確認できる事実を、人間へ質問しない。 次の場合は、人間へ判断を求める。 - 解決すべき課題や目的を複数に解釈できる - 期待する振る舞いを既存の仕様から判断できない - Issueの要求と既存の設計意図が矛盾する - 複数の解決方針に要件上のトレードオフがある - 互換性を維持するか変更するか決定が必要 - 対象範囲を広げなければ完全には解決できない - 元のIssueの意図を変更する必要がある - 不可逆または復旧が難しい変更を伴う - 必要な情報へアクセスできず、代替となる証拠もない 質問するときは、`references/default-issue-templates.md` の判断依頼形式を使用する。 実際に成立する選択肢だけを提示し、調査結果に基づく推奨を示す。 判断結果に依存しない調査は継続してよい。ただし、判断結果を仮定してIssueを完成させない。 回答を受けたら、決定と理由をIssueへ反映する。 ### 14. Issueをレビューする 次の観点から、課題解決までの論理をレビューする。 #### 課題 - 課題は確認した事実に基づいているか - 解決策の要望を課題として扱っていないか - 影響を受ける対象と影響を説明できるか - 解決すべき状態の差を捉えているか #### 解決方針 - 方針は確認した原因または差に作用するか - 変更によって望ましい状態へ到達できるか - より小さく課題を解決できる方針がないか - 不要な変更が混ざっていないか - 仮説を確定事項として扱っていないか #### 影響範囲 - 関連するコンポーネント、データ、状態、インターフェースを見落としていないか - 維持すべき既存の振る舞いが明確か - 変更によって別の課題を生まないか - 対象外とした範囲が解決に本当に不要か - 依存関係や実施順序が必要ではないか #### 検証 - 実装の存在ではなく結果を確認しているか - 実装前と実装後の差を確認できるか - 関係する境界条件や失敗時の振る舞いを確認できるか - 完了条件を満たせば、元の課題が解決したと判断できるか #### 実行可能性 - 実装者がIssueから必要な判断と参照先を確認できるか - 必要なコード、テスト、仕様、関連Issueへ到達できるか - 課題や要件を実装者が再解釈する必要がないか - 実装中に判断してよい事項の範囲が明確か - 人間が判断すべき未解決事項が隠れていないか 指摘を次のように分類する。 - `Blocker`: 誤った変更になるか、課題を解決できない可能性がある - `Improvement`: 課題は解決できるが、明確さや実装効率を改善できる すべての `Blocker` を解消するまで、調査、方針選択、Issueの再構成を繰り返す。 `Improvement` は、Issueを不必要に大きくせず、課題解決に有効なものだけを反映する。 ### 15. Issueを更新する 確定した内容を、実装者が一か所から確認できるようIssue本文へ反映する。 重要な決定をコメントだけに残さない。 タイトルが次に該当する場合は更新する。 - 対象や事象を識別できない - 実装手段だけが書かれている - 未確認の原因を断定している - 調査によって明らかになった課題と一致しない Taskでは実現する結果、Bugでは期待と異なる事象をタイトルにする。 ラベル、担当者、優先度、マイルストーン、Issueの状態は、既存の規約または明示的な指示がある場合だけ変更する。 Polish独自のラベルや状態を作成しない。 保存先が不明、書き込み権限がない、またはユーザーが下書きを求めた場合は、Issueを変更せず更新案を提示する。 ### 16. 終了条件を確認する 次をすべて満たした場合にPolishを完了する。 - 誰または何が、なぜ困っているか説明できる - 課題が解決した状態を観測可能な振る舞いとして説明できる - 現在の状態との差を、確認した事実に基づいて説明できる - 解決方針が、その差へ作用する理由を説明できる - 課題解決に必要な変更範囲が明確である - 期待する結果を確認する方法が決まっている - Issueの変更と検証が、元の課題解決まで論理的につながっている - 人間が判断すべき未解決事項が残っていない - 残っている選択が、課題や要件を変えない実装上の選択だけである - 追加調査によって重要な判断が変わる可能性が低い - すべての `Blocker` が解消されている - Issue本文または更新案へ、確定した内容が反映されている 最後に、次を逆向きに確認する。 > この検証に合格すれば、望ましい状態になったといえるか > この変更を実施すれば、その検証に合格できるか > この方針は、確認した原因または差に作用するか > その差をなくせば、元の課題は解決するか いずれかを説明できない場合は、調査、方針選択、またはIssueの再構成に戻る。 必要な情報を取得できない場合や、人間の判断が必要な場合は、推測で完了させない。 ### 17. 結果を報告する 次の形式で簡潔に報告する。 ```markdown ## Polish結果 - 対象: {IssueのURLまたはパス} - 結果: {更新完了／判断待ち／対応不要} ## 主な変更 - {明確にした課題} - {選択した解決方針} - {追加した検証方法} ## 根拠 - {確認したコード、テスト、仕様、実行結果} ## 未解決事項 - {ない場合は「なし」} ## 確認してほしいこと - {Polishによって変更または確定した重要な判断} - {対象範囲と対象外} - {解決方針と検証方法} ``` `判断待ち` の場合は、Issueを完成したものとして扱わず、必要な判断と選択肢を提示する。 `対応不要` は、現在のIssueを実装対象として磨くべきではないという調査結果を表す。Issueを閉じたことを意味しない。 対応不要の場合は、根拠と推奨する扱いを報告する。 Polish結果を報告した後、実装を自動的に開始しない。 ## カスタマイズ プロジェクトは次の項目を変更または追加できる。 - Issueの保存先 - Issue本文の構造と見出し - 必須となる調査対象 - 利用可能な実行環境 - 実験や試作を許可する範囲 - 必須となる検証方法 - Issueを分割する基準 - 必須となるレビュー観点 - Issueの更新と承認方法 - ラベル、担当者、優先度、マイルストーン - 使用する言語 プロジェクト固有の規約がこのSkillと異なる場合は、異なる内容、理由、影響を確認してから適用する。