/iterate

name: iterate
description: >-
  Iterate on a GitHub pull request — drive it through CI, code review, and QA
  until it is merge-ready. Poll verification layers with `gh` CLI, diagnose
  and fix CI failures, address review feedback, retry flaky checks, push
  fixes, and repeat. The agent is the orchestration loop.
triggers:
- /iterate
- /verify
- /babysit

/iterate — Drive a PR to Merge-Ready

Iterate on a pull request until it passes all verification layers. You push, poll, fix, and push again — the loop only ends when the PR is green or a blocker requires human help.

No scripts — you are the orchestration loop. Uses only standard `gh` CLI commands that work on any GitHub repo.

Requires: `gh` CLI authenticated with repo access, a PR branch. Windows PowerShell equivalents for Bash-only assignment, redirection, and quoting patterns in this skill are in `references/windows.md`.

Discover what the repo has

Not every repo has all three verification layers. Before entering the loop, check which ones exist. Only poll layers that are actually set up.

gh workflow list --json name --jq '.[].name'

• **CI checks** — almost every repo has these. If `gh pr checks` returns results, CI is present.
• **PR review bot** — look for a workflow named like "PR Review" or "pr-review" in the output above, or check for `.github/workflows/pr-review*.yml` in the repo. If it's not there, the repo doesn't have automated PR review. Skip step 3 entirely.
• **QA bot** — look for a workflow named like "QA" or "qa-changes". If it's not there, the repo doesn't have automated QA. Skip step 4 entirely.

A repo might have only CI. Or CI + review. Or all three. Your "all passed" condition is: every *present* layer is green. Don't block waiting for layers that don't exist.

The loop

1. Push and ensure a draft PR exists. 2. Poll each present verification layer. 3. Decide: all passed? fix needed? wait? 4. If fix needed — fix, refresh any `.pr/` artifacts affected (see below), commit, push, re-request review from bots, go to 2. 5. If waiting — sleep per polling cadence, go to 2. 6. If all present layers passed on the *current* SHA — mark PR ready, done.

IMPORTANT: pushing a fix is NOT the end. After every fix+push you MUST re-request review from the review bot (if present) and go back to step 2. The loop only ends when the verifiers pass on your latest SHA. Addressing feedback and pushing a commit is just one iteration — the bot needs to review the new code too.

Do not stop to ask the user whether to continue polling; continue autonomously until a strict stop condition is met or the user interrupts.

Step 1 — Push and ensure PR exists (as draft)

Create the PR as a draft. This prevents repo automations (merge workflows, artifact cleanup, auto-merge) from triggering while you're still iterating. You mark it ready only after all verification layers pass.

git push origin HEAD
gh pr create --fill --draft 2>/dev/null || true
gh pr view --json number,url,headRefOid,isDraft --jq '"\(.number) \(.url) \(.headRefOid) draft=\(.isDraft)"'

If the PR already exists and is not a draft, convert it:

gh pr ready --undo

Step 2 — Poll CI checks

gh pr checks --json name,state,bucket --jq '
  { passed:  [.[] | select(.bucket=="pass")]  | length,
    failed:  [.[] | select(.bucket=="fail")]  | length,
    pending: [.[] | select(.bucket=="pending")] | length }'

• Zero failed, zero pending → CI green.
• Any pending → wait and re-poll.
• Any failed → diagnose (see "CI failure classification" below).

To inspect a failure:

SHA=$(gh pr view --json headRefOid --jq .headRefOid)
gh run list --commit "$SHA" --status failure --json databaseId,name,conclusion \
  --jq '.[] | "\(.databaseId)\t\(.name)\t\(.conclusion)"'
gh run view <run-id> --log-failed

Step 3 — Poll PR review (if present)

Skip this step if the repo has no review bot.

gh pr view --json reviews --jq '
  [.reviews[] | select(
    .authorAssociation == "OWNER" or
    .authorAssociation == "MEMBER" or
    .authorAssociation == "COLLABORATOR" or
    (.author.login | test("openhands|all-hands-bot"; "i"))
  )] | last | { state: .state, reviewer: .author.login, body: .body[0:300] }'

• `APPROVED` → review passed.
• `CHANGES_REQUESTED` → read the body and inline comments, fix code.
• `COMMENTED` → may have actionable suggestions; read and decide.
• No matching review yet → bot may still be running; wait and re-poll.

Inline review comments (when changes requested):

gh api "repos/{owner}/{repo}/pulls/{number}/comments" \
  --jq '.[] | select(.user.login | test("openhands|all-hands-bot"; "i"))
        | { path: .path, line: .line, body: .body[0:200] }'

On a fresh iteration, existing pending review feedback should be checked immediately — not only comments that arrive after monitoring starts. Already-open review comments must not be missed.

Step 4 — Poll QA report (if present)

Skip this step if the repo has no QA bot.

QA reports are PR issue comments with a status line like `Status: PASS`.

gh api "repos/{owner}/{repo}/issues/{number}/comments" --paginate \
  --jq '[.[] | select(
    (.user.login | test("openhands|all-hands-bot"; "i")) and
    (.body | test("Status:\\s*(PASS|FAIL|PARTIAL)"; "i"))
  )] | last | { author: .user.login, body: .body[0:500], url: .html_url }'

• `PASS` → QA passed.
• `FAIL` → read details, fix code.
• `PARTIAL` → some passed, some failed; read details.
• No QA comment yet → bot may still be running; wait and re-poll.

Step 5 — Decide and act

For each present layer, check its status. If a layer is not present in the repo, treat it as passing.

• All present layers green on current SHA → done.
• CI failed → fix code, or rerun if flaky (see below).
• Review requested changes → read comments, fix, push.
• QA failed/partial → read report, fix, push.
• Anything still pending → sleep per polling cadence, re-poll.
• PR closed/merged → stop.