iterate

Files (11)

• plugin.json · .claude-plugin/
• plugin.json · .codex-plugin/
• plugin.json · .plugin/
• README.md
• SKILL.md
• babysit.md · commands/
• iterate.md · commands/
• verify.md · commands/
• heuristics.md · references/
• verification.md · references/
• windows.md · references/

SKILL.md (first lines)

# /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.

```bash
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.

```bash
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:

```bash
gh pr ready --undo
```

## Step 2 — Poll CI checks

```bash
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:

```bash
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.

```bash
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):

```bash
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.

From OpenHands/extensions, MIT.

More from OpenHands/extensions