ci-watch

Inspect current CI state, identify the first real blocker, separate required failures from noise, and monitor until checks settle. Use when checks are failing, flaky, or blocking a merge.

SKILL.md

GitHub

ci-watch

Use for broken checks, flaky tests, or merge-blocking pipeline noise.

Phases

Phase 1 — Triage

  1. Identify the active PR or HEAD commit.
  2. List non-passing checks.
  3. Separate required failures from advisory noise.

Read PR state: gh pr view N --json mergeable,mergeStateStatus,reviewDecision,statusCheckRollup

Phase 2 — Diagnose

  1. Inspect the first failing required job deeply (logs, not just the summary line).
  2. Name the smallest fix — or the exact reason the failure is pre-existing / unrelated to the current change.

Phase 3 — Fix or Monitor

  1. If fixable: apply smallest fix, push, watch checks settle.
  2. If not fixable now: document the blocker and surface it as output.
  3. For checks that take >1 min to settle: use a Monitor until-loop rather than busy-waiting.

Output

BLOCKED — <job name>: <one-line cause>
  Fix: <smallest concrete action>
  Blocks shipping: yes / no

CLEAR — all required checks green

Reconciliation

CI WATCH — <PR/SHA>

Phase 1 Triage:   N failing checks (<X> required, <Y> advisory) ✅
Phase 2 Diagnose: root cause: <description> ✅
Phase 3 Fix:      <action taken> | (blocked: <reason>) ✅

Result: RESOLVED | BLOCKED (requires: <what unblocks it>)

PR state machine

mergeable / state Action
MERGEABLE + CLEAN proceed to merge
MERGEABLE + UNSTABLE non-required check failing; poll required-only checks
MERGEABLE + BEHIND gh pr update-branch or local rebase + force-push
MERGEABLE + BLOCKED check reviewDecision and branch protection
CONFLICTING + DIRTY local rebase first; if GH disagrees → webhook desync, close+recreate
UNKNOWN + UNKNOWN wait 15s, recheck; if STILL UNKNOWN try gh pr merge directly

Common gotchas

  • UNKNOWN often means the PR was already merged in another window.
  • mergeStateStatus: BLOCKED with no failing checks = review or branch protection.
  • PR head SHA disagrees with git ls-remote = webhook desync. Close + recreate.