PR の確認と報告

組み込みの code-review の結果に、Issue との整合、レビュースレッドの状態、CI を足して、Approve の判定、Merge の条件、短い説明を報告する。 報告はターミナルに出すだけで、GitHub、作業ツリー、ブランチ、stash を変えない。 PR の head はユーザーが前もってローカルに checkout しておき、skill はその作業ツリーのコードを読む。 skill 自身は checkout も fetch もしない。

引数: $ARGUMENTS

入力

書式は <PR番号> [--range <base>...<head>] [--level <low|medium|high|xhigh|max>] [資料 ...] とする。

• PR 番号が無ければ、この書式を示して止まる
• --level の既定は medium とする
• --range はローカルにすでにある参照で書く。 code-review の対象だけを狭め、説明、整合、スレッド、Merge の条件は PR 全体を対象にする。 範囲の head を git rev-parse した commit が PR の headRefOid と違うときは、古い範囲を見たおそれとして報告の「人が見る点」に書く
• 資料はファイルのパス、URL、チケットの ID で、いくつでも並べてよい。 要件の資料に加える

流れ

コマンドは references/commands.md にある。

1. PR の状態を取り、作業ツリーが PR の head かを確かめる。 head でなければ、PR の head を checkout してから呼び直すよう示して止まる。 PR を gh で読めなければ、gh のエラーを見せて止まる。 アカウントは切り替えない
2. Skill tool で code-review を args: "<level> <対象>" として呼ぶ。 <対象> は --range があればその範囲、無ければ PR 番号とする。 level は省かない
3. code-review がバックグラウンドで動いて起動したことだけを返したときは、完了の通知を待つ間に次の手順を進める。 同期で指摘が返ったときは、そのまま次へ進む。 code-review が git diff の失敗で終わったら、git のエラーを見せて止まり、報告を推測で埋めない
4. 差分、CI、Issue、スレッド、レビュー本文、会話欄のコメントを集める
5. 意図と照らす。 要件の資料 (「意図の取り方」) から要件と合否の基準を 1 件ずつ取り出し、それを満たすコードを作業ツリーで探して読み、満たしているか、満たしていないか、範囲外かを決める。 差分のうち、どの要件にも結び付かない変更は [要件に無い変更] として控える
6. 解決していないスレッド、レビュー本文、会話欄のコメントを、後の返信と、指摘の箇所を変えた commit を読んで分類する (「スレッドの状態」)
7. 説明の材料を集める。 変更したファイルと、その呼び出し元、呼び出し先、テストを作業ツリーで読み、変更がシステムのどこに載るかと、テストが何を守るかをつかむ。 差分と PR の本文だけから説明を書かない
8. code-review の指摘がそろうまで報告を書かない。 そろったら、指摘ごとに示されたコードを作業ツリーで読んで確かめる (「code-review の指摘の扱い」)
9. references/report.md の形で報告にまとめる。 意図との整合は手順 5、スレッドの状態は手順 6、説明は手順 7 から書き、対応が要るものと blocking でない指摘は手順 5、6、8 の結果を集めて書く

意図の取り方

エージェントが作った PR の本文は、作者の自己申告であり、何を頼まれたかの根拠にならない。 意図は PR の本文ではなく、Issue と、Issue が示す設計の文書から取る。

• 要件を定めるのは、closing キーワードで紐づいた Issue と、その Issue が設計の置き場所として示す文書である。 本文で #N と参照しただけの Issue は、本文もコメントも背景として読み、要件には数えない
• Issue が設計を PR に添付すると示しているときは、PR の作者が折りたたみのコメントとして付けた設計を要件の資料として読む
• 計画と、Issue が示していない設計は、要件に数えない。 説明を書く手がかりとして読み、要件と食い違う点は整合の節に [計画と要件の食い違い] として並べ、判定は要件に照らして出す。 Issue が示していない設計を要件にしたいときは、引数で渡された資料を使う
• PR の本文が Issue の範囲を明示しているときは、その範囲を受け入れる。 範囲から外した要件は blocking にせず、[範囲外] として並べる
• Issue の本文とコメントにあるリンクのうち、GitHub の Issue と PR、同じリポジトリのファイルは 1 段だけたどって読む。 外部のサービスのリンクはたどらず、[読んでいない資料] として挙げる
• 要件の資料を自分で探しに行かない。 読むのは、PR と Issue、そこから 1 段のリンク、引数の資料だけである
• Issue も引数の資料も無い PR は、PR の本文を仮の意図として使い、そのことを整合の節に書く。 何も見つからないときは推測で埋めず、「確かめる資料が無い」と書いて、判定を 人の判断が要る にする

判定

Approve の判定と Merge の条件は別々に出す。 draft を判定に混ぜない。

Approve の判定は次の 3 つのどれかにする。 2 つ以上に当たるときは 対応が要る を優先し、判断が要る点も並べて書く。

• Approve してよい: blocking の指摘が無く、解決していないスレッドは Nit や任意と明示されたものか、bot や自動のレビュアーのものだけである
• 対応が要る: blocking の指摘があるか、作者の対応を待つスレッドがある。 誰が何をするかを一覧にする
• 人の判断が要る: blocking の指摘は無いが、skill では決められない点がある。 次のものがこれにあたる
  • 要件の資料が見つからない
  • 要件に無い変更を受け入れるか
  • Issue や設計で決まったことへの異論
  • 「判断が要る」と「レビュアーの確認待ち」のスレッド

スレッドの分類との対応:

• [作者の対応待ち]: 対応が要る
• [判断が要る]: 人の判断が要る
• [レビュアーの確認待ち]: 人の判断が要る。 変更か返信を読み、指摘に応えているように見えるかを 1 行で添える。 resolve するかはレビュアーが決める。 対応が要るものの一覧には [レビュアー] として載せる
• Nit や任意と明示されたスレッドと、bot のスレッドは判定を変えない。 ただし、コードを読んで欠陥を確かめたものは 対応が要る にする

blocking にするのは次の 3 種類だけにする。

• 要件の資料が求めることを、PR が満たしていない
• 要件の資料に合否の基準があり、PR がそれに合わない
• 正しさの欠陥で、失敗する入力と誤った結果を具体的に示せて、コードを読んで確かめたもの。 code-review の指摘もこれに含める

次は blocking にしない: Nit、この PR より前からある問題、確かめきれなかった懸念、要件に無い変更、Issue や設計で決まったことへの異論。

Merge の条件は、CI の最新の結果、コンフリクトの有無、draft かどうか、必須の承認を満たしたかを示す。 表記は report.md に従う。

code-review の指摘の扱い

指摘ごとに、示されたコードを作業ツリーで読んで失敗の筋書きを確かめ、英語の指摘を日本語の 1 行に書き直す。

• 確かめた欠陥は blocking にする。 ただし、示された行を PR が変えておらず、失敗の筋書きにも PR の変更が関わらないものは、この PR より前からある問題として [既存] に並べ、blocking にしない
• 誤りと分かった指摘は報告に入れず、件数だけを書く
• 確かめきれなかった指摘は [懸念] として blocking でない指摘に並べる

スレッドの状態

• 解決済みのスレッドは件数だけを書く。 解決していないものは、次に誰が動くかで 3 つに分ける
  • [レビュアーの確認待ち]: 指摘に応える変更か返信があるが、resolve されていない
  • [作者の対応待ち]: 指摘に応える変更も返信も無い
  • [判断が要る]: 設計の判断や方針を問うていて、コードの変更では片づかない
• 対象は、レビュースレッド、COMMENTED と CHANGES_REQUESTED のレビュー本文、PR の会話欄のコメントである。 会話欄のコメントには resolve の状態が無いので、後の返信と commit から判定する。 レビュー本文は、同じレビュアーが後で APPROVED のレビューを出していれば解決済みに数える。 本文の空のレビューは、行コメントを送ったときにできるものなので数えない
• PR の作者自身のコメントは、レビュアーの指摘として数えない
• bot のスレッドと、レビュアーが Nit や任意と明示したスレッドは、未対応でも作者の対応待ちに数えず、blocking でない指摘に [bot] や [Nit] として並べる。 コードを読んで欠陥を確かめたものは、blocking として対応が要るものに載せる