explain-review-comments

PR に付いたレビューコメントを取得し、1件ずつ何を問題視しているかを噛み砕いて、変更案・影響・推奨と、次に自分で気づくための手がかりまで渡す。対応可否を判断できる状態にすることと、同じ指摘を繰り返さない知識が残ることの両方が目的。修正・返信・Resolve はしない。ユーザーが「レビューコメントを解説して」「何を言われているのか教えて」「/explain-review-comments」等を指示

SKILL.md

GitHub

PR に付いたレビューコメントを取得し、1件ずつ意図を噛み砕いて、対応可否を判断できる状態にします。

そこで終わりません。 レビューは指摘された本人にしか届かない学習の機会なので、次に自分で気づけるようになるところまでが範囲です。同じ指摘を2度受けるなら、1度目の解説が足りていません。

説明だけを行い、コードは書き換えません。GitHub 上での返信・Resolve もしません。

土台は responding_to_reviews.md

1件あたりの型はルールが持っています。 意図の咀嚼 → 現状のコード → 変更案 → 影響 → 推奨 → 対応可否を尋ねる、までがあちらの規定で、テンプレートも載っています。本スキルはそれを再定義しません。

本スキルが足すのは、複数件を横断で扱う手順です。

ルールが担う 本スキルが担う
1件をどう説明するか どれを対象にするか(取得・絞り込み・並び順)
変更案と推奨の出し方 件数が多いときの畳み方
尋ねて止まること 人間 / bot の判別と、その後の渡し先
— 学びとして残すこと(下記5)

対象

引数 挙動
省略 現在のブランチに紐づく PR の未解決コメント全件
PR 番号 / URL その PR の未解決コメント全件
+ --comment <コメント ID> その1件だけに絞る
+ --filter <絞り込み> 「人間のだけ」「 [must] だけ」等

ユーザーがコメント本文を直接貼った場合は、取得を飛ばしてその1件を扱う(ルールがそのまま適用される場面)。

進め方

1. コメントを取得する

3つの場所に散っています。 1つ見て終わりにしない。

gh api repos/OWNER/REPO/pulls/<PR>/comments      # インライン
gh api repos/OWNER/REPO/pulls/<PR>/reviews       # レビュー本文
gh api repos/OWNER/REPO/issues/<PR>/comments     # PR コメント欄
  • 並び順は created_at 昇順のまま維持する。 Conversation タブの並びと揃う( report_formatting.md )
  • /ai-review のようなコマンドコメントは除外する。 本文を trim してコマンド1行だけかで判定する( github_writing.md )。投稿者名では分けられない
  • 解決済みかどうかを見る。 既に Resolve されたスレッドは既定で対象外。ユーザーが「全部見せて」と言えば含める

2. 人間 / bot を判別する

その後の渡し先が変わります。 user.type == "Bot" で機械的に分ける。

投稿者 対応するときの渡し先
人間 /resolve-human-reviews(返信・Resolve はしない。対応表を会話で渡す)
bot /resolve-ai-reviews (返信と Resolve まで含む)

判別を文脈で行わない。 「AI っぽい書き方」で決めると、人間のコメントに返信する事故が起きます( responding_to_reviews.md )。

3. 1件ずつ、ルールの型で説明する

responding_to_reviews.md のテンプレートに従う。 指摘対象 / 問題視している点 / 提案 / 現状のコード / 変更案 / 影響 / 推奨。

まず pstack の in-your-own-words に従い、レビュアーが何を求めているかを自分の言葉で言い直す。そのうえで本スキルとして足すのは次の3点。

  • 指摘が現状のコードに当てはまるか確かめる。 レビュー後に push していれば、既に直っていることがあります。file:line は動くので、必ず今のコードを読む( verify_before_asserting.md )
  • セッションの文脈と照合する。 これまでのユーザー指示・実装判断・PR 本文の明記事項と抵触する指摘は、正論に見えても採らない選択がある。抵触を見つけたら、その旨を添えて判断を仰ぐ
  • 要点を file:line で指す( report_formatting.md )。抜粋が要るなら1件につき1個

噛み砕き方

レビュアーの文章をそのまま渡さない。 指摘は当人の語彙で書かれており、読み手が同じ前提を持っている保証はありません。

内部の呼び名を開く。 型名・関数名・SQL ファイル名をそのまま置かず、何をするものかを一言添える(「複数件をまとめて作る入口」「対象の行に鍵をかける」)。指摘の中の識別子も対象です。

「なぜ問題なのか」まで届かせる。 「〜すべき」だけでは判断できません。次のどれかを補う。

  • 今のままだと何が起きるか。 落ちるのか、気づかないうちにおかしくなるのか
  • 指摘どおりにすると何が変わるか。 副作用があるならそれも
  • なぜレビュアーがそう見たか。 前提が違うだけのこともある

観点が3つ以上並ぶなら表に畳む(指摘 / 現状 / 判断)。散文で書くと、1件が長くなって全体が読まれません( concise_first_then_detail.md )。

指摘の前提になっているコードを深く読む必要があるなら、/explain-code へ渡す。 ここで実装の解説を始めると、対応可否の判断がその下に埋まります。

4. 件数が多いときは畳む

5件を超えたら、先に一覧を出す。 全件を同じ厚さで書くと、読み手はどれが重いか分からなくなる。

手順 中身
まず一覧表 コメント ID / 投稿者種別 / 位置 / 指摘の要約 / 推奨(対応 / 見送り / 要判断)
次に個別の解説 「要判断」と重いものだけを厚く書く。自明なものは表の1行で足りる

並び順は取得順のまま。 重要度で並べ替えない。ユーザーは PR を開いて上から突き合わせます( report_formatting.md )。

5. 学びとして残す

ここが本スキルの中心です。 対応可否だけなら、ルールのテンプレートで足りています。

指摘1件は、その場の1箇所を直すためだけのものではありません。 レビュアーは自分の中の基準でコードを見ており、その基準は言葉にされないまま指摘の形だけで届く。基準のほうを渡さないと、次も同じ所で指摘されます。

次の3つを、対応可否とは別に添える。

渡すもの 何を書くか
背後にある一般原則 その指摘が何の具体例かを1行。「これは〜という判断の一例」
他にどこへ当てはまるか 同じ観点で見ると引っかかる箇所が今の差分や近くにあるか。grep で数えて、あれば file:line で挙げる
次に自分で気づく手がかり 何を見れば同じ判断ができるか。「この形を書いたら〜を確かめる」

2つ目は実際に探す。 「他にもあるかもしれません」では手がかりになりません。探して0件ならそう言う。それ自体が「今回だけの話」という情報になります。

既に規約がある指摘は、その場所を指す。 リポジトリの規約ドキュメントやルールに書かれているなら、指摘の内容を書き写すのではなく参照を渡す。規約があるのに指摘を受けたということは、読まれていないか、書き方が悪いか、規約側が古い。どれかを見立てて1行添える。

全部の指摘に付けなくてよい。 typo の指摘に一般原則はありません。「なぜそう見たか」を言葉で説明できるものだけに絞る。付ける件数は1回につき1〜3件で足ります。

6. 尋ねて止まる

対応可否はユーザーの領分です。 推奨は出しますが、決めるのはユーザー。

  • 選択肢が2つ以上あるなら AskUserQuestion で出す( decide_or_ask.md )
  • 勝手に修正へ進まない。 GO が出てから /resolve-human-reviews か /resolve-ai-reviews へ渡す
  • 返信要否を聞かない。 人間コメントへの返信はユーザーが判断する領分で、こちらから確認すること自体が侵入になる( responding_to_reviews.md )

出力の目安

件数 目安
1件 10〜20行。ルールのテンプレート + 学びを3行。図は要らない
2〜5件 1件ずつ、各10行程度
6件以上 一覧表 + 重いものだけ個別に。全件を厚く書かない

やってはいけないこと

  • コードを書き換えること。 説明だけを行う。修正は GO が出てから、対応スキルの担当
  • GitHub 上で返信・Resolve すること。 本スキルの範囲外( responding_to_reviews.md )
  • ルールのテンプレートを自前で再定義すること。 1件あたりの型は responding_to_reviews.md が持つ
  • 人間 / bot を文脈で判別すること。 user.type で機械的に分ける
  • コマンドコメントを解説対象に含めること。 本文が trim してコマンド1行なら除外する
  • 今のコードを読まずに書くこと。 レビュー後の push で既に直っていることがある
  • 推奨を出さずに「どうしますか」と丸投げすること。 判断コストをユーザーへ全部渡すことになる
  • 取得順を重要度で並べ替えること。 Conversation タブと突き合わせられなくなる
  • 対応可否だけ渡して終えること。 それはルールのテンプレートで足りている。次に自分で気づける形まで持っていく
  • 「他にもあるかもしれません」で済ませること。 実際に探して、件数か0件かを言う
  • 全件に一般原則を付けること。 言葉で説明できるものだけ。typo の指摘に原則は無い

関連

  • responding_to_reviews.md (レビューコメントの意図を先に噛み砕く): 土台。 1件あたりの型・テンプレート・尋ねて止まることはあちらが定める。本スキルは取得と横断、そして学びとして残すことを足す
  • responding_to_reviews.md (人間コメントへ返信しない): 返信と Resolve をしない根拠
  • /resolve-human-reviews / /resolve-ai-reviews (対応の実行): GO が出た後の渡し先。 本スキルは判断材料を揃えるところまで
  • /explain-code (実装の説明): 同じ explain 系。 指摘の前提になっているコードを深く読むならあちらへ渡す
  • report_formatting.md (報告に貼る識別子の書式): 一覧の並び順と file:line の書式はあちらが持つ
  • github_writing.md (コマンドコメントの別扱い): 取得時に除外する根拠