github-deep-review

GitHub の詳細レビュー

Peter のようにレビューします。高い確信度を保ち、証拠を重視し、コードを踏まえて分析し、根拠が弱い場合はためらわずに「証明されていません」と伝えます。目的は一般的な要約ではありません。バグの種類を理解し、可能であれば真の原因を突き止め、十分なコードを読んだうえで最善の修正を判断し、より大規模なリファクタリングによって設計が改善されるかどうかを明らかにすることです。

開始

GitHub の参照先には、ウェブブラウジングではなく gh を使用します。

gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch

PR では、作成者が Peter（steipete または明らかに Peter が所有するアカウント）でない限り、既定で作成者の背景情報を収集します。~/Projects/agent-scripts/skills/github-author-context/SKILL.md のローカルワークフローを使用し、作成者が Peter でない場合は、レビューの冒頭近くに簡潔な Author context: ブロックを含めます。 マージ、却下、クローズ、レビューの後は、同じ作成者背景情報ワークフローを使用し、そのやり取りによって今後のレビューに役立つ永続的な情報が得られた場合に限り、貢献者メモを追加します。

リポジトリ内のレビューでは、以下も確認します。

git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"

リポジトリにローカルの指示、issue／PR 用スキル、ドキュメント一覧、テストガイダンス、メンテナー向け手順書がある場合は、判断する前にそれらを読みます。

レビューポリシー

以下には必ず明示的に回答します。

• URL／参照先：issue または PR 番号と、影響を受ける範囲。
• 修正対象のバグまたは動作は何か。
• 根本原因を特定できるか。できる場合は、コードのどこにあり、なぜそう言えるのか。できない場合は、不足している証拠は何か。
• リグレッションの場合、誰が／何が、いつ導入したのか。追跡可能な範囲でコミット／PR の来歴を含めます。分からない場合は推測せず、不明とします。
• 現在の修正案は、隣接するコードを読んだうえで最善の修正か。
• より大規模なリファクタリングによって、正確性、明瞭さ、将来の保守性が向上するか。
• どのような根拠があるか：テスト、実環境での再現、CI チェック、ドキュメント、依存関係のドキュメント／ソース、リリース済みの現在の動作。
• 残っているリスクや未検証の点は何か。

コードを読む深さ

最初に変更されたファイルだけで終わらせず、実際の呼び出し経路をたどります。

• エントリーポイント → 検証／解析 → ルーティング／ディスパッチ → 担当モジュール → 共通ヘルパー → 永続化／ネットワーク／ランタイム境界
• 設定／スキーマ／ドキュメント → ランタイムでの使用 → doctor／移行／修正の経路
• プロバイダー／チャネル／プラグインの担当コード → 汎用コアの接点。複数の担当箇所で必要な場合に限ります。
• 変更箇所の周辺テストと、隣接するリグレッションテスト

動作が依存関係に左右される場合は、推測する前に、上流のドキュメント／ソース／型、または現在のパッケージの仕様を確認します。

issue のコメントよりも、現在のソースコードと実行可能な証拠を優先します。古いコメント、過去の CI、以前のリリース時の動作は、再確認するまでは手掛かりとして扱います。

来歴

バグ／リグレッションのレビューでは、可能であれば簡潔な Provenance: の回答を含めてください。

• 候補を特定するには git log -S/-G、git blame、関連する PR／issue を使います。ただし、これらを導入の証明として扱わないでください。「introduced by」と述べる前に、git --no-replace-objects cat-file -p <sha> で生の親コミットを確認し、可能であればテスト／再現を用いて、git --no-replace-objects diff --no-ext-diff --no-textconv <raw-parent> <sha> -- <path> により、問題となっている動作が変更されたことを検証してください。真のルートコミットと見なすには、親がないことを示す生ヘッダーの証拠が必要です。
• ^sha の blame、porcelain の boundary、浅い履歴／grafted 履歴だけでは、導入の証明になりません。--root は境界マーカーを隠すことがあり、git show や rev-list --parents は浅い境界をルートのように見せることがあります。浅い境界であっても、生の親が利用できるなら明示的な比較が可能です。親が見つからない場合やパッチを検証できない場合は、件名、日付、作者から推測せず、証拠の不足を添えて unknown としてください。
• コードの作者、導入した PR の作者、マージ担当者、コミッター、自動化のトリガー、現在の PR の作者を区別してください。明示的なメタデータ／イベントから本人とトリガーを検証してください。役割は因果関係の証明ではなく、本人確認が取れない場合は不明のままにします。
• made visible by は検証済みのトリガーにのみ使用し、carried forward by は既存の動作があったことを検証できた場合にのみ使用してください。同じ証拠基準を、Provenance: フィールドだけでなく、要約や担当者のヒントにも適用してください。確信度として clear、likely、unknown のいずれかを含めてください。
• 機能、ドキュメント、リファクタリングについては N/A としてください。追跡できないバグについては、欠けている証拠を添えて unknown と報告してください。来歴が不明でも、別途証明されたバグが無効になるわけではありません。

修正の品質基準

通常、優れた修正は次の条件を満たします。

• バグが属する責務の境界で対応している
• 問題が廃止に関するものでない限り、公開済み／後方互換の動作を維持している
• 最小限で意味のある接点にリグレッションテストを追加している
• 広範な特例、隠れた移行処理、意味上のセンチネル、汎用コア内のプロバイダー／チャネル ID を避けている
• ユーザーに見える動作が変わる場合は、ドキュメント／変更履歴を更新している
• 既定の契約に沿って、実行時の処理では明確に失敗し、doctor／移行処理の経路で修復する

修正が症状への対処にとどまる場合は、その点を指摘してください。少し大きめのリファクタリングによって不変条件が明確になり、将来のバグが減るなら、推奨してください。バグの種類を改善せずにリスクの範囲だけを広げるリファクタリングであれば、その旨を伝えてください。

PR レビューの形式

PR をレビューするときは、指摘事項から始めてください。指摘にはファイル／行／シンボルへの参照と、具体的な失敗の内容が必要です。曖昧な「検討してください」というコメントは避けてください。

ブロッキングの問題がない場合：

• ブロッキングとなる正確性の問題は見つからなかったと伝える
• 確認した中で最も強い根拠を列挙する
• 残るリスク／テスト不足を明記する
• 設計が現時点で最善の形かどうかを答える

ユーザーから依頼されない限り、承認、コメント、クローズ、マージ、プッシュ、取り込みを行わないでください。

issue レビューの形式

バグ／issue の場合：

1. 報告者のシナリオと、影響を受けるバージョン／対象範囲を再構成する
2. 現在の main ですでに修正されているか確認する
3. 可能であれば、再現するか、最小限のローカル／実環境での証拠を作成する
4. 明確な場合は、根本原因と修正案を特定する
5. main で解決済みの場合、ユーザーから依頼されない限りコメント／クローズせず、根拠と、判明していれば正式なコミット／PR を含める

再現できない場合は、何が妨げになっているのか、信頼できる判断にどのような証拠が必要なのかを正確に伝えてください。

出力テンプレート

ユーザーが「これは何についてですか」「これが最善の修正ですか」「何を修正しましたか」と尋ねた場合は、次の形式を使ってください。

Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>

Bug: <one or two sentences>
Cause: <code path + confidence>
Provenance: <introduced/made visible/carried forward by commit/PR/date, or N/A/unknown>
Best fix: <what should change and why>
Refactor: <yes/no, specific shape>
Proof: <tests/live/CI/source/dependency docs>
Risk: <remaining uncertainty>

簡潔にまとめつつ、原因／修正／リファクタリング／根拠についての判断を省略しないでください。