Skip to content

Commit c140f9f

Browse files
iterate-pr v2.3.0
Signed-off-by: Ahmed Jamil <[email protected]>
1 parent ddf0945 commit c140f9f

12 files changed

Lines changed: 2308 additions & 0 deletions

‎.agents/skills/iterate-pr/SKILL.md‎

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
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`
Binary file not shown.
Binary file not shown.

0 commit comments

Comments
 (0)