babysit-pr

PR の見守り

目的

次のいずれかの最終状態になるまで、PR を継続的に見守ります。

• PR がマージまたはクローズされる。
• CI インフラの問題、再試行上限に達した後も繰り返し発生する不安定な失敗、権限の問題、安全に解決できない曖昧さなど、ユーザーの支援が必要な状況になる。
• 任意の引き継ぎマイルストーン：PR が現在、すべてのチェックに合格し、マージ可能で、レビュー上の未対応事項がない状態です。これは進捗状態として扱い、監視を停止する理由にはしません。PR がオープンである間は、後から届いたレビューコメントも速やかに通知します。

チェックがまだ保留中の状態で、単一のスナップショットが idle を返しただけで停止しないでください。

入力

次のいずれかを受け付けます。

• PR 引数なし：現在のブランチから PR を推測します（--pr auto）
• PR 番号
• PR URL

基本ワークフロー

1. ユーザーが PR の「監視」「ウォッチ」「見守り」を依頼した場合、単発の診断スナップショットを意図しているのでなければ、ウォッチャーの継続モード（--watch）で開始します。
2. ウォッチャースクリプトを実行して PR／レビュー／CI の状態をスナップショットします（または --watch からストリーム出力される各スナップショットを処理します）。
3. JSON レスポンスの actions リストを確認します。
4. diagnose_ci_failure が含まれている場合は、失敗した実行のログを調べ、失敗を分類します。
5. 失敗が現在のブランチに起因する可能性が高い場合は、ローカルでコードを修正し、コミットしてプッシュします。ランダムな不安定テスト、CI インフラ、依存関係の停止、ランナーの問題、その他ブランチに関係のない失敗は修正しないでください。
6. process_review_comment が含まれている場合は、通知された公開済みレビュー項目を確認し、対応するかどうかを判断します。
7. レビュー項目が対応可能で妥当な場合は、ローカルでコードを修正し、コミットしてプッシュします。その後、以下の GitHub 状態変更ポリシーで許可されている場合にのみ、関連するレビューのスレッドを解決します。
8. ユーザーが返信内容を明示的に確認していない限り、人間が作成したレビューコメント／スレッドに返信しないでください。人間によるレビュー項目が対応不要、対応済み、または妥当でない場合は、GitHub で返信するのではなく、その項目と推奨する返信内容をユーザーに提示します。
9. 失敗が不安定または無関係である可能性が高く、retry_failed_checks が含まれている場合は、--retry-failed-now を指定して失敗したジョブを再実行します。
10. 対応可能なレビューのフィードバックと retry_failed_checks の両方が含まれている場合は、レビューのフィードバックを優先します。新しいコミットによって CI が再実行されるため、レビューの変更を意図的に先送りするのでなければ、古い SHA のまま不安定なチェックを再実行しないでください。
11. 各ループで、CI の失敗やマージ可能性の状態に対応する前に、新たに通知されたレビューのフィードバックを確認します。その後、CI と並行してマージ可能性／マージ競合の状態（たとえば gh pr view を使用）を確認します。
12. プッシュまたは再実行の後は、直ちに手順 1 に戻り、更新された SHA／状態をポーリングし続けます。
13. パッチ／コミット／プッシュのために一時停止する前に --watch を使用していた場合は、プッシュの直後、同じターン内に自分で --watch を再起動します（ユーザーがスキルを再度実行するまで待たないでください）。
14. stop_pr_closed が表示されるか、ユーザーの支援が必要なブロッカーに達するまでポーリングを繰り返します。チェックに合格し、レビュー上の未対応事項がなく、マージ可能な PR は進捗上のマイルストーンであり、PR がオープンのまま監視を停止する理由にはなりません。
15. ターミナル／セッションの所有権を維持します。見守りが有効な間は、同じターン内でウォッチャーの出力を読み続けます。--watch プロセスを切り離して実行したままにし、監視が完了したかのようにターンを終了しないでください。

コマンド

単発スナップショット

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --once

継続監視（JSONL）

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --watch

不安定な再試行サイクルを開始（ウォッチャーが指示した場合のみ）

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --retry-failed-now

PR を明示的に指定

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr <number-or-url> --once

CI 失敗の分類

再実行を決める前に、gh コマンドを使って失敗した実行を調査してください。

• gh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha
• gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs -X GET -f per_page=100
• gh api repos/<owner>/<repo>/actions/jobs/<job-id>/logs > /tmp/codex-gh-job-<job-id>-logs.zip
• 全体のワークフロー実行が完了した後、代替手段として gh run view <run-id> --log-failed

gh run view --log-failed の対象はワークフロー実行全体であり、全体の実行が完了するまで、失敗したジョブのログを確認できない場合があります。迅速に診断するには、まず実行のジョブをポーリングし、特定のジョブが失敗したらすぐに、Actions のジョブログエンドポイントからそのジョブのログを直接取得してください。ウォッチャーには、GitHub が公開している場合、失敗した各ジョブの job_id と logs_endpoint を含む failed_jobs リストがあります。

失敗したジョブのログが変更されたコード（変更箇所におけるコンパイル／テスト／リント／型チェック／スナップショット／静的解析）を示している場合は、ブランチに起因する失敗として扱うことを優先してください。

ログに一時的なインフラや外部サービスの問題（タイムアウト、ランナーのプロビジョニング失敗、レジストリ／ネットワークの停止、GitHub Actions のインフラエラー）が示されている場合は、不安定または無関係な失敗として扱うことを優先してください。

ログから PR ブランチとの関連が明確に確認できない限り、テスト、ビルドスクリプト、CI 設定、依存関係のバージョン固定、またはインフラに関連するコードを変更して、不安定または無関係な失敗を修正しようとしないでください。不安定または無関係な失敗の場合、ウォッチャーが retry_failed_checks を推奨しているときに限り再実行してください。それ以外の場合は、待つか、ユーザーに支援を求めて中止してください。

分類が曖昧な場合は、再実行を選ぶ前に手動で一度診断してください。

簡潔なチェックリストについては、.codex/skills/babysit-pr/references/heuristics.md を読んでください。

レビューコメントへの対応

ウォッチャーは、次のレビュー項目を表示します。

• PR の issue コメント
• インラインのレビューコメント
• レビューの送信（COMMENT / APPROVED / CHANGES_REQUESTED）

公開済みのフィードバックにのみ対応してください。GitHub で PENDING 状態のレビュー送信と、それらの保留中レビューに紐づくインラインコメントは無視してください。保留中のレビューのフィードバックを既読としてマークしないでください。レビュー担当者がレビューを送信した後に表示対象となる必要があります。

Codex のレビューボットによるフィードバック（たとえば、chatgpt-codex-connector[bot] からのコメントやレビュー）も、人間のレビュー担当者によるフィードバックに加えて意図的に表示します。それ以外の無関係なボットのノイズは、引き続き無視してください。 安全のため、ウォッチャーが自動表示するのは、信頼できる人間のレビュー投稿者（たとえば、リポジトリの OWNER／MEMBER／COLLABORATOR と、認証済みの操作者）および Codex などの承認済みレビューボットからのものに限ります。 ウォッチャーの状態ファイルが新規の場合、未対応の公開済みレビューのフィードバックがすでに存在していれば、監視開始後に届いたコメントだけでなく、直ちに表示されることがあります。これは意図的な動作であり、すでに開いているレビューコメントを見落とさないためのものです。

コメントに同意し、対応可能な場合は、次の手順に従ってください。

1. ローカルでコードを修正します。
2. codex: address PR review feedback (#<n>) でコミットします。
3. PR のヘッドブランチにプッシュします。
4. プッシュが成功した後、以下の GitHub 状態変更ポリシーで許可されている場合に限り、関連する GitHub のレビュースレッドを解決します。
5. 新しい SHA で直ちに監視を再開します（プッシュを報告した時点で終了しないでください）。
6. --watch モードで監視していた場合は、プッシュ後、同じターン内ですぐに --watch を再起動します。ユーザーから再度依頼されるまで待たないでください。

人間が作成した GitHub のレビューコメントやスレッドに、自動で返信しないでください。人間のコメントに同意できない場合、対応不要または対応済みだと考える場合、あるいは質問への回答が必要な場合は、返信案を添えてユーザーに報告し、GitHub に何かを投稿する前に明示的な確認を待ってください。ユーザーが返信を承認した場合は、返信が自動投稿であり、人間のユーザーによるものではないと明確に分かるよう、[codex] を先頭に付けてください。 認証済みの操作者も信頼できるレビュー投稿者として扱われるため、ウォッチャーが後に承認済みの自分の返信を表示した場合は、すでに対応済みの項目として扱い、再度返信しないでください。 コードレビューのコメントやスレッドが GitHub ですでに解決済みとしてマークされている場合は、新たに未解決のフォローアップフィードバックがない限り、対応不要として安全に無視してください。

GitHub の状態変更ポリシー

監視に必要な PR の状態はすべて読み取れます。書き込みは、このポリシーに従う必要があります。

上記の説明に従って、レビュー対象のコードを更新したり、CI を再実行したりするために PR にプッシュできます。

監視を依頼した人間、または Codex のレビューボットからのレビュースレッドは解決できます。解決する際は、[from Codex]: を先頭に付けたコメントを残し、加えた変更と、それを含むコミットを説明してください。監視を依頼したユーザー以外の人間が参加しているレビュースレッドには触れないでください。

変更を行う前に、PR ウォッチャースクリプトの出力に頼らず、自分で PR の状態を取得してください。

明示的に依頼されていない限り、次のことは行わないでください。

• 他の人間のレビュースレッドにコメントせず、チャットでユーザーとやり取りしてください
• ユーザー以外の人間からのレビュースレッドを解決する
• ユーザー以外の人間とやり取りする
• PR をドラフトにしたり、レビュー準備完了にしたりする
• PR をクローズまたは再オープンする

一般に、他の人間から見える操作について、自分が行ったのかユーザーが行ったのか判別しにくくなるような形で GitHub 上で行動しないでください。判断に迷う場合は、チャットでユーザーに確認してください。

Git の安全性に関するルール

• PR のヘッドブランチでのみ作業します。
• 破壊的な Git コマンドは避けてください。
• 状況を把握するために必要な場合を除き、ブランチを切り替えないでください。
• 編集する前に、無関係な未コミットの変更がないか確認してください。ある場合は作業を中止して、ユーザーに確認してください。
• 修正が成功するたびにコミットして git push し、その後ウォッチャーを再実行してください。
• 修正のために実行中の --watch セッションを中断した場合は、同じターン内に git push した直後、すぐに --watch を再起動してください。
• 同じ PR／状態ファイルに対して複数の --watch プロセスを同時に実行しないでください。停止するか、意図的に再起動するまでは、ウォッチャーセッションを 1 つだけ維持して再利用してください。
• git push は最終結果ではありません。厳格な停止条件に該当しない限り、監視ループを続けてください。

コミットメッセージのデフォルト：

• codex: fix CI failure on PR #<n>
• codex: address PR review feedback (#<n>)

監視ループのパターン

実行中の Codex セッションでは、次のループを使用します。

1. --once を実行します。
2. actions を確認します。
3. まず、PR がすでにマージ済み、または何らかの理由でクローズ済みかどうかを確認します。そうであれば、その最終状態を報告し、直ちにポーリングを停止します。
4. CI の概要、新しいレビュー項目、マージ可能性／競合のステータスを確認します。
5. CI の失敗を診断し、ブランチに関連するものか、一時的なもの／無関係なものかを分類します。ワークフローの実行全体がまだ保留中でも、failed_jobs にすでに失敗したジョブが含まれている場合は、ワークフローの実行が完了するまで待たずに、そのジョブのログを取得してすぐに診断します。失敗がブランチに関連する場合に限り、修正します。
6. 別の作成者によるレビュー項目が表示されたら、対応可能な場合は修正してコミット／プッシュしたうえで、上記の GitHub 状態変更ポリシーで許可されている場合に限り解決します。対応できない場合、すでに対処済みの場合、または文章での回答が必要な場合は、自動投稿せず、推奨する回答とともにユーザーに提示します。後続のスナップショットに承認済みの自分の返信が表示された場合は、情報として扱い、再度返信せずに続行します。
7. 対応可能なレビューコメントと一時的な失敗の再実行がどちらもある場合は、一時的な失敗の再実行より先にレビューコメントへ対応します。レビューの修正にコミットが必要な場合は、それをプッシュし、古い SHA に対する失敗チェックの再実行はスキップします。
8. retry_failed_checks が存在し、かつレビュー／CI 修正コミットで現在の SHA を置き換える直前でない場合に限り、失敗したチェックを再試行します。CI を通過させるためだけに、無関係な一時的失敗やインフラストラクチャの障害に対するコード変更は行いません。
9. コミットをプッシュした場合、対象となるレビュー スレッドを解決した場合、または再実行を開始した場合は、その操作を簡潔に報告してポーリングを続けます（停止しません）。レビューコメントへの GitHub 上での文章による返信が必要な場合は、投稿前に停止して確認を求めます。
10. レビュー修正をプッシュした後は、厳格な停止条件にすでに達していない限り、同じターン内に継続的な監視（--watch）を積極的に再開します。
11. すべてのチェックが成功し、マージ可能で、必須のレビュー承認によってブロックされておらず、未対応のレビュー項目もない場合は、PR が現在マージ可能な状態であることを報告します。ただし、PR がオープンである間は、新しいレビューコメントをすぐに検出できるよう、ウォッチャーの実行は続けます。
12. ユーザーの対応が必要な問題（インフラストラクチャの停止、一時的な失敗の再試行上限、レビュアーの依頼が不明確、権限の問題）によってブロックされている場合は、その阻害要因を報告して停止します。
13. それ以外の場合は、以下のポーリング間隔に従って待機し、繰り返します。

ユーザーから PR の監視／ウォッチ／見守りを明示的に依頼された場合は、1 つのコマンドでポーリングを自動継続できる --watch を優先します。繰り返し --once でスナップショットを取得するのは、デバッグ、ローカルテスト、またはユーザーから単発の確認を明示的に依頼された場合に限ります。 ポーリングを続けるかどうかをユーザーに尋ねるために停止してはいけません。厳格な停止条件に達するか、ユーザーから明示的に中断されるまで、自動で続行します。 レビュー修正をプッシュした後、新しい SHA が作成されたというだけでユーザーに制御を戻してはいけません。ウォッチャーを再開してポーリングループに戻ることも、同じ見守りタスクの一部です。 --watch プロセスがまだ実行中で、厳格な停止条件に達していない場合、見守りタスクは進行中です。ターンを終了せず、ウォッチャーの出力をストリーミング／読み取り続けます。

ポーリング間隔

レビューのポーリングは頻繁に行い、CI が成功した後も監視を続けます。

• CI が成功していない間（保留中／実行中／キュー待ち、または失敗中）：1 分ごとにポーリングします。
• CI が成功した後：PR がオープンである間は、成功状態が長く続く場合の間隔を空けるのではなく、基本の間隔でポーリングを続け、新たに投稿されたレビューコメントをすぐに検出します。
• 何らかの変更（新しいコミット／SHA、チェックのステータス変更、新しいレビューコメント、マージ可能性の変更、レビュー判定の変更）があった場合は、直ちにポーリング間隔をリセットします。
• CI が再び成功しなくなった場合（新しいコミット、再実行、またはリグレッション）は、基本のポーリング間隔を維持します。
• いずれかのポーリングで PR がマージ済み、または何らかの理由でクローズ済みと判明した場合は、直ちにポーリングを停止し、最終状態を報告します。

停止条件（厳守）

次のいずれかに該当する場合にのみ停止します。

• PR がマージまたはクローズされた（ポーリング／スナップショットで確認した時点ですぐに停止します）。
• ユーザーの介入が必要で、Codex だけでは安全に続行できない。

次の場合はポーリングを続けます。

• actions に idle だけが含まれているものの、チェックがまだ保留中である。
• CI がまだ実行中またはキュー待ちである。
• レビュー状況に変化がないものの、CI が終端状態に達していない。
• CI は成功しているものの、マージ可能かどうかが不明または保留中である。
• CI は成功し、マージ可能であるものの、PR はまだオープンで、新しいレビューコメントやマージコンフリクトの変更がないか待っている。
• PR は成功しているものの、レビュー承認（REVIEW_REQUIRED／類似の状態）がないためブロックされている。この場合は基本の間隔でポーリングを続け、監視の継続について確認を求めずに、新しいレビューコメントがあれば報告します。

出力に関する要件

監視中は簡潔に進捗を報告し、最終的な要約には次の内容を含めます。

• 長時間にわたり変化がない場合は、ポーリングのたびに進捗をすべて報告するのを避け、状態の変化と、時折の状況報告だけにまとめます。

• push の確認、中間的な CI スナップショット、マージ可能になったことを示すスナップショット、レビュー対応の更新は、進捗報告としてのみ扱います。厳守の停止条件を満たさない限り、最終要約を出したり、監視を終了したりしないでください。

• ユーザーの「監視して」という依頼は、数回の試験的なポーリングだけでは満たされません。厳守の停止条件に該当するか、ユーザーが明示的に中断するまでループを続けてください。

• レビュー対応の修正コミットと push は完了ではありません。同じターン内で直ちにライブ監視（--watch）を再開し、進捗報告を続けてください。

• 現在の SHA に対する CI が初めてすべて成功した時点で、一度だけ祝福の進捗報告を行います（成功状態が続くポーリングのたびに繰り返さないでください）。推奨形式：🚀 CI is all green! 33/33 passed. Still on watch for review approval.

• ウォッチャーがまだ実行中の場合、厳守の停止条件が成立したことをウォッチャーが通知または確認するまでは、最終要約を送信しないでください。それまでは進捗報告を続けてください。

• 最終的な PR SHA

• CI の状態の要約

• マージ可能性／コンフリクトの状態

• push した修正

• 使用したフレーキー再試行のサイクル数

• 未解決の失敗またはレビューコメント

参考資料

• ヒューリスティクスと判断ツリー：.codex/skills/babysit-pr/references/heuristics.md
• ウォッチャーが使用する GitHub CLI／API の詳細：.codex/skills/babysit-pr/references/github-api-notes.md