/qt-cpp-review

name: qt-cpp-review
description: >-
  Invoke when the user asks to review, check, audit, or look
  over Qt6 C++ code — or suggest before committing. Runs
  deterministic linting (60+ rules) then deep-analysis agents
  (scaled to the size of the change) covering model
  contracts, ownership, threading, API correctness, error
  handling, and performance. 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: "3.0"
  qt-version: "6.x"
  category: review
argument-hint: "[framework]"

Qt Code Review

Read-only review of Qt6 C++ code: a deterministic Python linter first, then agent-driven deep analysis across six rule domains, then one consolidated report.

When to use this skill

• Review-related requests: "review", "check", "audit", "look over",

"code review", "sanity check"

• Suggest it **before committing** code

Arguments

• `/qt-cpp-review` — universal Qt6 C++ rules
• `/qt-cpp-review framework` — also apply Qt framework/module rules

(binary compatibility, exports, d-pointers, qdoc, QML versioning)

Framework mode

Enable when `$ARGUMENTS` contains "framework". Otherwise, if the lint run or a quick Grep shows **two or more** of these signals, suggest framework mode to the user but do not enable it yourself: `QT_BEGIN_NAMESPACE`, any `Q_*_EXPORT` macro, `<QtModule/private/*_p.h>` includes, `Q_DECLARE_PRIVATE`/`Q_D()`/`Q_Q()`, `qt_internal_add_module` in CMakeLists.txt, `sync.profile` or `.qmake.conf` at the repo root.

When enabled: pass `--framework` to the linter, and name `references/qt-framework-checklist.md` in the prompts of the agents covering A2 or A4 (they apply it as mapped at the end of `agent-rules.md`). In diff scope, also check the commit message against the FW-CMT rules yourself; load only that section with `sed -n '/^## Commit Message/,$p' references/qt-framework-checklist.md`.

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 `*.cpp`, `*.h`, `*.hpp` 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 checklists are 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. 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 harness has one.** If the `cpp-review-agent` definition (listed as `qt-development-skills:cpp-review-agent` when installed with the plugin, plain `cpp-review-agent` when copied by hand) is available, launch the agents with it (read-only, tools limited to Read, Grep, Glob and read-only Bash); otherwise use the harness's general-purpose agent. The definition lives in the plugin's `agents/` directory, outside this skill, so it is missing when the skill was copied on its own or the harness does not install `agents/`. Then add one line to each prompt: read-only (Bash only for `cat`, `grep`, `awk`, `git diff`, `git show`); take `file:line` from the printed numbers; in diff scope do not re-read the files; Grep or Read other files only to trace a symbol; prefer few confirmed findings over many guesses.

Execution order

Never skip a phase.

Phase 1: Deterministic linting

# codebase scope
python3 <skill>/references/lint-scripts/qt_review_lint.py --summary [--framework] <files...>
# diff scope, run inside the repository; no file arguments
python3 <skill>/references/lint-scripts/qt_review_lint.py --summary [--framework] --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: INC, DEP, PAT, MDL, ERR, LCY, API, ENM, TMO, CND, VAL, HDR, TRN, VAR (60+ checks). Exit code 1 simply means findings exist; 2 means a usage or git error.

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

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

| Section | Mission | |---|---| | A1 | Model Contracts | | A2 | Ownership & Lifecycle | | A3 | Thread Safety | | A4 | API, Naming & C++ Correctness | | A5 | Error Handling & Validation | | A6 | Performance & Code Quality |

Choose the fan-out from the scope size. Count the lines of the files in scope (the changed lines in diff scope), taken from