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, and rerunning failed CI jobs. It also covers 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, and never 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 and the milestone is set. An independent review must have 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). GitHub must report the PR 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. That event must 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.