dart-pr

name: dart-pr description: "DART PR: create a branch, commit, push, and open a DART pull request"

Use this skill in Codex to run the DART dart-pr workflow. The editable workflow source currently lives in .claude/commands/, and this generated Codex skill is a first-class Codex entrypoint.

Invocation

Claude Code/OpenCode: /dart-pr <arguments>
Codex: $dart-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

Prepare or open a DART pull request after explicit maintainer/user approval: $ARGUMENTS

Required Reading

@AGENTS.md @docs/onboarding/contributing.md @docs/onboarding/ai-tools.md @.github/PULL_REQUEST_TEMPLATE.md

Recent PR Patterns

When the expected PR style is unclear, inspect recently merged PRs before drafting the title or body:

gh pr list --repo dartsim/dart --state merged --base main --limit 10 \
  --json number,title,body,mergedAt

Use these practices:

Keep titles plain, scoped, and outcome-focused. Do not add agent prefixes.
Fill the PR template in DART's default order: Summary, Motivation / Problem, Changes / Key Changes, optional Before / After, Testing, Breaking Changes, and Related Issues / PRs. Keep Summary first because reviewers need the skimmable outcome before the rationale. If the motivation is necessary to understand the outcome, make the first Summary sentence problem-oriented, then put the fuller why in Motivation / Problem rather than moving Motivation above Summary.
Write the opening Summary and Motivation from the perspective of a user or downstream maintainer who is not already familiar with the implementation: lead with what changes for them, what stays compatible, how they would opt in or migrate, and why the evidence matters. Keep implementation details in Changes unless they explain a user-visible outcome or risk.
When the change has meaningful user-facing API, workflow, behavior, or performance impact, add a concise ## Before / After section before Testing. Use a small table or bullets that cover only relevant dimensions such as public API, commands/workflows, behavior, migration, and performance baseline. Phrase each row as a user-visible before/after, then name the implementation mechanism only as supporting context. For performance claims, name the baseline explicitly: CPU path, parent commit, main, or prior implementation, plus workload, metric, and important limitations.
In Testing, list exact commands, targets, or test names that ran.
For CI, performance, or infrastructure work, include evidence such as CI run observations, timing, reruns, benchmark output, or why a skipped check is expected.
For rendering, model, mesh, texture, GUI, or visual-example changes, include a before/after visual comparison when practical:
- Prefer an existing headless example path such as --headless, --frames, --width, --height, and --screenshot over manual screenshots.
- Capture the before image from the base branch or by temporarily restoring the replaced sample/assets, then capture the after image from the final branch with the same camera, dimensions, frame count, and renderer.
- Inspect the images yourself and include the commands plus any environment variables such as software rendering flags in the PR body.
- Upload transient comparison images, GIFs, and videos through the GitHub PR/issue Markdown attachment flow so the PR body contains GitHub-hosted https://github.com/user-attachments/assets/... URLs that render inline. Do not commit screenshots, headless renders, GIFs, or screencast videos solely as PR evidence. Commit visual files only when they are durable documentation, fixtures, or source assets that should live in the repository.
- The official GitHub attachment flow is the web PR/issue editor drag/drop or file picker. gh pr edit, gh pr comment, and the public REST API do not provide a supported generic attachment upload command; any command or action that edits or comments on a PR still requires explicit maintainer/user approval. Use a maintainer-approved upload helper only when it produces GitHub attachment URLs without committing files to the branch; helpers that mimic the web upload may require a browser session cookie and must not be used unless the maintainer has explicitly approved that credential handling.
- If the current tool cannot upload PR attachments, keep the local artifact paths in the working note, ask a maintainer to upload them through the PR editor, and then update the PR body with the returned GitHub attachment URL after explicit maintainer/user approval. Do not fall back to committing transient evidence into docs/assets/.
- If no headless path exists, either add a narrowly scoped capture mode when it fits the example or document why visual comparison is not practical.
Mark non-applicable checklist items as "N/A" with a short reason.
Mention related PRs, issues, backports, and follow-ups explicitly, including "None" when there is no related work.

Workflow

Inspect scope:

git status --short --branch
git diff --stat
git diff --check

Exclude unrelated dirty files unless the user explicitly includes them.
Choose the target branch and milestone:

Target Milestone

main DART 7.0

release-6.17 DART 6.17.1
For bug fixes, use the dual-PR flow: fix release-6.17 first, then cherry-pick or reapply to main.
Before every commit, run:
```
pixi run lint
```
Also run pixi run build for C++ or Python changes and focused tests for behavior changes.

Target	Milestone
`main`	`DART 7.0`
`release-6.17`	`DART 6.17.1`

Create or update a topic branch when needed:

git checkout -b <type>/<topic> origin/<target-branch>

Commit only intended files with a plain descriptive commit title.
Ask for explicit maintainer/user approval before pushing or opening the draft PR. If approved:
```
git push -u origin HEAD
gh pr create --draft --base <target-branch> --milestone "<milestone>" \
  --title "<plain title>" --body-file <filled-template-file>
```
For fast feedback on a draft PR, also request Codex review after publication when approval covers PR comments:
```
gh pr comment <PR_NUMBER> --body "@codex review"
```
If Codex already shows an activity signal or submitted review, do not post a duplicate trigger.
After a PR is published, prefer additive follow-up commits for updates so reviewers can inspect each review round. Amend or force-push only after explicit maintainer/user approval and only when the user explicitly requests it or when there is a clear reason such as removing sensitive content or repairing broken branch history.
Before every push to a published PR branch, first merge the latest base branch into it (on every push, not just the first) so each pushed/CI-tested state reflects current main and conflicts surface early:
```
git fetch origin <target-branch>
git merge --no-ff origin/<target-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. Do not rebase a published PR branch by default because it invalidates existing CI runs and makes PR review/comment history harder to follow. Rebase or force-push only when the maintainer explicitly requests it.
If CHANGELOG.md needs the PR number, keep the follow-up changelog commit local until explicit maintainer/user approval is given for the additional push or PR update.
Monitor CI:
```
gh pr checks <PR_NUMBER>
```

AI Review Comments

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]. When a draft PR is first published, a top-level @codex review is the preferred fast path once explicit maintainer/user approval covers PR comments; it can run while the PR remains draft. Make fixes silently. Push and ask for a new AI review with @codex review only after explicit maintainer/user approval and only when the approved follow-up push addressed Codex review comments, or when the first trigger has a concrete timeout/blocker.

After Codex returns no actionable issues and local validation passes on the current head (default pixi run test-all, plus pixi run -e cuda test-all on Linux hosts with a visible NVIDIA CUDA runtime), a draft PR is ready to mark ready for human review after explicit approval even if hosted CI is still pending. Do not merge until branch protection and required checks pass unless a maintainer explicitly approves a policy bypass.