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. ```sh 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: ```sh 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.