utm-review

utm-review

Agent-neutral instructions — follow them with whatever tools your agent provides (Claude Code, Codex, OpenCode, Antigravity, …). This is the canonical copy; the per-agent entries under .claude/commands/, .opencode/command/, etc. just point here.

Gate a UTM change through two passes before it can be submitted:

1. A standard code review for real correctness bugs and worthwhile cleanups.
2. A UTM contribution-guideline audit — the part specific to this project and the reason this workflow exists. UTM has firm rules (especially for AI-assisted contributions) that a generic review won't check.

Report everything you find. This workflow reviews and reports; it does not push, commit, or rewrite history — that is /utm-submit's job.

If you were invoked with an argument, treat it as a review effort level (low|medium|high|max); default to high.

Step 1 — Read the authoritative rules

Read CONTRIBUTING.md and AGENTS.md at the repo root now — they are the single source of truth for what makes an acceptable UTM contribution, and Step 4 audits the diff against them. (AGENTS.md overrides default tool behavior for this repo — notably the commit-trailer policy.)

Step 2 — Establish the review scope

The change under review is everything that will land in the PR: commits on this branch since it diverged from the base, plus any uncommitted edits.

base=$(git merge-base HEAD origin/main)
git log --oneline "$base"..HEAD          # the PR's commits
git --no-stat diff "$base"...HEAD        # committed change
git --no-stat diff HEAD                  # uncommitted change (if any)
git status --porcelain                   # untracked files

Keep the list of changed files handy — several guideline checks below hinge on which files were touched.

Step 3 — Standard code review

Run a standard code review of the pending diff to surface correctness bugs and reuse/simplification/efficiency cleanups. Use whatever review capability your agent provides — for example a /code-review or /review command — or perform a focused review pass yourself if none exists. If the change includes uncommitted edits the review tool doesn't pick up, review those yourself to the same standard. Collect the findings; you'll merge them into one report.

Step 4 — UTM contribution-guideline audit

Audit the diff against every rule in the CONTRIBUTING.md and AGENTS.md you just read — those files are the checklist, so keeping it there (rather than copied here) means it never drifts out of sync. Cite file:line and the specific rule for each issue you raise. Judge the diff against all of it: style and concurrency, design philosophy, platform compatibility, dependency-upstreaming, and the rest — defer to the files' wording instead of restating it.

These few are high-value, repo-specific, and the easiest to miss, so check them explicitly:

• AI attribution. Every AI-assisted commit in "$base"..HEAD must carry an Assisted-by: AGENT:MODEL trailer — many agents omit it by default, so a missing trailer is a common, easy-to-miss finding, not an acceptable absence — and no Co-authored-by (strip it — UTM takes full human responsibility per the Linux-kernel policy). Verify with git log --format='%H%n%B' "$base"..HEAD.
• Scope discipline. One feature/fix; no edits, refactors, reformatting, or whitespace/header churn in unrelated files; no stray logging.
• Generated files not hand-edited — Configuration/QEMUConstantGenerated.swift, Scripting/UTMScripting.swift, QAPI/QMP wrappers. Edit the generator instead.
• Logging goes through UTMLogging/logging at debug level (warnings and errors excepted); bring-up-only logging is removed before committing.
• UI strings avoid jargon ("GPU Acceleration" not "Venus", "Apple Silicon" not ARM64); commit titles are component: short description explaining why.

Step 5 — Report

Produce one consolidated report:

• A one-line summary of the change and its apparent scope.
• Correctness/quality findings (from Step 3), each with file:line.
• Guideline findings (from Step 4), each with file:line and the rule cited.
• A short verdict: is this ready to submit, or what must change first? Call out any blocker that /utm-submit will trip on (e.g. a Co-authored-by trailer, an unrelated-file edit, or a missing Assisted-by).

Be honest about uncertainty and avoid nitpicks a senior reviewer wouldn't raise (pre-existing issues, things a compiler/linter would catch, lines the change didn't touch). The goal is a change that sails through human review on the UTM repo, not a wall of pedantry.

Step 6 — Record that the review ran (handoff to /utm-submit)

/utm-submit checks whether the current changes were reviewed. Leave a marker so it can confirm even across sessions or a different agent:

gitdir=$(git rev-parse --git-dir)
hash=$( { git rev-parse HEAD; git diff "$(git merge-base HEAD origin/main)"...HEAD; git diff HEAD; } | git hash-object --stdin )
printf 'branch=%s\nhead=%s\ndiff_hash=%s\nat=%s\n' "$(git rev-parse --abbrev-ref HEAD)" "$(git rev-parse HEAD)" "$hash" "$(date -u +%FT%TZ)" > "$gitdir/utm-review-marker"

Then end with a clear, recognizable line, e.g.: ✅ utm-review complete — <branch> @ <short-sha>, N findings (M blockers).

The diff_hash lets /utm-submit tell whether the changes it's about to submit are exactly the ones you reviewed, or whether they've been edited since.