/qt-qml-review

name: qt-qml-review
description: >-
  Invoke when the user asks to review, check, audit, or look
  over Qt6 QML code -- or suggest before committing. Runs
  deterministic linting (48+ rules) then deep-analysis agents
  (scaled to the size of the change) covering
  bindings, layout, loaders, delegates, states, and performance.
  Optionally invokes system qmllint for type-level checks.
  Reports only high-confidence issues (>80/100) with structured
  mitigations. Read-only -- never modifies code.
license: LicenseRef-Qt-Commercial OR BSD-3-Clause
compatibility: Designed for Claude Code, GitHub Copilot, and similar agents.
disable-model-invocation: false
metadata:
  author: qt-ai-skills
  version: "2.0"
  qt-version: "6.x"
  category: review

Qt QML Code Review

Read-only review of Qt6 QML code: a deterministic Python linter (with qmllint folded in when available) first, then agent-driven deep analysis across seven rule domains, then one consolidated report. Suggest it before the user commits QML code.

Scope detection

**Diff scope** -- "this commit", "these changes", "the diff", "what I changed", "staged changes", "before I commit". The range is `HEAD` (working tree plus index), `--cached` for staged changes only, or `HEAD~1..HEAD` for "this commit". Do not load the diff itself: the linter's `--diff` mode (Phase 1) lists the changed files with their changed-line counts and reports only findings on changed lines.

**Codebase scope** -- "review the codebase", "audit src/", or an explicit path with no commit language. Glob `*.qml` under the path.

Token budget rules

These rules exist to keep the review cheap. Follow them.

1. **Do not load the reference files into the main context.** Agents read `references/agent-rules.md` themselves; you pass its absolute path and the section IDs. Only an inline run (Phase 2) reads it in the main context. Lint messages are self-describing; the checklist is for humans. 2. **Pass lint results in `--summary` form** (grouped by rule, paths relative to a root printed once), never the raw per-line listing or qmllint's JSON. 3. **Point agents at content, never paste it.** Every token you write into a prompt is output on the orchestrating model, the most expensive tokens in the review. Prompts carry paths, commands and section IDs; the agents load the rules, the files and the diff. In diff scope an agent gets the `git diff -U50 <range> -- <files>` command instead of the hunks, and reads other files only to trace a specific symbol. 4. **Scale the agent count to the scope** (see Phase 2). Launch no agents for a small scope and split a large one into shards of about equal line count. 5. **Use the dedicated review agent where the tool has one.** If the `qt-development-skills:qml-review-agent` definition shipped with this plugin is available, launch the agents with it (read-only, tools limited to Read, Grep, Glob and read-only Bash); otherwise use the tool's general-purpose agent.

Execution order

Never skip a phase.

Phase 1: Linting (Python linter + qmllint)

# codebase scope
python3 <skill>/references/lint-scripts/qt_qml_lint.py --summary --qmllint <files...>
# diff scope, run inside the repository; no file arguments
python3 <skill>/references/lint-scripts/qt_qml_lint.py --summary --qmllint --diff=<range>
# fall back to `python` if python3 is not found

Python 3.7+, no dependencies. If Python is unavailable, warn and continue (in diff scope, take the file list from `git diff --stat <range>`). The linter is authoritative; do not second-guess its output. Rule families: IMP, ORD, BND, LAY, LDR, DEL, STA, IMG, PRF, STY, SIG, ERR, JS (48+ checks). Exit code 1 simply means findings exist; 2 means a usage or git error.

`--qmllint` also runs qmllint and merges its warnings as `QL:<id>` rows; add `--qmllint-args="-I <dir>"` for a build directory with QML modules. The linter looks in `$QT_HOST_PATH/bin`, on PATH, in the host bin directory reported by `qtpaths` or `qmake`, and in the newest Qt 6 kit of a Qt online installer under `~/Qt`, `C:\Qt` or `/opt/Qt` (`<version>/<kit>/bin`, kits such as `gcc_64`, `macos`, `msvc2022_64`, `mingw_64`). If it reports `not available` but Qt is installed elsewhere (a custom installer path, or `CMAKE_PREFIX_PATH` in the project's `CMakeCache.txt`), rerun once with `--qmllint=<that kit>/bin`; it accepts the binary or its bin directory. Do not search further. Copy the printed `qmllint:` status into the report header. qmllint is authoritative for type-level issues, the Python linter for style, ordering and performance patterns.

Phase 2: Deep analysis (inline, or one agent per shard)

The seven sections of `references/agent-rules.md` are the analysis. Agents read it themselves; read it yourself only when running inline:

| Section | Mission | |---|---| | A1 | Bindings & Properties | | A2 | Layout & Anchoring | | A3 | Component Loading & Lifecycle | | A4 | ListView & Delegates | | A5 | States, Transitions & Migration | | A6 | Performance & Code Quality | | A7 | Logic & Wiring |

Choose the fan-out from the scope size. Count the lines of the files in scope (the changed lines in diff scope), taken from the lint summary or `wc -l`. A block is about 1,500 lines; the line count alone decides the split, never the number of files.

| Scope | Agents | |---|---| | Up to 1,500 lines | 0 (inline) | | More than 1,500 lines | one per shard, `ceil(lines / 1500)` shards |

**Inline.** A small scope does not repay the cost of agents, which each rebuild the context and roughly double the review's token cost for the same findings. Do the analysis yourself: read `references/agent-rules.md` and the files (or the diff) with the one Bash call shown under the agent prompt below, and apply A1-A7 in a single pass under the same rules, confidence thresholds and output format. Do not re-report lint rows, and do not run inline above the limit because the code looks simple. Report `