what-iff: Skill for Claude Code

Watching a GitHub Actions run cheaply

gh run watch opens a long-lived connection and streams progress. That is expensive in an agent context: the output is large, mostly noise, and it cannot be interrupted cleanly to do something else. This skill polls instead — a handful of small gh api calls, each returning a few bytes.

Rules of thumb

• Ask for the smallest thing that answers the question. --jq runs server-side output through a filter locally, but the field selection is what keeps the response small; never fetch a whole run object to read one field.
• Poll on a curve, not a constant. CI jobs take minutes, so a 5-second poll is ~100 wasted requests. Start at 20s, grow to 60s.
• Only reach for logs after a failure, and only for the job that failed.
• Never poll without a ceiling. An infinite until loop against a hung run will spin forever.

1. Find the run

Prefer the exact commit — branch lookups race with new pushes and can return a run for a commit you did not make.

SHA=$(git rev-parse HEAD)
REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
RID=$(gh api "repos/$REPO/actions/runs?head_sha=$SHA&per_page=1" --jq '.workflow_runs[0].id')

Narrow to one workflow when several trigger on the same commit:

gh api "repos/$REPO/actions/runs?head_sha=$SHA&per_page=20" \
  --jq '.workflow_runs[] | select(.name == "E2E (mock backend)") | .id' | head -1

A freshly pushed commit may have no run for a few seconds. Poll for the run's existence the same way you poll for its completion, with the same ceiling.

2. Wait for it

One field per request, backing off, bounded:

DEADLINE=$(( $(date +%s) + 1800 ))   # 30 min ceiling — raise for slow suites
SLEEP=20
while :; do
  STATUS=$(gh api "repos/$REPO/actions/runs/$RID" --jq '.status')
  [ "$STATUS" = "completed" ] && break
  [ "$(date +%s)" -ge "$DEADLINE" ] && { echo "timed out waiting for $RID"; break; }
  sleep "$SLEEP"
  [ "$SLEEP" -lt 60 ] && SLEEP=$(( SLEEP + 10 ))
done
gh api "repos/$REPO/actions/runs/$RID" --jq '.conclusion'