dart-manage-pr

Use this skill to run the DART dart-manage-pr workflow. The editable workflow source lives in .claude/commands/; this generated skill is its entrypoint for Codex and Muse.

Invocation

• Claude Code: /dart-manage-pr <arguments>
• Codex: $dart-manage-pr <arguments>
• Muse: /dart-manage-pr <arguments>

Treat the text after the skill name, or the user's request when the skill is loaded on demand, as $ARGUMENTS. When the workflow references $1, $2, etc., map those to the positional values supplied by the user.

Command Body

Manage an open DART pull request after explicit maintainer/user approval for mutations: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/release-management.md @docs/onboarding/ci-cd.md @docs/onboarding/ai-tools.md

Modes

• status: report-only; no mutations.
• mode=manage (default): run the full loop below to the next terminal state.
• mode=merge: merges happen only under this mode, through the step 5 pre-merge gate and explicit maintainer/user approval to merge.

Invocation Contract

When the user says manage <PR> or continue managing <PR> without limiting the request to status-only, treat that as approval to run the full PR-management loop to the next terminal state:

• required policy metadata checked and corrected when stale;
• CI monitored until green, failed, or blocked;
• merge conflicts reproduced and resolved locally;
• review comments addressed, pushed, resolved, re-reviewed when appropriate;
• PR body/testing evidence refreshed when it no longer matches the branch.

This explicit approval covers routine PR-maintenance mutations for that loop: additive fix commits and pushes, description/metadata corrections, resolving already-addressed review threads, rerunning failed CI jobs, requesting a fresh @codex review for a new head, and marking a draft ready once the "PR Lifecycle" step 2 gate passes. It does not cover merging (see mode=merge), force-pushes, branch deletion, PR closure, base-branch changes, or human reviewer requests; ask separately for those.

Do not call the PR managed just because checks are green: continue until it is mergeable with required checks complete and addressed threads resolved, or a concrete blocker remains.

Identify the PR

Use the PR number or URL from $ARGUMENTS. If none is provided, infer the PR from the current branch:

gh pr view --json number,url,headRefName,baseRefName

Then inspect the full state:

gh pr view <PR_NUMBER> --json number,title,state,isDraft,baseRefName,headRefName,mergeStateStatus,milestone,url,reviewDecision,statusCheckRollup
gh pr checks <PR_NUMBER>

Workflow

1. Confirm scope and policy:
   • Check the live base branch, title, and PR template. Fetch that base and read its docs/onboarding/release-management.md § "Release target". Verify the exact DART <Next release> milestone is open on GitHub; correct stale or missing metadata only after maintainer/user approval. For an explicit rollover, follow the owner's proposed-target rule.
   • Confirm ordinary changes target main. Backports and release-specific packaging, CI, or branch guidance may target a maintained release-* branch; backports use dart-backport-pr.
   • Confirm the PR body's testing/status section matches the current head and does not point reviewers to deleted dev-task evidence as still pending.
   • Follow docs/onboarding/contributing.md § "PR Descriptions" for the body and complete its applicable "PR Author Checklist" actions before publishing updates.
   • Ensure transient visual evidence (screenshots, headless renders, GIFs, videos) is hosted as GitHub PR/issue Markdown attachments (https://github.com/user-attachments/assets/...), never as release assets or tags or committed to the branch; if evidence files were committed only for the PR body, remove them and link an attachment URL instead (ask a maintainer to upload when tooling cannot).
   • For claim-dependent 3D behavior, require Visual verification through dart-verify-sim per docs/ai/verification.md, or a stated reason visual corroboration is unavailable/irrelevant and named replacement evidence.
   • Inspect local state before editing: git status --short --branch, git diff --stat, git diff --check.
2. Monitor CI:

   gh pr checks <PR_NUMBER> --watch --interval 30 --fail-fast
   

   If checks are still queued or running, report the current jobs and keep watching unless the user asked only for status. Also poll mergeability:

   gh pr view <PR_NUMBER> --json mergeStateStatus,headRefOid,isDraft,reviewDecision
   

   If GitHub reports conflicts, fetch the target branch and resolve them before treating green checks as sufficient.
3. Fix failures:
   • Inspect the newest failed run or job, not an older cancelled run.
   • Use the dart-fix-ci workflow for non-trivial CI debugging.
   • Reproduce locally with the relevant pixi run ... task or focused test.
   • Before committing fixes, run pixi run lint; also run build or tests when code or behavior changed.
   • Commit only intended files. Push only after explicit maintainer/user approval, then continue monitoring the PR.
   • For already-published PRs, prefer additive follow-up commits. Amend or force-push only after explicit maintainer/user approval, when the user explicitly requests it or a clear reason exists (removing sensitive content, repairing broken history).
   • Before every push, first merge the latest base branch into the PR branch (on every push, not just the first) so each pushed/CI-tested state reflects the current target base branch and conflicts surface early:

     git fetch origin <base-branch>
     git merge --no-ff origin/<base-branch>  # never rebase a published PR branch
     # rebuild + retest if the merge touched code
     git push                                 # after explicit approval
     

     The local base merge is a routine pre-push step; the push itself still requires explicit maintainer/user approval. Never rebase or force-push a published PR branch unless the maintainer explicitly requests it.
4. Address reviews:
   • Use the dart-review-pr workflow for substantive review feedback.
   • Never reply to AI-generated review comments from bot users such as chatgpt-codex-connector[bot], github-code-quality[bot], github-actions[bot], or copilot[bot].
   • Request Codex review as docs/onboarding/ai-tools.md § "PR Lifecycle" describes once explicit maintainer/user approval covers PR comments. If Codex already shows an activity signal or a review of the current head, do not post a duplicate trigger.
   • Apply AI-review fixes silently. After explicit maintainer/user approval, push, resolve reviewed and addressed threads, and request a fresh review for the new head:

     gh pr comment <PR_NUMBER> --body "@codex review"
     

   • For substantive code PRs, an independent review session (a human, or a separate session running dart-review-pr via /dart-review-pr or $dart-review-pr) must record its outcome — findings or an explicitly clean result — before merge approval; docs-only/mechanical are exempt.
   • For human reviewers, reply only when a response is useful after a fix or when a question needs clarification.
   • After posting @codex review, keep monitoring until a submitted review, a visible activity signal, or a concrete timeout/blocker is observed.
5. Mark ready or merge only through docs/onboarding/ai-tools.md § "PR Lifecycle":
   • PR comments, review re-triggers, thread resolution, reviewer requests, ready-for-review transitions, merges, and branch deletion are external mutations and require explicit maintainer/user approval.
   • If the PR is draft and lifecycle step 2 passes, mark it ready with gh pr ready <PR_NUMBER>.
   • mode=merge gate: before any merge, re-run local validation on the current head after the latest pushed change (pixi run test-all, plus the Gazebo gate when downstream compatibility could be affected); merge only when lifecycle steps 3-5 hold, the milestone is set, an independent review recorded a clean result on the current post-fix head (after findings, a clean re-review; the docs-only/mechanical exemption in step 4 above also satisfies this), and GitHub reports it mergeable.
   • The maintainer-approved label is the explicit approval (lifecycle step 4). It must still be on the PR (gh pr view --json labels); its latest labeled event (gh api --paginate repos/dartsim/dart/issues/<PR>/events) must have the maintainer as actor and follow any head_ref_force_pushed, base_ref_changed or reopened event and the latest pull_request run for this PR (gh api "repos/dartsim/dart/actions/runs?event=pull_request& head_sha=<SHA>", pull_requests[].number) on the last commit that is not a conflict-free base merge, or on the first later commit with one. If none does, ask for a fresh label. Never add it yourself.
   • Use the current head SHA when merging so a moved branch cannot be merged accidentally.
6. Clean up after merge:
   • Confirm the PR merged and identify the head branch before deleting. After explicit maintainer/user approval, prefer merge-time deletion with the approved merge method and head SHA:

     gh pr merge <PR_NUMBER> --squash --match-head-commit <HEAD_SHA> --delete-branch
     

   • After explicit maintainer/user approval, otherwise delete only the PR branch after confirming it has landed (git push origin --delete <HEAD_BRANCH>, then update the local checkout); force-delete locally only after explicit maintainer/user approval and after confirming the branch landed — squash/rebase merges do not preserve the branch tip in target-branch ancestry.

Output

Report:

• PR number, URL, base, head, draft state, milestone, and merge status.
• CI summary, review summary, and whether @codex review was triggered.
• Commits pushed, merge action, and branch cleanup action.
• Remaining blockers or next action.