shibryo Polish Issue
作成済みのIssueを調査し、記載された変更を実施して検証すれば、元の課題が解決したと判断できる状態にする。
Issueの文章量を増やすことや、すべての項目を埋めることを目的にしない。
課題、原因または現在との差、解決方針、期待する結果、検証方法のつながりを明確にする。
原則
- 一度に一つのIssueを対象とする
- Issueの保存場所にかかわらず、現在のIssueを正本として扱う
- Issueに書かれた作業を、そのまま課題として扱わない
- 確認した事実、仮説、人間による決定を区別する
- 不明な情報を推測で補わない
- 課題を解決するために必要な最小の変更を選ぶ
- 調査の深さを、課題の影響、変更の大きさ、不確実性に合わせる
- 形式的な網羅より、重要な判断を変える証拠を優先する
- 実装に必要な判断と参照先をIssueへ集約する
- コード、テスト、仕様、ログを必要以上にIssueへ複製しない
- 実装方法をコード相当の詳細までIssueへ書かない
- 実装の完了ではなく、課題の解決を検証できる条件を書く
- 元のIssueの意図を黙って変更しない
- プロジェクト固有の規約を標準より優先する
- Polish完了と実装開始の承認を区別する
- 課題を解決する本番実装は行わない
入力
次を入力として扱う。
- 対象となる一つのIssue
- Issueの本文、コメント、関連Issue、変更履歴
- 対象プロジェクトのコード、テスト、仕様、履歴
- プロジェクト固有のIssue規約
Issueは、意味上の種類として task または bug のいずれかとする。
出力
次のいずれかを出力する。
- 課題解決までの論理が明確になった更新済みIssue
- 保存先へ書き込めない場合の更新案
- 人間の判断が必要な場合の調査結果と質問
- Issueを実装対象として磨くべきではない場合の根拠と推奨
手順
1. プロジェクトの規約を確認する
次の順序で適用する。
- ユーザーからの明示的な指示
- プロジェクトに含まれるIssue関連の規約
- Issue管理先に用意されたテンプレート
- この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. 結果を報告する
次の形式で簡潔に報告する。
## Polish結果
- 対象: {IssueのURLまたはパス}
- 結果: {更新完了／判断待ち／対応不要}
## 主な変更
- {明確にした課題}
- {選択した解決方針}
- {追加した検証方法}
## 根拠
- {確認したコード、テスト、仕様、実行結果}
## 未解決事項
- {ない場合は「なし」}
## 確認してほしいこと
- {Polishによって変更または確定した重要な判断}
- {対象範囲と対象外}
- {解決方針と検証方法}
判断待ち の場合は、Issueを完成したものとして扱わず、必要な判断と選択肢を提示する。
対応不要 は、現在のIssueを実装対象として磨くべきではないという調査結果を表す。Issueを閉じたことを意味しない。
対応不要の場合は、根拠と推奨する扱いを報告する。
Polish結果を報告した後、実装を自動的に開始しない。
カスタマイズ
プロジェクトは次の項目を変更または追加できる。
- Issueの保存先
- Issue本文の構造と見出し
- 必須となる調査対象
- 利用可能な実行環境
- 実験や試作を許可する範囲
- 必須となる検証方法
- Issueを分割する基準
- 必須となるレビュー観点
- Issueの更新と承認方法
- ラベル、担当者、優先度、マイルストーン
- 使用する言語
プロジェクト固有の規約がこのSkillと異なる場合は、異なる内容、理由、影響を確認してから適用する。