babysit-pr

PR ライフサイクルオペレーター

目的

PR の作成からマージ後の検証までを、手動での介入をできるだけ抑えて管理します。

最終的な状態：

• PR がマージされ、デプロイが正常に見えます。
• PR は安全にマージできる状態で、人による対応を待っています。
• ブロッカーに対してユーザーの支援が必要です。製品の意図が曖昧、権限がない、無関係な変更がワークツリーに残っている、外部サービスのみの障害、デプロイ状況を確認できない、といった場合です。

「PR を作成した」や「CI が一度成功した」だけで停止しないでください。最終的な状態のいずれかに該当するまで、PR の追跡を続けてください。

よくある失敗モード

実際の PR 自動化で発生する以下の落とし穴には、事前に対処する必要があります。

ウォッチャースクリプトが予期せず終了する（テンプレートの解決） プリフライト中に PR テンプレートの解決に失敗すると、ウォッチャーが予期せず終了することがあります。根本原因：resolve_pr_template.py がカスタムテンプレート構文を解析できない場合や、テンプレートファイルを読み取れない場合があります。対策：ウォッチャーの起動前に、必ずリゾルバーを --json モードで実行してテンプレートを検証してください。解決に失敗した場合は、同梱のデフォルトテンプレート assets/default_pr_template.md に切り替えてください。

同じ PR に複数のウォッチャーを実行する（コメントの重複） 同じ PR に対して複数の gh_pr_watch.py インスタンスを実行すると、コメントの処理が重複し、ボットコメントが重複したり、再試行の操作が競合したりする可能性があります。通常、前のセッションを適切に停止せずにウォッチャーを再起動すると発生します。対策：PR ごとにウォッチャーセッションを 1 つだけ使用してください。起動前に、残存プロセスがないことを次のコマンドで確認してください：ps aux | grep gh_pr_watch。再開する前に、古いセッションを停止してください。

CI の再試行ロジックが一時的でない失敗でも実行される（クォータの浪費） 再試行ロジックによって、実際には一時的でない失敗（例：ブランチ固有の問題による正当なテスト失敗）に CI の再試行予算が使われることがあります。これはクォータを浪費し、正当な問題への対応を妨げる可能性があります。対策：再試行する前に、必ず gh run view <run-id> --log-failed で CI ログを確認してください。その失敗が本当に一時的なものか、ブランチの変更とは無関係であることを確認してください。--retry-failed-now を呼び出す前に、references/heuristics.md に記載されたヒューリスティックを厳守してください。

Markdown の書式設定によりレビュー評価の抽出に失敗する レビュアーが評価の文言に Markdown の書式設定を使用すると（例：**4/5** stars や `4 out of 5`）、レビュー評価の抽出用正規表現が一致しないことがあります。その結果、ウォッチャーが明示された評価を見落とし、レビュアーからのフィードバックが未完了にもかかわらず、PR を早まってマージする可能性があります。対策：評価抽出機能は 5/5 や 5 out of 5 のようなパターンを検索します。レビュアーが評価を Markdown で囲んでいる場合は、数値の評価を手動で抽出し、先に PR のスレッドに記録してください。

防止策については、以下の各ワークフローセクションにある参照情報を確認してください。

デフォルト設定

• オープンな PR の状態を 60 秒ごとに確認します。
• PR ごとにウォッチャーセッションを 1 つだけ使用します。
• 一時的な CI の失敗を再試行する前に、正当なレビュー指摘の修正を優先します。
• レビュアーの評価が明示されている場合は、実際の要件として扱います。
• 同梱のデフォルト設定に切り替える前に、リポジトリ固有のテンプレートとシグナルを使用します。

プリフライト

1. デフォルトブランチではなく、PR ブランチにいることを確認します。
2. gh auth status が正常に動作することを確認します。
3. 編集する前に、無関係な未コミットの変更がないか確認します。
4. PR の本文を開いたり書き換えたりする前に、PR テンプレートを解決します。

PR テンプレートの処理

まずリゾルバースクリプトを使用します。

python3 skills/babysit-pr/scripts/resolve_pr_template.py --json

⚠️ 関連する注意点： よくある失敗モードの「Watcher Script Exits Silently (Template Resolution)」を参照してください。ウォッチャーを開始する前に、必ずテンプレートの解決を検証してください。

ルール：

• リポジトリにプルリクエストテンプレートがある場合は、セクション構成を維持し、内容をよく考えて記入してください。
• リポジトリにテンプレートがない場合は、同梱のフォールバック assets/default_pr_template.md を使用してください。
• 解決済みのテンプレートに沿った本文を用意し、gh pr create --body-file または gh pr edit --body-file を使用することを推奨します。
• 明らかに無関係で、空欄のままにすると誤解を招く場合を除き、チェックリスト項目を削除しないでください。

作成ワークフロー

1. テンプレートを解決します。
2. 簡潔な PR タイトルを作成します。
3. 概要、テスト、ロールアウトに関するメモを含む PR 本文を作成します。
4. ブランチをプッシュします。
5. PR を作成または更新します。
6. プッシュが成功したら、ただちにウォッチャーを開始します。

便利なコマンド：

gh pr create --base <default-branch> --title "<title>" --body-file <body-file>
gh pr edit <pr-number> --title "<title>" --body-file <body-file>
python3 skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --watch

ウォッチャーのワークフロー

ウォッチャーはスナップショットと推奨アクションを出力します。まず次を実行します。

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

⚠️ 関連する注意点： よくある失敗モードの「Multiple Watchers on Same PR」と「Watcher Script Exits Silently」を参照してください。開始前に古いウォッチャープロセスが実行されていないことを確認し、テンプレートの解決が正常に完了したことを検証してください。

主なアクション：

• process_review_comment：新しいコメントまたはレビューを確認し、現在のブランチにおいて妥当で、関連性があり、対応可能かを判断します。
• improve_review_score：信頼できるレビュアーから最高点を下回る明示的なスコアが付けられています。作業をまだ完了として扱わないでください。
• diagnose_ci_failure：失敗したログを確認し、その失敗がブランチに関連するものかを判断します。
• retry_failed_checks：失敗が不安定なもの、または無関係なものと思われる場合に限り、失敗したチェックを再実行します。
• stop_ready_to_merge：CI が成功し、未対応の信頼できるレビュー項目がなく、マージ可能な状態に問題がない場合に停止します。
• stop_pr_closed：PR がマージまたはクローズされた場合に停止します。マージされた場合は、デプロイ監視に移行します。
• stop_exhausted_retries：不安定な失敗に対する再試行回数の上限に達した場合は、証拠を添えてユーザーに支援を求めます。

CI 失敗時の方針

分類チェックリストには references/heuristics.md を使用してください。

⚠️ 関連する注意点： よくある失敗モードの「CI Retry Logic Triggers on Non-Flaky Failures」を参照してください。正当な失敗にクォータを浪費しないよう、再試行する前に必ずログを確認してください。

デフォルトのコマンド：

gh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha
gh run view <run-id> --log-failed
python3 skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --retry-failed-now

ルール：

• ブランチに関連する失敗：修正し、必要最小限で有効な検証を実行して、コミット、プッシュし、ウォッチャーを再起動します。
• 不安定な失敗または無関係な失敗：ログを一度確認し、一時的な失敗である可能性が高いと判断できた場合に限り、再実行します。
• インフラのみの問題、認証の問題、または権限不足：ブロッカーとして報告し、停止します。

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

信頼できる人間のレビュアーや承認済みボットからのフィードバックは、技術的に正しく、対応可能で、ユーザーの意図に沿っている場合に反映します。

新しいフィードバックがあった場合：

1. フィードバックが現在の PR に関連していることを確認します。
2. 対応が必要な場合は、正しく対応できる最小限の修正を実施します。
3. 対象を絞った検証を実行します。
4. コミットしてプッシュします。
5. ただちにウォッチャーを再起動します。

次のようなフィードバックは無視するか、エスカレーションしてください。

• すでに解決済み
• 明らかにノイズである
• 曖昧である
• 明示的なユーザーの指示と矛盾している
• 無関係な未コミットの変更、またはより広範な製品上の判断によって対応できない

レビュースコア

ウォッチャーは、信頼できるコメントやレビューから、5/5 や 5 out of 5 のような明示的なスコア表現を抽出するようになりました。

⚠️ 関連する注意点： よくある失敗モードの「Markdown の書式設定によってレビューのスコア抽出に失敗する」を参照してください。レビュアーがスコアを Markdown で囲んでいる場合は、作業を続ける前に評価を手動で抽出してください。

ルール：

• レビュアーが最高点を下回る明示的なスコアを付けた場合、PR を技術的にマージできる状態であっても、未完了の作業として扱ってください。
• PR を完了と判断する前に、最高スコアを目指してください。
• 改善を行った後は、スコアが上がったと決めつけず、レビュアーからの更新されたフィードバックを待ってください。

Git の安全性

• PR のヘッドブランチでのみ作業してください。
• 破壊的な git 操作は避けてください。
• 同じ PR に対して複数のウォッチャープロセスを実行しないでください。（よくある失敗モードの「同じ PR に対する複数のウォッチャー」を参照してください。）
• 無関係な未コミットのワークツリー変更を見つけた場合は、編集する前に作業を止め、ユーザーに確認してください。

マージ後のデプロイ監視

マージ後、デプロイウォッチャーを開始してください：

python3 skills/babysit-pr/scripts/gh_deploy_watch.py --pr auto --watch

デプロイウォッチャーは、GitHub のデプロイ記録と、マージコミットに関連付けられたデプロイ相当のワークフロー実行を使用します。次のいずれかのアクションで停止します：

• wait_deployment：デプロイシグナルが存在し、まだ実行中です。
• wait_for_deployment_signal：PR が最近マージされ、猶予期間がまだ終了していません。
• alert_deployment_failure：デプロイシグナルが失敗しました。ログを調査し、修正をリリースするか判断してください。
• validate_production：デプロイシグナルは成功したようです。必要性が最も高く、範囲を絞った本番環境の検証を実行してください。
• no_deployment_signal：猶予期間の終了後も、機械で読み取り可能なデプロイシグナルが見つかりませんでした。
• stop_pr_not_merged：PR はまだマージされていません。

プロバイダー固有のフォローアップ、スモークテスト、ログ、メトリクスのガイダンスについては、references/deployment-monitoring.md を使用してください。

出力に関する要件

• 通常の監視中は、進捗報告を簡潔にしてください。
• 修正をプッシュした場合は、根本原因と変更内容を要約してください。
• 停止する際は、終了条件とその根拠を報告してください。

参考資料

• references/heuristics.md
• references/github-api-notes.md
• references/deployment-monitoring.md