Systematic workflow for maintaining a backlog of open MicroPython PRs. Use when the user asks about PR maintenance, PR backlog processing, rebasing PRs, working through open PRs, or updating stale PRs. Handles reconnaissance, reviewer feedback discussion, rebase in worktrees via subprocess, local CI validation, and force-push.
Process open PRs on micropython/micropython authored by a specific user, oldest to newest. Each PR goes through: reconnaissance, user discussion, rebase/fix in a worktree subprocess, local CI validation, and push.
gh CLI authenticated with access to micropython/micropythonmpy-ci plugin installed (provides ci/ci-local.sh and ci/Dockerfile)mpy-pr-triage plugin installed (provides PR listing)origin pointing to the user's fork and upstream pointing to micropython/micropythonUse the triage plugin or directly to get open PRs:
ghgh pr list --repo micropython/micropython --author @me --state open --json number,title,headRefName,createdAt,isDraft --limit 100
Sort by createdAt ascending (oldest first).
Create or load ~/mpy/pr-maintenance-state.json:
{
"last_updated": "ISO-8601 timestamp",
"current_pr_index": 0,
"prs": [
{
"number": 5323,
"branch": "ordered_maps",
"status": "pending",
"notes": ""
}
]
}
Valid statuses: pending, in_progress, completed, skipped, deferred, closed.
Update current_pr_index as PRs are processed. Save after each PR completes.
For each PR, run 5 parallel Bash calls to gather:
PR metadata -- title, body, labels, draft status, mergeable state:
gh pr view <NUMBER> --repo micropython/micropython --json title,body,labels,isDraft,mergeable,baseRefName,headRefName,createdAt,updatedAt
Comments and reviews -- all discussion, review comments, inline review comments:
gh pr view <NUMBER> --repo micropython/micropython --comments
gh api /repos/micropython/micropython/pulls/<NUMBER>/comments
gh api /repos/micropython/micropython/pulls/<NUMBER>/reviews
CI status -- check runs on the PR head:
gh pr checks <NUMBER> --repo micropython/micropython
Branch state -- whether the branch exists locally, divergence from upstream/master:
git fetch origin <BRANCH> 2>&1
git log --oneline origin/<BRANCH>..upstream/master | head -20
git log --oneline upstream/master..origin/<BRANCH>
Commit history -- commits on the PR branch:
gh api /repos/micropython/micropython/pulls/<NUMBER>/commits --jq '.[].commit.message'
Filter comments and reviews to find feedback from external reviewers (not the PR author, not bots). Key maintainer accounts: dpgeorge, projectgus, jimmo, robert-hh.
Feedback is "unaddressed" if:
Present findings to the user:
Wait for the user to choose one of:
skipped, move to next PRgh pr close <NUMBER> --repo micropython/micropython, mark as closeddeferred, move to next PRFor draft PRs, default recommendation is skip unless the user says otherwise.
If multiple PRs have no unaddressed reviewer feedback, present them as a batch and offer to launch all of them in parallel (up to 6 concurrent subprocesses). Still present each PR's summary so the user can exclude any.
git fetch origin <BRANCH>
git worktree add ~/mpy/<BRANCH> origin/<BRANCH>
cd ~/mpy/<BRANCH> && git checkout -b <BRANCH>
git remote add upstream https://github.com/micropython/micropython.git 2>/dev/null || true
git fetch upstream master
Install CI tooling and project context into the worktree:
ln -sf ~/CLAUDE_micropython.md ~/mpy/<BRANCH>/CLAUDE.md
mkdir -p ~/mpy/<BRANCH>/ci
cp ${CLAUDE_PLUGIN_ROOT}/../mpy-ci/skills/mpy-ci/scripts/ci-local.sh ~/mpy/<BRANCH>/ci/ci-local.sh
cp ${CLAUDE_PLUGIN_ROOT}/../mpy-ci/skills/mpy-ci/assets/Dockerfile ~/mpy/<BRANCH>/ci/Dockerfile
chmod +x ~/mpy/<BRANCH>/ci/ci-local.sh
If ${CLAUDE_PLUGIN_ROOT} is not available, fall back to the CI files in the current repo's ci/ directory, or ask the user for the path.
Build a prompt from the templates in references/prompt-templates.md. The prompt must include:
Run:
cd ~/mpy/<BRANCH> && claude -p --dangerously-skip-permissions "<PROMPT>" 2>&1 | tee /tmp/claude-pr-<NUMBER>.log | tail -30
Key points about the subprocess:
--dangerously-skip-permissions is required because -p (pipe/non-interactive mode) cannot approve tool permission promptscd ~/mpy/<BRANCH> && claude/tmp/claude-pr-<NUMBER>.logAfter the subprocess exits, verify:
cd ~/mpy/<BRANCH> && git status
cd ~/mpy/<BRANCH> && git log --oneline upstream/master..HEAD
Check that:
git checkout upstream/master -- lib/)Determine which CI targets to run based on changed files:
cd ~/mpy/<BRANCH> && git diff --name-only upstream/master...HEAD
Apply these rules:
| Changed path pattern | CI targets |
|---|---|
py/**, extmod/**, shared/**, lib/**, drivers/** | unix, stm32 |
ports/stm32/** | stm32 |
ports/esp32/** | esp32 |
ports/rp2/** | rp2 |
ports/unix/** | unix |
ports/<port>/** | that port's target name |
tests/** | unix |
docs/** | docs |
tools/mpremote/** | mpremote |
Always include: format, codespell, ruff.
Deduplicate the target list.
cd ~/mpy/<BRANCH> && ./ci/ci-local.sh format codespell ruff <PORT_TARGETS> 2>&1 | tee /tmp/ci-pr-<NUMBER>.log
This step is mandatory. Do not push until local CI passes. The subprocess in Phase 3 only runs a basic build test — this phase runs the full relevant CI suite.
Run in the background to allow parallel processing of the next PR's recon/discussion, but block the push (Phase 5) until results are available.
These tests fail intermittently and should not block a push:
thread/stress_schedule.pymisc/sys_settrace_features.pyOnly after local CI passes (check the background job results):
cd ~/mpy/<BRANCH> && git push origin <BRANCH> --force-with-lease
--force-with-lease prevents overwriting changes pushed by someone else since the last fetch.
Update state file: set PR status to completed.
Optionally leave a comment on the PR noting the rebase:
gh pr comment <NUMBER> --repo micropython/micropython --body "Rebased onto current master and addressed review feedback."
After all PRs are processed:
# Remove worktrees for completed PRs only
git worktree list | grep ~/mpy/ | awk '{print $1}' | xargs -I{} git worktree remove {}
Only clean up worktrees for PRs with status completed. Keep worktrees for deferred or in_progress PRs.
Process the oldest (base) PR first. If PR B depends on PR A, rebase A first, then rebase B onto A's updated branch.
Expect significant conflicts. The subprocess may need to reimplement the feature on current master rather than performing a git rebase. Flag this to the user during Phase 2.
Submodule pointer changes (in lib/) that differ from upstream/master should be dropped:
git checkout upstream/master -- lib/
git commit --amend --no-edit
Present to the user during Phase 2 with a default recommendation of skip. The user may choose to proceed if the draft is close to ready.
Subprocess prompt templates for different PR scenarios (simple rebase, rebase with feedback, major rework, squash and clean up).