dart-manage-pr

name	dart-manage-pr
description	DART Manage PR: manage an open DART pull request through CI, review, merge, and cleanup

dart-manage-pr

Use this skill in Codex to run the DART dart-manage-pr workflow. The editable workflow source lives in .claude/commands/; this file is its generated adapter in the shared .agents/skills/ catalog.

Invocation

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

Treat the text after the skill name 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/ci-cd.md @docs/onboarding/testing.md @docs/onboarding/ai-reviews.md

Modes

• mode=manage (default): run the full PR-management loop below to the next terminal state.
• mode=merge: maintainer-only. Complete the local pre-merge validation in step 6 and merge a ready PR only after explicit maintainer/user approval for the 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, and 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, PR description/metadata corrections, resolving already-addressed review threads, rerunning failed CI jobs, and requesting a fresh AI review after follow-up fixes. It does not cover merging the PR into the target branch, 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 the PR is mergeable with required checks complete and addressed review threads resolved, or until 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 that the base branch, title, and PR template are correct.
   • Verify the milestone is set before merge: DART 7.0 for a main base, the branch-matching DART 6.x release milestone for a release-* base. If it is missing, set it only after explicit maintainer/user approval.
   • For bug fixes, verify the required DART 6 LTS + main dual-PR flow.
   • 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.
   • Apply the PR-writing guidance in docs/onboarding/contributing.md#submitting-a-pull-request: a concrete problem and solution, important decisions first, and claim-relevant evidence with visible limitations. Read the rendered body against the current diff; rewrite stale content rather than appending a repair diary.
   • Ensure transient visual evidence (screenshots, headless renders, GIFs, videos) is hosted as GitHub attachments rather than committed to the branch; pixi run evidence-publish renders the section and its upload placeholders (docs/onboarding/agent-sim-verification.md).
   • When the claim depends on 3D structure or behavior, require Visual verification produced through dart-verify-sim with the claim it explains, or the guide's documented unavailable-evidence handling. Verify it agrees with the text oracle, covers explicit claims, names what is not proved and any limitations, records view/debug layers, and includes reproduce commands.
   • 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.

Output

Report:

• PR number, URL, base, head, draft state, milestone, and merge status.
• CI summary: passing, failing, pending, or skipped checks.
• Review summary, independent-review status, and whether @codex review ran.
• Reviewed head, completed round count, trigger/completion evidence, and any strategy-checkpoint outcome or missing review coverage.
• Local pre-merge validation state when mode=merge ran.
• Commits pushed, merge action, and branch cleanup action.
• Remaining blockers or next action.