Monitoring Pull Requests

Pull Request CI Monitor

Introduction

Watch the CI for a pull request, and when something fails, fix it the careful way: reproduce the failure locally before changing anything, validate the fix locally before pushing, and retry up to 5 times. If 5 fix attempts still leave the PR red, revert every fix-attempt commit — with the user's approval — and hand back the PR in its original state; five failed attempts is a strong signal the changes are misguided.

Push-without-local-reproduction is allowed only when the failure cannot be reproduced locally (genuine CI-only divergence). Never push a speculative fix when local reproduction is possible.

This skill is project-agnostic: it discovers how to reproduce CI failures from the project's own context (workflow definitions, AGENTS.md/CLAUDE.md/CONTRIBUTING.md, Makefile/Taskfile/justfile, package.json scripts, pyproject.toml/tox.ini, pre-commit config) rather than assuming a fixed toolchain.

Execution Mode

This skill is designed to run as a background agent, not in the user's foreground turn. CI commonly runs for tens of minutes, and a fix-and-retry loop multiplies that by up to 5 iterations. Blocking the parent conversation that long is wasteful — spawn this skill as an asynchronous agent and let it report back when it has something to say.

• Recommended invocation: by another skill (notably pr Phase 7) using the runtime's background-agent primitive (Claude Code: Agent with run_in_background: true; equivalent in other runtimes).
• Acceptable invocation: directly by the user as /monitoring-pull-requests when they explicitly want to watch a PR. In that case the loop runs in the foreground and the user can interrupt.
• The skill is self-contained: it captures baseline_commit itself in Phase 0 and resolves the PR/branch from arguments or current branch. No state needs to be inherited from the spawning conversation beyond what is passed in $ARGUMENTS.

Arguments

<arguments> $ARGUMENTS </arguments>

Supported arguments:

• (no args) — Use the PR for the current branch.
• <PR-number> — Use the PR with that number on the current repo.
• <PR-URL> — Use the PR at that GitHub URL.

State

Maintain these variables throughout the run. Track them in your scratch space; they drive the retry/revert logic.

iteration            = 0
max_iterations       = 5
pr_number            = <resolved in Phase 0>
branch               = <resolved in Phase 0>
baseline_commit      = <HEAD on the branch when the skill starts — the revert target>
fix_commits          = []     # SHAs created by this skill while attempting fixes
ci_resolved          = false
attempt_log          = []     # One entry per iteration

Every fix attempt produces exactly one new commit on the branch, appended to fix_commits. This is what makes the Phase 6 revert deterministic.

Phase 0: Resolve Target PR & Baseline

1. Move to the repo root:

   cd "$(git rev-parse --show-toplevel)"

   If this fails, STOP — not inside a Git working tree.

2. Resolve the PR. Determine pr_number and branch:

   • If $ARGUMENTS looks like a number → pr_number = $ARGUMENTS.
   • If $ARGUMENTS looks like a URL → extract the number with gh pr view "$ARGUMENTS" --json number -q .number.
   • Otherwise → pr_number = $(gh pr view --json number -q .number) for the current branch. If no PR exists, STOP and tell the user to open one (or run /pr first).

   Then capture metadata:

   gh pr view <pr_number> --json number,headRefName,headRefOid,baseRefName,state,isDraft,mergeable,statusCheckRollup

   • branch = headRefName (and keep headRefOid at hand — step 4 verifies the local baseline against it)

3. Check out the PR branch locally (if not already):

   git fetch origin
   git checkout <branch>
   git pull --ff-only origin <branch>

   If git pull is not fast-forward, STOP and tell the user the local branch has diverged from origin — they need to reconcile first.

4. Record baseline_commit as the current HEAD. This is the local revert target if all 5 iterations fail:

   baseline_commit=$(git rev-parse HEAD)

   Verify it matches headRefOid from step 2. If they differ, STOP — the branch is out of sync with the PR head and any revert would lose work.

5. Refuse to operate on long-lived branches. If branch is the repository's default branch (git symbolic-ref --short refs/remotes/origin/HEAD), a long-standing integration branch (main, master, stable, develop, dev, trunk), or a release branch (release/*, release-*, version-named branches), STOP. This skill is for feature PRs only.

6. Discover the project's local toolchain (used by Phases 2–4). Read whatever project context exists — AGENTS.md/CLAUDE.md/CONTRIBUTING.md, Makefile/Taskfile/justfile, package.json scripts, pyproject.toml/tox.ini, .pre-commit-config.yaml — and note:

   • The lint/format gate (the command developers run before pushing).
   • The test runner(s) and how to target a single test.
   • Any code-generation steps whose outputs are checked in (GraphQL schemas, OpenAPI clients, protobufs, generated SDKs) — CI often fails when these are stale.

7. Report to the user: PR number, title, branch, baseline commit short SHA, current statusCheckRollup summary (counts of pending/success/failure). Then proceed.

Phase 1: Monitor CI

The goal of this phase is to discover whether the CI is currently passing, failing, or still running — and to wait through "still running" states.

1. Find the most recent CI run for the branch:

   gh run list --branch <branch> --limit 10 --json databaseId,name,status,conclusion,event,headSha,createdAt

   Filter to runs whose headSha matches the current branch tip. If multiple workflows ran for the same SHA, look at all of them — the PR is only green if every required check is green.

2. Wait for in-flight runs to settle. While any run for the current SHA has status other than completed:

   • Poll every 60 seconds: gh run list --branch <branch> --limit 10 --json databaseId,status,conclusion,headSha. Where available, prefer a single blocking gh run watch <run-id> over polling.
   • Be patient — CI can take 30+ minutes on repos with heavy integration or end-to-end suites.
   • If nothing has appeared after 5 minutes from a fresh push, investigate whether the push triggered a workflow at all (gh run list --branch <branch> --limit 5). Stalled webhooks happen.

3. Once all runs for the SHA are completed:

   • If every run's conclusion == success (or skipped for legitimately skipped jobs) → set ci_resolved = true, go to Phase 5.
   • If any conclusion in {failure, cancelled, timed_out, action_required} → go to Phase 2.

4. If iteration == 0 and CI is already green when the skill is first invoked: report this to the user and exit cleanly. Nothing to do.

Phase 2: Classify Failures

For each failed run, list its failed jobs and work out how to reproduce each one locally.

Failure outside the PR's diff — don't trust a stale "commits behind" count. A failure in a file or config the PR's diff doesn't touch may be inherited from the base — but the "how far behind" distance is a snapshot, not a durable property. It can go stale the moment the base gets fixed, including while you're escalating or waiting on a reviewer reply — a branch that was genuinely 0 commits behind an hour ago is not proof it still is now.

• Re-fetch and recompute immediately before deciding, never reuse a distance computed earlier in the session: git fetch origin && git rev-list --count HEAD..origin/<base-branch>.
• Reproduce against the base's current tip, not the branch's original merge-base — if the failure is gone there, a rebase is the fix, not an escalation.
• A reviewer's "this needs a rebase" is a cue to re-verify, not a claim to argue against with a distance computed earlier — that number may no longer be true.
• Cite a specific run, not an impression. To prove a failure predates your branch, find a run of the same job on the base branch (gh run list --branch <base-branch> --json databaseId,conclusion,headSha,createdAt) and confirm it failed the same way — a concrete run ID beats an inferred "probably pre-existing."
• To test whether your own commit caused a failure without burning the run, re-run the failed job on the same SHA (gh run rerun <run-id> --failed) instead of pushing a fix-attempt commit first — a workflow with concurrency: cancel-in-progress: true cancels the very run whose outcome would answer the question.

1. List failed jobs for each failed run:

   gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion=="failure") | {name, databaseId, conclusion}'

2. Classify each failed job into a track. Read the workflow definition that ran the job (under .github/workflows/) to see the exact commands CI executed, then map the job onto one of these tracks:

   Track	Typical job names	Local reproduction strategy
   lint	lint, pre-commit, format, static analysis	Re-run the specific failing hook/rule on the specific failing files (Phase 3.lint)
   test	unit tests, integration tests	Re-run the exact failing test case(s) with the project's test runner (Phase 3.test)
   build	build, compile, typecheck, packaging	Re-run the project's build/typecheck command (Phase 3.build)
   e2e	e2e, acceptance, browser tests, anything needing heavy infrastructure	Target the single failing test; never the full suite (Phase 3.e2e)
   other	publish, release, deploy, bots, unfamiliar workflows	Read logs and ask the user before guessing

   The local-equivalent command for each track comes from the toolchain discovered in Phase 0 step 6 and from the workflow file itself — when in doubt, run locally exactly what CI ran, narrowed to the failing case.

3. Pull the failing log lines for every failed job. Don't dump the whole log; extract the failing test/check:

   gh run view <run-id> --log-failed > /tmp/monitoring-pull-requests-failed-<run-id>.log

   Grep for the runner's failure markers (e.g. FAILED/ERROR for pytest, FAIL for vitest/jest/go test, error[ for compilers) — those give the exact test IDs, hook names, or file/rule pairs to reproduce.

4. Always reproduce as narrowly as possible. The goal is the smallest local invocation that exercises the failing case, not a full-suite re-run. A run targeting one test finishes in seconds; a full suite can take many minutes. Narrow runs are also clearer to debug — less noise in the output. Concretely:

   • Pull the exact failing test IDs / file paths / hook names from the log first. Don't fall back to a broad suite while there are specific names to try.
   • If the first narrow command fails to reproduce or the test ID was wrong (typo, parametrized name not matched), try a slightly broader form — drop the parameter suffix, then step up to the file, then the directory. Widen one notch at a time, never jump straight to the full suite.
   • Only fall back to the full-suite invocation as a last resort, and only after at least two narrowed attempts didn't pinpoint it. Note the fallback explicitly in attempt_log.
   • Once the fix is in, re-run the narrow command first to confirm the fix; you may then run the broader suite as a regression check before pushing — but keep the reproduction step narrow.

5. Decide the order of attack. Fix one failure per iteration. Prefer the cheapest one first (lint < test < build < e2e), because lint failures often mask deeper issues and are fast to fix. Record the chosen target in attempt_log for this iteration:

   attempt_log[iteration] = {
       failing_jobs: [<list of job names that failed>],
       target_job:   <the one being fixed this iteration>,
       target_node:  <test id or hook name being reproduced>,
       failure_excerpt: <a few key log lines>,
   }

Phase 3: Reproduce Locally and Fix

Hard rule: never push a speculative fix when local reproduction is possible. Reproduce first, then fix, then re-verify locally, then push.

The reproduction strategy depends on the track. Pick the matching subsection. In every subsection, the concrete commands come from the project's own toolchain (Phase 0 step 6) — the examples below illustrate the narrowing pattern, not a required tool.

3.lint — Lint / Format / Pre-Commit

Narrow first: run only the hook(s) or rule(s) that failed, on only the file(s) they flagged.

1. From the failed-job log, identify the specific hook/rule id and the file paths it complained about.
2. Reproduce that check in isolation against just those files — e.g. with pre-commit: pre-commit run <hook-id> --files <file1> <file2>; with a direct linter: point it at the flagged files only.
3. If the narrow run doesn't reproduce, widen one notch — the same check across all files.
4. Only as a last resort, run the project's full lint/format gate the way CI runs it.
5. If the failure reproduces:
   • Read the failing rule/file.
   • Apply the minimal fix — formatter auto-fixes are fine; for type errors, fix the actual type.
   • Re-run the same narrow command to confirm. Then run the full gate once before pushing as a regression check.
6. If the failure does not reproduce even at the broadest local invocation (rare for lint, but possible — version drift, OS-specific): document this in attempt_log and proceed to Phase 4 with a best-effort fix. Note the unreproduced status.