Iterate PR

Iterate on PR Until CI Passes

2.4.0 - fetch_pr_feedback.py no longer reports an empty result as a successful fetch. Every path where a feedback channel could come back empty because the request did not actually deliver now fails loudly, and a server-side count probe backstops any path not yet known. See Fetch Integrity.

Continuously iterate on the current branch until all CI checks pass and review feedback is addressed.

Requires: GitHub CLI (gh) authenticated.

Requires: Python 3.9+.

Important: Run scripts from the repository root directory (where .git is located).

Running the Bundled Scripts

Skills live in .agents/skills/ - that is the canonical path, and the only one used in this document. Some repos also expose .claude/skills as a symlink to it, but that symlink is not guaranteed: it does not survive a Windows checkout with core.symlinks=false, and not every repo carries it. Always invoke via .agents/.

Every script below accepts either runner - they only use the standard library, so no dependency installation is needed either way:

• Preferred: uv - uv run <script>. Faster startup, isolated from system Python.
• Fallback: python3 <script> - used automatically when uv is not on PATH.

Before running any script command shown in this skill, check for uv first and prefer it; fall back to python3 only if uv is unavailable:

if command -v uv >/dev/null 2>&1; then
  uv run .agents/skills/iterate-pr/scripts/<script>.py [args]
else
  python3 .agents/skills/iterate-pr/scripts/<script>.py [args]
fi

The rest of this document shows invocations in the shorter python3 <script> form for readability - substitute uv run per the rule above whenever uv is available.

Reading Script Output - Mandatory Gate

fetch_pr_feedback.py and fetch_pr_checks.py both emit a single JSON object with a top-level status field, and both exit non-zero on failure.

Check status before reading any other field. A failed lookup is not a clean PR. Do not pipe these scripts through anything that discards the exit status, and never infer "no feedback" or "checks passed" from an absent count - on failure the counts are null, not 0, precisely so that the two cases cannot be confused.

Fetch Integrity

The failure this skill guards against hardest is the silent one: reporting a clean PR because the feedback never arrived, rather than because there was none. A run that merges on that basis merges unreviewed code, and nothing in the output says so.

fetch_pr_feedback.py reads three independent channels - inline review threads (GraphQL), PR conversation comments (REST), and review bodies (REST). Each is treated as a channel that must deliver, not merely return:

• gh exiting non-zero is an error, never an empty channel.
• gh exiting 0 while writing nothing is an error too. An undelivered response and an empty one are indistinguishable downstream, so they are not allowed to look alike here.
• A payload of unexpected shape is an error, not an absence.
• Count probe backstop: if any channel does come back empty, the script asks GitHub how many records that channel actually holds. If the server says there are records and the fetch produced none, the script fails with the channel named and both numbers shown.

The probe costs one small extra query and only runs when a channel is already empty, so a genuinely quiet PR reports status: "ok" with zero counts and no extra cost on the common path. A PR with real feedback can no longer report zero.

Invocation and Modes

Invoke as:

• /iterate-pr
• /iterate-pr --merge (alias: full)
• /iterate-pr --release
• /iterate-pr --merge --release (alias: full-release)

In Claude Desktop, arguments are hints, not strict CLI parsing. Treat whatever follows /iterate-pr as a mode hint string.

full and full-release are the positional spellings this skill used before 2.3.0 and are still what several callers' standing instructions say. They are exact synonyms for --merge and --merge --release. Both spellings are supported and must stay supported: a caller who types full is asking for an autonomous merge run, and silently giving them default mode means the PR they expected to be merged just sits there.

Argument Hint Interpretation (Claude Desktop)

Use this deterministic precedence:

1. If hints include --release, full-release, or terms like release, publish, ship → run release mode.
2. Else if hints include --merge, full, or terms like autonomous, merge → run merge mode.
3. Else run default mode.

Do not fail because hints are missing or unrecognized; default safely.

Bundled Scripts

scripts/fetch_pr_checks.py

Fetches CI check status and extracts failure snippets from logs.

python3 .agents/skills/iterate-pr/scripts/fetch_pr_checks.py [--pr NUMBER]

Returns JSON:

{
  "status": "ok",
  "pr": {"number": 123, "branch": "feat/foo"},
  "summary": {"total": 5, "passed": 3, "failed": 2, "pending": 0},
  "checks": [
    {"name": "tests", "status": "fail", "log_snippet": "...", "run_id": 123},
    {"name": "lint", "status": "pass"}
  ]
}

scripts/fetch_pr_feedback.py

Fetches and categorizes PR review feedback using the LOGAF scale.

python3 .agents/skills/iterate-pr/scripts/fetch_pr_feedback.py [--pr NUMBER]

Sources covered, all paginated: review bodies (every review state, not only CHANGES_REQUESTED), inline review threads, and PR conversation comments. Each is a channel that must deliver - see Fetch Integrity - so a zero here means the PR really has nothing, never that a request quietly returned nothing.

Returns JSON with feedback categorized as:

• high - Must address before merge (h:, blocker, changes requested)
• medium - Should address (m:, standard feedback)
• low - Optional (l:, nit, style, suggestion)
• bot - Informational automated comments (Codecov, Dependabot, etc.)
• resolved - Already resolved threads

Review bot feedback (CodeRabbit, Gemini Code Assist, Copilot, Sentry, Warden, Cursor, Bugbot, CodeQL, etc.) appears in high/medium/low with review_bot: true — it is NOT placed in the bot bucket. REVIEW_BOT_PATTERNS in scripts/fetch_pr_feedback.py owns the full roster; do not maintain a second copy of it here. Logins are matched with any trailing [bot] stripped, because REST reports coderabbitai[bot] where GraphQL reports coderabbitai for the same account; without that normalization the generic [bot] suffix rule files the fleet's main reviewer under bot and it gets skipped silently.

Each feedback item may also include:

• thread_id - GraphQL node ID for inline review comments (used for replies via reply_to_thread.py)
• replied - the newest comment in that thread is yours, so you have already answered it

Top-level fields:

• status - see the mandatory gate above
• viewer - the login gh is authenticated as
• summary.needs_attention - open high + medium items, excluding those flagged replied
• summary.already_replied - how many priority items were excluded on that basis

Self-authored feedback is never reported. Comments and reviews written by the PR author or by viewer are dropped, and a thread whose newest comment is yours is flagged replied and leaves needs_attention. Without both rules a --merge run answers an item, sees its own answer as new feedback, and never converges.

replied is decided per source, by the strongest evidence each one offers:

Only the inline-thread signal is exact evidence, so it is the only one used. Anything weaker - "the review predates something else we said" - cannot tell answering a review apart from merely typing after it, and would silently dismiss a review that arrives mid-round. Re-reporting a review you already answered is visible to you; dropping one you never read is not.

scripts/reply_to_thread.py

Replies to PR review threads. Batches multiple replies into a single GraphQL call.

python3 .agents/skills/iterate-pr/scripts/reply_to_thread.py THREAD_ID "body" [THREAD_ID "body" ...]

Arguments are alternating (thread_id, body) pairs. The script sends the reply body without adding signatures, attribution, or sign-off text. Example:

python3 .agents/skills/iterate-pr/scripts/reply_to_thread.py \
  PRRT_abc "Fixed the null check." \
  PRRT_def "Replaced with path-segment counting."

Workflow

1. Identify PR

gh pr view --json number,url,headRefName

Stop if no PR exists for the current branch.

2. Gather Review Feedback

Run python3 .agents/skills/iterate-pr/scripts/fetch_pr_feedback.py to get categorized feedback already posted on the PR.

Check status first. If it is not "ok", stop and report the error — do not continue as though the PR had no feedback.

3. Handle Feedback by Priority and Mode

Determine mode from invocation (/iterate-pr, /iterate-pr --merge, /iterate-pr --release).

Default mode (/iterate-pr)

Auto-fix (no prompt):

• high - must address (blockers, security, changes requested)
• medium - should address (standard feedback)

Prompt user for selection:

• low - present numbered list and ask which to address:

Found 3 low-priority suggestions:
1. [l] "Consider renaming this variable" - @reviewer in api.py:42
2. [nit] "Could use a list comprehension" - @reviewer in utils.py:18
3. [style] "Add a docstring" - @reviewer in models.py:55

Which would you like to address? (e.g., "1,3" or "all" or "none")

Skip silently:

• resolved threads
• items flagged replied (you already answered them; act only when a reviewer follows up)
• bot comments (informational only — Codecov, Dependabot, etc.)

Merge modes (/iterate-pr --merge, /iterate-pr --merge --release)

Operate autonomously. Process every new feedback item returned by fetch_pr_feedback.py (high, medium, low, and bot).

An item is new when it is not resolved, not flagged replied, and not one you already answered in an earlier round of this same session. Only inline review threads carry replied; review bodies and PR conversation comments have no resolution state, so the fetcher re-returns them verbatim on every poll and cannot make that last distinction for you. Keep your own in-session record of which ones you have replied to and do not answer them twice.

For each item:

• Decide whether the feedback is justified
• If justified, implement the change
• If not justified, reject it with a concise technical reason
• Never leave an item without an explicit decision

When fixing feedback (all modes):

• Understand the root cause, not just the surface symptom
• Check for similar issues in nearby code or related files
• Fix all instances, not just the one mentioned

This includes review bot feedback (items with review_bot: true). Treat it the same as human feedback:

• Real issue found → fix it
• False positive → reject with explanation
• Never silently ignore review bot feedback — always verify the finding

Replying to Comments

After processing feedback, reply to PR comments/threads to acknowledge the action taken.

Scope by mode:

• Default mode: reply to high/medium; reply to low only when fixed or declined by the user
• Merge modes: reply to every new feedback item, including informational bot feedback - one reply per item per session, not one per poll

How to reply:

• If thread_id exists (inline review thread), use python3 .agents/skills/iterate-pr/scripts/reply_to_thread.py
• If no thread_id exists, post a PR comment with gh pr comment <PR_NUMBER> --body "..."
• In merge modes, a round is incomplete until every new item has a corresponding reply; an item you answered in an earlier round of this session already has one, so leave it alone rather than replying again

Batch inline replies for a round into a single call:

python3 .agents/skills/iterate-pr/scripts/reply_to_thread.py \
  PRRT_abc "Fixed — description of change." \
  PRRT_def "Not applicable — reason."

Reply format:

• 1-2 sentences: what was changed, why it's not an issue, or acknowledgment of declined items
• Never add a signature, attribution line, tag, or vendor/model mention in replies
• Keep replies tool-agnostic and identity-free
• If the script fails, log and continue — do not block the workflow