|
| 1 | +--- |
| 2 | +name: iterate-pr |
| 3 | +description: Iterate on a PR until CI passes. Optionally merge or merge and publish a release of the repo. Automates the feedback-fix-push-wait cycle. |
| 4 | +argument-hint: "[--full] [--release]" |
| 5 | +metadata: |
| 6 | + author: leecalcote |
| 7 | + version: "2.3.0" |
| 8 | +--- |
| 9 | + |
| 10 | +# Iterate on PR Until CI Passes |
| 11 | + |
| 12 | +Continuously iterate on the current branch until all CI checks pass and review feedback is addressed. |
| 13 | + |
| 14 | +**Requires**: GitHub CLI (`gh`) authenticated. |
| 15 | + |
| 16 | +**Requires**: Python 3.9+. |
| 17 | + |
| 18 | +**Important**: Run scripts from the repository root directory (where `.git` is located). |
| 19 | + |
| 20 | +### Running the Bundled Scripts |
| 21 | + |
| 22 | +Every script below accepts either runner - they only use the standard library, so no |
| 23 | +dependency installation is needed either way: |
| 24 | + |
| 25 | +- **Preferred**: [`uv`](https://docs.astral.sh/uv/getting-started/installation/) - `uv run <script>`. Faster startup, isolated from system Python. |
| 26 | +- **Fallback**: `python3 <script>` - used automatically when `uv` is not on `PATH`. |
| 27 | + |
| 28 | +Before running any script command shown in this skill, check for `uv` first and prefer it; |
| 29 | +fall back to `python3` only if `uv` is unavailable: |
| 30 | + |
| 31 | +```bash |
| 32 | +if command -v uv >/dev/null 2>&1; then |
| 33 | + uv run .claude/skills/iterate-pr/scripts/<script>.py [args] |
| 34 | +else |
| 35 | + python3 .claude/skills/iterate-pr/scripts/<script>.py [args] |
| 36 | +fi |
| 37 | +``` |
| 38 | + |
| 39 | +The rest of this document shows invocations in the shorter `python3 <script>` form for |
| 40 | +readability - substitute `uv run` per the rule above whenever `uv` is available. |
| 41 | + |
| 42 | +## Invocation and Modes |
| 43 | + |
| 44 | +Invoke as: |
| 45 | + |
| 46 | +- `/iterate-pr` |
| 47 | +- `/iterate-pr --full` |
| 48 | +- `/iterate-pr --release` |
| 49 | +- `/iterate-pr --full --release` |
| 50 | + |
| 51 | +In Claude Desktop, arguments are **hints**, not strict CLI parsing. Treat whatever follows `/iterate-pr` as a mode hint string. |
| 52 | + |
| 53 | +### Argument Hint Interpretation (Claude Desktop) |
| 54 | + |
| 55 | +Use this deterministic precedence: |
| 56 | + |
| 57 | +1. If hints include `--release` or terms like `release`, `publish`, `ship` → run **release mode**. |
| 58 | +2. Else if hints include `--full` or terms like `full`, `autonomous`, `merge` → run **full mode**. |
| 59 | +3. Else run **default mode**. |
| 60 | + |
| 61 | +Do not fail because hints are missing or unrecognized; default safely. |
| 62 | + |
| 63 | +| Mode | Behavior | |
| 64 | +|---|---| |
| 65 | +| Default (`/iterate-pr`) | Iterates on CI + high/medium feedback, asks user about low-priority items, then exits without merging. | |
| 66 | +| `--full` | Fully autonomous: handles every non-resolved feedback item, replies to every item, re-requests review (Gemini or Copilot) after each push, iterates until no new feedback and CI is green, then administratively merges the PR without waiting for a required-approval status. | |
| 67 | +| `--release` | Does everything in `--full`, then cuts/publishes a release for the repository. | |
| 68 | + |
| 69 | +## Bundled Scripts |
| 70 | + |
| 71 | +### `scripts/fetch_pr_checks.py` |
| 72 | + |
| 73 | +Fetches CI check status and extracts failure snippets from logs. |
| 74 | + |
| 75 | +```bash |
| 76 | +python3 .claude/skills/iterate-pr/scripts/fetch_pr_checks.py [--pr NUMBER] |
| 77 | +``` |
| 78 | + |
| 79 | +Returns JSON: |
| 80 | +```json |
| 81 | +{ |
| 82 | + "pr": {"number": 123, "branch": "feat/foo"}, |
| 83 | + "summary": {"total": 5, "passed": 3, "failed": 2, "pending": 0}, |
| 84 | + "checks": [ |
| 85 | + {"name": "tests", "status": "fail", "log_snippet": "...", "run_id": 123}, |
| 86 | + {"name": "lint", "status": "pass"} |
| 87 | + ] |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +### `scripts/fetch_pr_feedback.py` |
| 92 | + |
| 93 | +Fetches and categorizes PR review feedback using the [LOGAF scale](https://develop.sentry.dev/engineering-practices/code-review/#logaf-scale). |
| 94 | + |
| 95 | +```bash |
| 96 | +python3 .claude/skills/iterate-pr/scripts/fetch_pr_feedback.py [--pr NUMBER] |
| 97 | +``` |
| 98 | + |
| 99 | +Returns JSON with feedback categorized as: |
| 100 | +- `high` - Must address before merge (`h:`, blocker, changes requested) |
| 101 | +- `medium` - Should address (`m:`, standard feedback) |
| 102 | +- `low` - Optional (`l:`, nit, style, suggestion) |
| 103 | +- `bot` - Informational automated comments (Codecov, Dependabot, etc.) |
| 104 | +- `resolved` - Already resolved threads |
| 105 | + |
| 106 | +Review bot feedback (from Sentry, Warden, Cursor, Bugbot, CodeQL, etc.) appears in `high`/`medium`/`low` with `review_bot: true` — it is NOT placed in the `bot` bucket. |
| 107 | + |
| 108 | +Each feedback item may also include: |
| 109 | +- `thread_id` - GraphQL node ID for inline review comments (used for replies via `reply_to_thread.py`) |
| 110 | + |
| 111 | +### `scripts/reply_to_thread.py` |
| 112 | + |
| 113 | +Replies to PR review threads. Batches multiple replies into a single GraphQL call. |
| 114 | + |
| 115 | +```bash |
| 116 | +python3 .claude/skills/iterate-pr/scripts/reply_to_thread.py THREAD_ID "body" [THREAD_ID "body" ...] |
| 117 | +``` |
| 118 | + |
| 119 | +Arguments are alternating `(thread_id, body)` pairs. The script sends the reply body without adding signatures, attribution, or sign-off text. Example: |
| 120 | +```bash |
| 121 | +python3 .claude/skills/iterate-pr/scripts/reply_to_thread.py \ |
| 122 | + PRRT_abc "Fixed the null check." \ |
| 123 | + PRRT_def "Replaced with path-segment counting." |
| 124 | +``` |
| 125 | + |
| 126 | +## Workflow |
| 127 | + |
| 128 | +### 1. Identify PR |
| 129 | + |
| 130 | +```bash |
| 131 | +gh pr view --json number,url,headRefName |
| 132 | +``` |
| 133 | + |
| 134 | +Stop if no PR exists for the current branch. |
| 135 | + |
| 136 | +### 2. Gather Review Feedback |
| 137 | + |
| 138 | +Run `python3 .claude/skills/iterate-pr/scripts/fetch_pr_feedback.py` to get categorized feedback already posted on the PR. |
| 139 | + |
| 140 | +### 3. Handle Feedback by Priority and Mode |
| 141 | + |
| 142 | +Determine mode from invocation (`/iterate-pr`, `/iterate-pr --full`, `/iterate-pr --release`). |
| 143 | + |
| 144 | +#### Default mode (`/iterate-pr`) |
| 145 | + |
| 146 | +**Auto-fix (no prompt):** |
| 147 | +- `high` - must address (blockers, security, changes requested) |
| 148 | +- `medium` - should address (standard feedback) |
| 149 | + |
| 150 | +**Prompt user for selection:** |
| 151 | +- `low` - present numbered list and ask which to address: |
| 152 | + |
| 153 | +``` |
| 154 | +Found 3 low-priority suggestions: |
| 155 | +1. [l] "Consider renaming this variable" - @reviewer in api.py:42 |
| 156 | +2. [nit] "Could use a list comprehension" - @reviewer in utils.py:18 |
| 157 | +3. [style] "Add a docstring" - @reviewer in models.py:55 |
| 158 | +
|
| 159 | +Which would you like to address? (e.g., "1,3" or "all" or "none") |
| 160 | +``` |
| 161 | + |
| 162 | +**Skip silently:** |
| 163 | +- `resolved` threads |
| 164 | +- `bot` comments (informational only — Codecov, Dependabot, etc.) |
| 165 | + |
| 166 | +#### Full modes (`/iterate-pr --full`, `/iterate-pr --full --release`) |
| 167 | + |
| 168 | +Operate autonomously. Process every non-resolved feedback item returned by `fetch_pr_feedback.py` (`high`, `medium`, `low`, and `bot`). |
| 169 | + |
| 170 | +For each item: |
| 171 | +- Decide whether the feedback is justified |
| 172 | +- If justified, implement the change |
| 173 | +- If not justified, reject it with a concise technical reason |
| 174 | +- Never leave an item without an explicit decision |
| 175 | + |
| 176 | +When fixing feedback (all modes): |
| 177 | +- Understand the root cause, not just the surface symptom |
| 178 | +- Check for similar issues in nearby code or related files |
| 179 | +- Fix all instances, not just the one mentioned |
| 180 | + |
| 181 | +This includes review bot feedback (items with `review_bot: true`). Treat it the same as human feedback: |
| 182 | +- Real issue found → fix it |
| 183 | +- False positive → reject with explanation |
| 184 | +- Never silently ignore review bot feedback — always verify the finding |
| 185 | + |
| 186 | +#### Replying to Comments |
| 187 | + |
| 188 | +After processing feedback, reply to PR comments/threads to acknowledge the action taken. |
| 189 | + |
| 190 | +**Scope by mode:** |
| 191 | +- Default mode: reply to `high`/`medium`; reply to `low` only when fixed or declined by the user |
| 192 | +- Full modes: reply to every non-resolved feedback item, including informational bot feedback |
| 193 | + |
| 194 | +**How to reply:** |
| 195 | +- If `thread_id` exists (inline review thread), use `python3 .claude/skills/iterate-pr/scripts/reply_to_thread.py` |
| 196 | +- If no `thread_id` exists, post a PR comment with `gh pr comment <PR_NUMBER> --body "..."` |
| 197 | +- In full modes, a feedback round is incomplete until every item has a corresponding reply |
| 198 | + |
| 199 | +Batch inline replies for a round into a single call: |
| 200 | + |
| 201 | +```bash |
| 202 | +python3 .claude/skills/iterate-pr/scripts/reply_to_thread.py \ |
| 203 | + PRRT_abc "Fixed — description of change." \ |
| 204 | + PRRT_def "Not applicable — reason." |
| 205 | +``` |
| 206 | + |
| 207 | +**Reply format:** |
| 208 | +- 1-2 sentences: what was changed, why it's not an issue, or acknowledgment of declined items |
| 209 | +- Never add a signature, attribution line, tag, or vendor/model mention in replies |
| 210 | +- Keep replies tool-agnostic and identity-free |
| 211 | +- If the script fails, log and continue — do not block the workflow |
| 212 | + |
| 213 | +### 4. Check CI Status |
| 214 | + |
| 215 | +Run `python3 .claude/skills/iterate-pr/scripts/fetch_pr_checks.py` to get structured failure data. |
| 216 | + |
| 217 | +**Wait if pending:** If review bot checks (sentry, warden, cursor, bugbot, seer, codeql) are still running, wait before proceeding—they post actionable feedback that must be evaluated. Informational bots (codecov) are not worth waiting for. |
| 218 | + |
| 219 | +### 5. Fix CI Failures |
| 220 | + |
| 221 | +For each failure in the script output: |
| 222 | +1. Read the `log_snippet` and trace backwards from the error to understand WHY it failed — not just what failed |
| 223 | +2. Read the relevant code and check for related issues (e.g., if a type error in one call site, check other call sites) |
| 224 | +3. Fix the root cause with minimal, targeted changes |
| 225 | +4. Find existing tests for the affected code and run them. If the fix introduces behavior not covered by existing tests, extend them to cover it (add a test case, not a whole new test file) |
| 226 | + |
| 227 | +Do NOT assume what failed based on check name alone—always read the logs. Do NOT "quick fix and hope" — understand the failure thoroughly before changing code. |
| 228 | + |
| 229 | +### 6. Verify Locally, Then Commit and Push |
| 230 | + |
| 231 | +Before committing, verify your fixes locally: |
| 232 | +- If you fixed a test failure: re-run that specific test locally |
| 233 | +- If you fixed a lint/type error: re-run the linter or type checker on affected files |
| 234 | +- For any code fix: run existing tests covering the changed code |
| 235 | + |
| 236 | +If local verification fails, fix before proceeding — do not push known-broken code. |
| 237 | + |
| 238 | +```bash |
| 239 | +git add <files> |
| 240 | +gh auth status -a |
| 241 | +git commit --signoff -m "fix: <descriptive message>" |
| 242 | +git push |
| 243 | +``` |
| 244 | + |
| 245 | +Always add exactly one sign-off to each commit for the active authenticated GitHub user. Check `gh auth status -a` before committing to confirm the active account, use `git commit --signoff`, and do not add any other trailers, signatures, or tool attribution to commits or PR comments. |
| 246 | + |
| 247 | +### 7. Monitor CI and Address Feedback |
| 248 | + |
| 249 | +Poll CI status and review feedback in a loop instead of blocking: |
| 250 | + |
| 251 | +1. Run `python3 .claude/skills/iterate-pr/scripts/fetch_pr_checks.py` to get current CI status |
| 252 | +2. If all checks passed → proceed to exit conditions |
| 253 | +3. If any checks failed (none pending) → return to step 5 |
| 254 | +4. If checks are still pending: |
| 255 | + a. Run `python3 .claude/skills/iterate-pr/scripts/fetch_pr_feedback.py` for new review feedback |
| 256 | + b. Address feedback based on mode: |
| 257 | + - Default mode: new `high`/`medium` |
| 258 | + - Full modes: every new non-resolved item (`high`/`medium`/`low`/`bot`) and reply to each item |
| 259 | + c. If changes were needed, commit and push (this restarts CI) |
| 260 | + d. In full modes, after each push, explicitly re-request review: |
| 261 | + - Prefer Gemini review command (`/gemini review`) when available |
| 262 | + - Otherwise request Copilot review by commenting `@copilot review` on the PR |
| 263 | + e. Sleep 30 seconds (don't increase on subsequent iterations), then repeat from sub-step 1 |
| 264 | +5. After all checks pass, do a final feedback check: `sleep 10`, then run `python3 .claude/skills/iterate-pr/scripts/fetch_pr_feedback.py`. |
| 265 | + - Default mode: address any new `high`/`medium` feedback; if changes are needed, return to step 6 |
| 266 | + - Full modes: address any new non-resolved item; if changes are needed, return to step 6 and re-request review |
| 267 | + |
| 268 | +### 8. Repeat |
| 269 | + |
| 270 | +If step 7 required code changes (from new feedback after CI passed), return to step 2 for a fresh cycle. CI failures during monitoring are already handled within step 7's polling loop. |
| 271 | + |
| 272 | +In full modes, continue looping until both conditions are true: |
| 273 | +- CI checks are green |
| 274 | +- No new non-resolved feedback is returned after the latest review request |
| 275 | + |
| 276 | +### 9. Finish by Mode |
| 277 | + |
| 278 | +- Default mode: stop after success conditions are met (do not merge automatically) |
| 279 | +- `full`: once CI is green and no new feedback remains, merge administratively - do not wait for a required-approval status to clear: |
| 280 | + |
| 281 | +```bash |
| 282 | +gh pr merge <PR_NUMBER> --admin --delete-branch |
| 283 | +``` |
| 284 | + |
| 285 | +`--admin` uses the authenticated account's admin/maintainer permissions to bypass the |
| 286 | +required-approving-review branch-protection rule; it does not bypass or skip the CI-green |
| 287 | +and feedback-resolved checks this skill already enforces in steps 4-7, and it never fabricates |
| 288 | +or requests an approving review from another account. If the command fails (e.g. the |
| 289 | +authenticated account lacks admin/maintainer rights on the repo, or a check can't be |
| 290 | +bypassed), stop and surface the `gh` error to the user - do not retry under a different |
| 291 | +identity and do not fall back silently. |
| 292 | + |
| 293 | +- `--release`: complete `--full` mode merge, then cut a release: |
| 294 | + 1. Find the draft release tag: |
| 295 | + ```bash |
| 296 | + gh release list --repo layer5io/meshery-cloud --json tagName,isDraft --jq '.[] | select(.isDraft) | .tagName' |
| 297 | + ``` |
| 298 | + 2. Review draft notes: |
| 299 | + ```bash |
| 300 | + gh release view vX.Y.Z --repo layer5io/meshery-cloud |
| 301 | + ``` |
| 302 | + 3. Publish the release: |
| 303 | + ```bash |
| 304 | + gh release edit vX.Y.Z --repo layer5io/meshery-cloud --draft=false --latest |
| 305 | + ``` |
| 306 | + |
| 307 | +## Exit Conditions |
| 308 | + |
| 309 | +**Success (default):** All checks pass, post-CI feedback re-check is clean (no new unaddressed high/medium feedback including review bot findings), user has decided on low-priority items. |
| 310 | + |
| 311 | +**Success (`full`):** All checks pass, no new non-resolved feedback remains after the latest review request, every feedback item has a reply, and the PR is administratively merged (no wait on a required-approval status). |
| 312 | + |
| 313 | +**Success (`--release`):** `--full` success criteria are met and the draft GitHub release has been published. |
| 314 | + |
| 315 | +**Ask for help:** Same failure after 2 attempts, feedback needs clarification, infrastructure issues, or `gh pr merge --admin` fails (insufficient permissions or an unbypassable check) - surface the error rather than retrying under a different identity or falling back silently. |
| 316 | + |
| 317 | +**Stop:** No PR exists, branch needs rebase. |
| 318 | + |
| 319 | +## Fallback |
| 320 | + |
| 321 | +If scripts fail, use `gh` CLI directly: |
| 322 | +- `gh pr checks --json name,state,bucket,link` |
| 323 | +- `gh run view <run-id> --log-failed` |
| 324 | +- `gh api repos/{owner}/{repo}/pulls/{number}/comments` |
0 commit comments