issue-agreement スキル

issue は要求の記録であると同時に、コードベースの現状や実装方法についての未検証の記述を含む。特に AI が作成した issue は、情報量が多く断定調で書かれていても、実態と食い違っていることがある。このスキルは、実装に入る前に issue の記述を実態と突き合わせ、何を作るかをユーザーと合意するためのものである。

原則

• issue 本文のうち、意図(何を望んでいるか)は要求として扱ってよい。
• コードベースの現状、原因分析、実装方法に関する記述は主張であって事実ではない。コードと突き合わせて一致を確認するまで、決定の根拠にしない。
• 情報量の多さを、検証済みであることと混同しない。長い issue ほど未検証の主張が多い前提で臨む。
• issue への書き込み(コメント・ラベルの変更)は行わない。報告と確認の相手はその場のユーザーである。
• このスキルの成果物は合意メモだけとする。調査の流れで実装まで進めない。

手順

1. issue を取得する

gh issue view <番号> --comments

コメントに追加の議論や方針変更があれば、本文と同じ扱いで読む。

2. 意図と主張を分離する

本文とコメントの記述を 2 つに分類する。

• 意図: 何を望んでいるか、何に困っているか
• 主張: コードの現状、原因の分析、実装案、影響範囲の見立て

3. 主張をコードと突き合わせる

各主張について該当するコードを実際に読み、「一致」「乖離」「確認できず」に分類する。根拠のファイルパスを記録する。issue に書かれたファイルパスや行番号も、現物を開いて確認する。「確認できず」の主張は、次の手順で質問または仮定として扱う。

4. 合意メモの草案をユーザーに提示する

次の項目で短くまとめて提示する。長い報告にしない。

• 意図: issue が求めていること(出典: issue 番号)
• 検証済みの現状: コードで確認できた事実(出典: ファイルパス)
• 乖離: issue の記述と実態が食い違う点
• 質問: 答えがないと進められない項目。各質問に推奨案を 1 行ずつ付ける

乖離も質問もない場合は、「主張 n 件を確認し、すべて実態と一致」と明示して、そのまま合意の確認だけを取る。

5. ユーザーの回答を反映して合意メモを確定する

乖離がある場合、進め方はユーザーが決める。勝手に選ばない。

• issue の方針のまま進める
• 実態に合わせて方針を変える
• issue 自体を直してから進める(直す場合もユーザーの指示を待つ)

確定した合意メモは次の 4 項目で構成する。

• 意図
• 検証済みの現状(出典: ファイルパス)
• 仮定(出典なしで進めることにユーザーが同意した項目)
• 確定した決定(ユーザーの回答で決まった項目)

6. 実装へ引き継ぐ

合意メモを implementation-decision-discipline の入力として扱う。同スキルの階層の判定は合意メモを起点に行い、標準階層になった場合の Phase 0 は合意メモの検収だけで通過する。