dart-pr

Use this skill in Codex to run the DART dart-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/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
@docs/onboarding/changelog.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 keep the fuller why in Motivation / Problem rather than moving it above
  Summary.
• Write Summary and Motivation for a user or downstream maintainer unfamiliar
  with the implementation: lead with what changes for them, what stays
  compatible, how they opt in or migrate, and why the evidence matters. Keep
  implementation mechanics in Changes unless they explain a user-visible
  outcome or risk.
• When the change has user-facing API, workflow, behavior, or performance
  impact, add a concise ## Before / After section before Testing covering
  only relevant dimensions (public API, commands/workflows, behavior,
  migration, performance baseline). Phrase each row as a user-visible
  before/after, then name the mechanism as supporting context. For performance
  claims, name the baseline explicitly (CPU path, parent commit, main, or
  prior implementation) plus workload, metric, and limitations.
• In Testing, list exact commands, targets, or test names that ran. For CI,
  performance, or infrastructure work, include evidence such as CI observations,
  timing, reruns, benchmark output, or why a skipped check is expected.
• For model/scene, dynamics, collision/contact, simulation, rendering, mesh,
  texture, GUI, or visual-example changes, use dart-verify-sim: report the
  text correctness oracle and include assessed, claim-relevant visual/debug
  evidence when applicable (an image alone is not correctness proof):
  • Prefer an existing headless example path (--headless, --frames,
    --width, --height, --screenshot) over manual screenshots. Capture
    before and after with the same camera, dimensions, frame count, and
    renderer; restore the replaced sample/assets or use the base branch to
    capture the before image. Inspect the images yourself and include the
    commands and any software-rendering flags in the PR body.
  • Upload transient comparison images, GIFs, and videos through the GitHub
    PR/issue Markdown attachment flow so the body contains GitHub-hosted
    https://github.com/user-attachments/assets/... URLs. Do not commit
    transient visual evidence; commit visual files only when they are durable
    documentation, fixtures, or source assets.
  • The supported attachment flow is the web PR/issue editor; gh pr edit,
    gh pr comment, and the REST API do not provide a generic upload, and any
    command that edits or comments on a PR still requires explicit
    maintainer/user approval. If the current tool cannot upload attachments,
    keep the local artifact paths in the working note, ask a maintainer to
    upload them, then update the PR body with the returned URL after explicit
    maintainer/user approval. Do not fall back to committing evidence into
    docs/assets/.
  • If no headless path exists, 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, and mention
  related PRs, issues, backports, and follow-ups explicitly, including "None".

Workflow

1. Inspect scope:

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

2. Exclude unrelated dirty files unless the user explicitly includes them.

3. Choose the target branch and milestone:

   Target	Milestone
   main	DART 7.0
   Active DART 6 LTS release-6.*	Branch-matching DART 6.x patch

4. For bug fixes, use the dual-PR flow: fix the active DART 6 LTS branch first,
   then cherry-pick or reapply to main.

5. Before every commit, run pixi run lint. Also run pixi run build for C++
   or Python changes and focused tests for behavior changes.

6. Create or update a topic branch when needed:

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

7. Commit only intended files with a plain descriptive commit title.

8. Merge the latest base branch into the PR branch before any push, and follow
   the base-merge and automated-review rules in docs/onboarding/ai-tools.md
   (no inline bot replies; @codex review re-triggers are throttled to one per
   approved review-fix round). Ask for explicit maintainer/user approval before
   pushing or opening the draft PR. After approval:

   git push -u origin HEAD
   gh pr create --draft --base <target-branch> --milestone "<milestone>" \
     --title "<plain title>" --body-file <filled-template-file>

9. Prefer additive follow-up commits for updates to a published PR. Amend or
   force-push only after explicit maintainer/user approval and only when the
   user requests it or a clear reason exists (removing sensitive content,
   repairing branch history).

10. Invoke the dart-changelog routine for the changelog decision, entry
    wording, and PR-link follow-up. 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.

11. Monitor CI: gh pr checks <PR_NUMBER>.

Output

• Branch, target base, and milestone used
• Commit titles and files included
• PR URL and draft/ready state, or the prepared PR text awaiting approval
• Changelog decision
• CI status and any remaining blocker