Awaiting PR Workflows

Overview

Wait for GitHub PR workflows to complete while correctly handling unpushed changes, commit correlation, and timing issues.

Core principle: Always verify local state before checking remote workflows. Under pressure, agents skip critical checks.

When to Use

Use this skill when you need to:

• Check if PR workflows have finished
• Verify CI status for recent changes
• Wait for workflows to complete before proceeding
• Handle requests like "are the tests passing?" or "wait for CI"

When NOT to use:

• PR doesn't exist and user hasn't asked to create one
• Just viewing PR status without concern for latest commits

Critical Checks (Always Perform These FIRST)

1. Check for Unpushed Local Changes

BEFORE checking workflow status, verify local/remote sync:

# Check if local branch has unpushed commits
git status

If unpushed commits exist:

Your branch is ahead of 'origin/branch-name' by N commits

Then ask user:

I found N unpushed commits on your local branch.
The PR workflows won't include these changes yet.

Would you like me to push them now? (y/n)

Never skip this check, even under time pressure.

2. Verify PR Exists

# Get current branch name
BRANCH=$(git branch --show-current)

# Search for PR by branch
gh pr list --head "$BRANCH" --json number,title

If no PR found, ask user:

No PR found for branch '$BRANCH'.

Would you like me to create one? (y/n)

3. Verify Commit Correlation

Always check which commits the workflows are testing:

# Get PR head commit
PR_COMMIT=$(gh pr view "$PR_NUMBER" --json headRefOid -q '.headRefOid')

# Get local HEAD commit
LOCAL_COMMIT=$(git rev-parse HEAD)

# Compare (show short SHAs for readability)
PR_SHORT=$(echo $PR_COMMIT | cut -c1-7)
LOCAL_SHORT=$(echo $LOCAL_COMMIT | cut -c1-7)

If commits don't match:

⚠️  Commit mismatch detected:
- PR is testing: $PR_SHORT
- Your local HEAD: $LOCAL_SHORT

The workflows are not testing your latest local changes.
[Proceed with step 1 - check for unpushed changes]

Waiting for Workflows

Step 1: Check if Workflows Have Started

# List recent workflow runs for the PR's head commit
gh run list --commit $PR_COMMIT --limit 5 --json status,conclusion,createdAt

If no runs found:

Wait up to 30 seconds (workflows may be queuing):

for i in {1..6}; do
  sleep 5
  RUNS=$(gh run list --commit $PR_COMMIT --limit 1 --json databaseId -q '.[0].databaseId')
  if [ -n "$RUNS" ]; then
    echo "Workflows started!"
    break
  fi
  echo "Waiting for workflows to start... ($((i*5))s elapsed)"
done

If still no runs after 30s:

⚠️  Workflows haven't started after 30 seconds.

This could mean:
- GitHub Actions is experiencing delays
- Workflows are disabled for this repo
- The commit hasn't triggered workflows

Would you like me to:
1. Wait longer (recommended if GitHub is slow)
2. Check workflow configuration
3. Stop waiting

Step 2: Wait for Workflows to Complete

First check if already complete, then poll with exponential backoff up to 20 minutes:

# Check if workflows are already complete
INCOMPLETE=$(gh run list --commit "$PR_COMMIT" --status in_progress,queued --json databaseId | jq 'length')

if [ "$INCOMPLETE" -eq 0 ]; then
  echo "✅ All workflows already complete!"
else
  # Wait with exponential backoff
  MAX_WAIT=1200  # 20 minutes in seconds
  INTERVAL=5     # Start with 5 seconds
  elapsed=0

  while [ $elapsed -lt $MAX_WAIT ]; do
    INCOMPLETE=$(gh run list --commit "$PR_COMMIT" --status in_progress,queued --json databaseId | jq 'length')

    if [ "$INCOMPLETE" -eq 0 ]; then
      echo "✅ All workflows complete!"
      break
    fi

    echo "⏳ $INCOMPLETE workflow(s) still running... (${elapsed}s elapsed, max ${MAX_WAIT}s)"
    sleep $INTERVAL
    elapsed=$((elapsed + INTERVAL))

    # Exponential backoff: 5s, 10s, 20s, 40s, then cap at 60s
    INTERVAL=$((INTERVAL * 2))
    if [ $INTERVAL -gt 60 ]; then
      INTERVAL=60
    fi
  done

  if [ $elapsed -ge $MAX_WAIT ]; then
    echo "⚠️  Workflows still running after 20 minutes."
    # Report current state and let caller decide what to do
  fi
fi

If timeout reached (20 min):

⚠️  Some workflows are still running after 20 minutes:

[List incomplete workflows with gh run list]

This is unusually long. Caller should decide whether to:
1. Wait longer
2. Proceed with current results
3. Check workflow logs for stuck jobs

Quick Reference

Common Mistakes

Skipping unpushed check under time pressure

• Problem: Reports stale workflow status, user confusion
• Fix: ALWAYS check git status first, even if "urgent"

Not correlating commits

• Problem: Report workflows for old commit as if they're current
• Fix: Always compare PR_COMMIT vs LOCAL_COMMIT

Giving up too early

• Problem: Reports "workflows not started" when they're just queuing
• Fix: Wait at least 30s for startup, 20min for completion

Not asking about push/PR creation

• Problem: Leaves user without next steps
• Fix: Always offer to push or create PR when needed

Rationalization Table

Red Flags - STOP and Check

If you catch yourself thinking:

• "They need results quickly, I'll skip git status" → NO. Always check.
• "The PR probably has the latest commits" → NO. Verify with commit SHAs.
• "No runs found, workflows must be disabled" → NO. Wait 30s first.
• "It's been 2 minutes, that's long enough" → NO. Max wait is 20 minutes.
• "I'll answer quickly without all the steps" → NO. Fast wrong answer helps nobody.

These are rationalizations. Follow the process.

Use Subagents to Save Context

IMPORTANT: This workflow involves waiting (up to 20 minutes) and produces minimal output.

Run in subagent using Task tool:

• Subagent does the waiting/polling
• Returns concise summary to main context
• Saves 150k+ tokens vs running in main session

Use the Task tool with subagent_type='general-purpose' and give them this skill.
They'll handle the polling and report back results.

Example Workflow

User: "Check if CI is passing for my PR"

[Run git status]
→ Found 2 unpushed commits

Me: "I found 2 unpushed commits. The PR workflows won't include
     these yet. Would you like me to push them now?"

User: "Yes"

[Run git push]
[Wait for workflows to start - 15 seconds]
→ Workflows started

[Poll every 30s for completion]
→ 3 minutes elapsed, workflows still running
→ 6 minutes elapsed, workflows complete

Me: "✅ All workflows complete for commit a1b2c3d:
     - Backend tests: PASSED
     - iOS tests: PASSED
     - Lint: PASSED"