pr-watch-auto

name	pr-watch-auto
description	This skill should be used when the user asks to 'PR push後にmergeまで監視して', 'CI通るまで自動で見て', 'pushしたPRをmergeまで面倒見て', 'watch this PR until merge', or wants a pushed pull request updated from origin/main, monitored through CI, repaired on failures or conflicts, pushed again, and watched until merge completion.
tools	["Bash(git *)","Bash(gh pr *)","Bash(gh run *)","Bash(bun *)","Bash(pnpm *)","Read","Edit","Write","Glob","Grep","TodoWrite"]

PR Watch Auto

Push 後の PR を、base 追従、conflict 解消、CI 監視、failure 調査、修正 push、merge 完了確認まで一気通貫で扱う。

MUST: PR が MERGED または CLOSED になるまで定期チェックを継続する。途中で監視を打ち切らない。CI pending 待ち・merge 待ち・外部ブロッカー待ちなど、次のアクションまで時間がかかる場合は ScheduleWakeup で定期チェックを予約し、merge 完了まで監視ループを維持する。

MUST: 最後に PR に変更を加えた時点（push / conflict 解消 / CI 修正 push）から最低 3 時間は監視を継続する。3 時間以内に MERGED にならなかった場合でも、3 時間経過するまでは定期チェックを打ち切らない。3 時間経過後かつ外部ブロッカー（reviewer 待ち・権限不足など agent が解決できない状態）が続いている場合に限り、ブロッカーの内容を報告して監視を終了してよい。

watch-pr との差分:

• watch-pr は PR 監視の判断基準と落とし穴をまとめた参照 skill。CI pending では ci-watcher に監視を委譲し、修正や再 push までを単一ループとして完結させるものではない。
• ci-watcher は background agent。CI と conflict 状態を観測して親 agent に返すだけで、base merge、conflict 解消、失敗修正、再 push、merge 待機は実行しない。
• pr-watch-auto は foreground orchestration。push 後に必要な git / gh 操作を連続実行し、状態が変わるたびに次の行動を選び直す。

事前状態の解決

1. 現在ブランチを取得する。
2. gh pr view --json number,url,baseRefName,headRefName,state,isDraft,mergeable,mergeStateStatus,autoMergeRequest,reviewDecision を実行する。
3. PR が見つからない場合は停止し、PR 作成または branch push が必要なことを報告する。
4. state が MERGED なら完了として停止する。
5. state が CLOSED なら merge されていないことを報告して停止する。
6. base branch は PR の baseRefName を優先し、取得できない場合だけ main を使う。

mergeable は push 直後に null になる。null の場合は 2 秒間隔で 3 回まで同じ gh pr view を再試行し、それでも null なら GitHub の計算待ちとして短く待ってからループ先頭へ戻る。

全体ループ

function pr_watch_auto():
  pr = resolve_pr()
  base = pr.baseRefName or "main"
  last_action = null

  loop until terminal:
    state = query_pr_state(pr)

    if state.state == "MERGED":
      report("PR merged", state.url)
      return

    if state.state == "CLOSED":
      report("PR closed without merge", state.url)
      return

    if state.mergeStateStatus in ["DIRTY", "dirty"]:
      resolve_conflicts_from_base(base)
      verify_merge()  // /verify-merge で意図しない変更混入を検出
      push_current_branch()
      last_action = "resolved_conflicts"
      continue

    if state.mergeStateStatus in ["BEHIND", "behind"]:
      merge_base_and_push(base)
      verify_merge()  // /verify-merge で意図しない変更混入を検出
      last_action = "merged_base"
      continue

    checks = query_pr_checks(pr)

    if checks.has_failed_required_check:
      investigate_and_fix_ci(checks)
      push_current_branch()
      last_action = "fixed_ci"
      continue

    if checks.has_pending_check:
      poll_checks_until_state_change(pr)
      last_action = "waited_ci"
      continue

    if state.isDraft:
      report("CI is green but PR is draft")
      return

    if state.reviewDecision == "CHANGES_REQUESTED":
      report("CI is green but review changes are requested")
      return

    if ready_to_merge(state, checks):
      ensure_merge_or_auto_merge(pr)
      wait_until_merged_or_blocked(pr)
      continue

    if last_action == "reported_blocked":
      schedule_wakeup_and_return()  // ScheduleWakeup で次回チェックを予約して一旦終了
    else:
      report_blocking_state(state, checks)
      last_action = "reported_blocked"

function schedule_wakeup_and_return():
  // merge されるまで定期チェックを継続する。
  // 待機理由に応じて間隔を選ぶ:
  //   CI pending 待ち → 60-270s（キャッシュ TTL 内）
  //   merge 待ち / 外部ブロッカー待ち → 1200s
  // ScheduleWakeup の prompt には pr-watch-auto skill の再実行指示を渡す。
  ScheduleWakeup(delay, reason, prompt)

Step 1: BEHIND 判定と origin/main merge

gh pr view の mergeStateStatus が BEHIND / behind の場合、または branch protection が up-to-date を要求している可能性がある場合は、base branch を merge してから push する。

git fetch origin <base>
git merge origin/<base>
# /verify-merge で意図しない変更混入がないか検証
git push

origin/main 固定を求められている場合は <base> を main として扱う。PR base が main ではない場合は、base の差異を報告してから PR の baseRefName を優先する。

Step 2: Conflict 自動解消フロー

mergeStateStatus が DIRTY / dirty の場合は、CI より先に conflict を解消する。GitHub Actions の pull_request workflow は conflict がある PR では dispatch されないため、gh pr checks を先に待ってはいけない。

function resolve_conflicts_from_base(base):
  run("git fetch origin " + base)
  result = run("git merge origin/" + base)

  if result exits cleanly:
    return

  conflicted = run("git diff --name-only --diff-filter=U")
  for file in conflicted:
    inspect ours, theirs, and base intent
    edit file to preserve branch intent and required base changes
    avoid whole-file --ours/--theirs unless the file is generated or lock-like
    run targeted verification for the touched area

  run("git add <resolved files>")
  run("git merge --continue")
  run("/verify-merge")  // 意図しない変更混入がないか検証

Conflict 解消では、機械的に片側を採用しない。ユーザー変更の目的、base 側の新しい契約、テストや型の期待値を合わせて確認する。判断不能な conflict だけユーザーに確認する。

MUST: conflict 解消後および base merge 後は、push する前に /verify-merge を実行する。merge resolution で意図しない変更（ブランチ側の変更消失・base 側の変更欠落・不整合な解消）が混入していないことを確認する。/verify-merge が問題を検出した場合は修正してから push する。

Step 3: gh pr checks で CI status をポーリング

Conflict がないことを確認してから CI を見る。

PROHIBIT: gh pr checks --watch — CI 完了を待つ間に PR の behind/conflict 状態変化を検出できないため。

以下を 30 秒から 60 秒間隔で繰り返す。

function poll_checks_until_state_change(pr_number):
  loop every 30-60 seconds:
    state = gh pr view {pr_number} --json state,mergeable,mergeStateStatus
    if state.state in ["MERGED", "CLOSED"]:
      return state
    if state.mergeStateStatus in ["DIRTY", "BEHIND"]:
      return state  // outer loop handles conflict/behind resolution

    checks = gh pr checks {pr_number}
    if all required checks passed:
      return {status: "ci_passed", checks: checks}
    if any required check failed:
      return {status: "ci_failed", checks: checks}
    // else: pending, continue polling

base branch が CI 実行中に更新されると、新しい conflict や behind 状態が発生するため、毎サイクル mergeStateStatus を確認し、CI 結果だけで merge-ready と判断しない。

Step 4: failure 時の調査・修正

CI failure を検出したら、失敗 check の名前、link、workflow を確認する。

gh pr checks <pr-number> --json name,state,bucket,link,workflow

GitHub Actions の run が分かる場合は、run summary と log を取得する。

gh run view <run-id>
gh run view <run-id> --log

調査後は、失敗原因に対応する最小差分を作る。修正がコード変更なら該当 package の local check を先に通し、コミットして push する。修正後はループ先頭へ戻り、conflict / behind / CI を再評価する。

function investigate_and_fix_ci(checks):
  failed = checks where state or bucket is failure-like
  for check in failed:
    read linked logs or run logs
    identify root cause
    edit minimal affected files
    run targeted local verification

  run("git status --short")
  run("git add <changed files>")
  run("git commit -m '<Japanese commit message>'")

外部サービス障害、権限不足、secret 不足、reviewer action 待ちなど、agent が修正できない failure は修正を作らずに blocking reason と next action を報告する。

Step 5: merge 完了まで監視

CI が pass し、draft ではなく、review / branch protection が merge 可能な状態なら、既存の auto-merge 設定を優先する。

1. autoMergeRequest が存在する場合は merge を実行せず、MERGED になるまで待つ。
2. merge queue が使われている場合は queue 状態を blocking として扱い、queue 内 CI の完了を待つ。
3. repository rules が agent による merge を求めている場合だけ、gh pr merge --squash または gh pr merge --squash --auto を実行する。
4. merge 実行後も gh pr view --json state,mergedAt,mergeCommit を polling し、MERGED を確認して完了報告する。

function wait_until_merged_or_blocked(pr):
  loop:
    current = gh_pr_view(pr, "state,mergedAt,mergeCommit,mergeStateStatus")
    if current.state == "MERGED":
      report("merge complete", current.mergeCommit)
      return
    if current.state == "CLOSED":
      report("closed before merge")
      return
    if current.mergeStateStatus in ["DIRTY", "BEHIND"]:
      return  // outer loop repairs it
    wait(60 seconds)

完了報告

最後に以下を短く報告する。

• PR URL
• 実行した更新: base merge、conflict 解消、CI failure 修正、再 push の有無
• 最終状態: MERGED、external blocker、または user decision required
• 実行した local verification と CI 結果

Bundled Resources

(No bundled resources found)