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 six parallel deep-
  analysis agents 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: "2.0"
  qt-version: "6.x"
  category: review
argument-hint: "[framework]"
---

# Qt Code Review

A structured, read-only code review skill for Qt6 C++ code that
combines deterministic linting with parallel agent-driven deep
analysis across six focused domains.

## When to use this skill

- When the user mentions review-related tasks: "review", "check",
  "audit", "look over", "code review", "sanity check"
- Suggest running this skill **before committing** code
- When the user asks to validate Qt6 C++ code quality

## Arguments

- `/qt-cpp-review` — review using universal Qt6 C++ rules only
- `/qt-cpp-review framework` — also apply Qt framework/module
  development rules (BC, exports, d-pointers, qdoc, QML
  versioning)

## Framework mode detection

If `$ARGUMENTS` contains "framework", enable framework mode.

If the argument is not passed, auto-detect by scanning the first
few files in scope for framework signals. If **two or more** of
the following are found, suggest to the user:
"This looks like Qt framework/module code. Run
`/qt-cpp-review framework` to also apply framework-specific
rules (BC, exports, qdoc, QML versioning)?"

**Framework signals** (any two = likely framework code):
- `QT_BEGIN_NAMESPACE` / `QT_END_NAMESPACE`
- `Q_CORE_EXPORT`, `Q_GUI_EXPORT`, `Q_WIDGETS_EXPORT`, or any
  `Q_*_EXPORT` macro
- `#include <QtModule/private/*_p.h>` (private headers)
- `Q_DECLARE_PRIVATE`, `Q_D()`, `Q_Q()`
- `qt_internal_add_module` or `qt_add_module` in CMakeLists.txt
- `sync.profile` or `.qmake.conf` in the repository root

Do **not** auto-enable framework mode — only suggest it. Let the
user confirm.

When framework mode is enabled:
1. Pass `--framework` to the linter (if supported)
2. Load `references/qt-framework-checklist.md` alongside the
   universal checklist
3. Include framework rules in each agent's mission context

## Scope detection

Detect the user's intended scope from their language:

### Diff/commit scope (narrow)
Triggered by language like: "this commit", "these changes",
"the diff", "what I changed", "my changes", "staged changes",
"outstanding changes", "before I commit"

**Action**: Run `git diff` (unstaged) and `git diff --cached`
(staged) to obtain the changeset. If the user says "this commit",
use `git diff HEAD~1..HEAD`. Review only the changed lines plus
sufficient surrounding context (±50 lines) for understanding.
Only report issues found in the changed lines — do not report
issues in unchanged surrounding context.

### Codebase scope (wide)
Triggered by language like: "review the codebase", "audit the
project", "check the repository", "review src/", or when a specific
file/directory path is given without commit language.

**Action**: Glob for `*.cpp`, `*.h`, `*.hpp` files in the
specified scope. Review all matched files.

## Execution order

The review proceeds in three phases. **Never skip a phase.**

### Phase 1: Deterministic linting (scripts)

Run the unified Python linter against the target files. Requires
Python 3.6+ (no external dependencies). If Python is not
available, warn the user and skip to Phase 2.

```bash
python3 references/lint-scripts/qt_review_lint.py <files...>
# If python3 is not found, fall back to:
python references/lint-scripts/qt_review_lint.py <files...>
```

This single-pass scanner encodes all mechanically-checkable rules
from the Qt review guidelines. It reads each file once and
evaluates all rules per line. Output is deterministic and
repeatable. The linter is authoritative — do not second-guess
its output.

Collect all output before proceeding to Phase 2.

**Rule categories** (60+ checks):
- **INC** (Includes) — ordering, qglobal.h, qNN duplication
- **DEP** (Deprecated) — obsolete Qt/std class usage
- **PAT** (Patterns) — anti-patterns (min/max, std::optional,
  NRVO, COW detach, etc.)
- **MDL** (Model) — QAbstractItemModel contract (begin/end
  balance, dataChanged roles, flags, default: in data())
- **ERR** (Error Handling) — QFile::open, QJsonDocument::isNull,
  QNetworkReply::error, SSL, timeouts, arg() mismatch
- **LCY** (Lifecycle) — deleteLater, Q_ASSERT side effects,
  null guards, unbounded containers, qDeleteAll depth
- **API** (Naming) — get-prefix, enum hygiene, QList<QString>
- **HDR/TMO/CND/VAL/TRN** — headers, timeouts, conditionals,
  value classes, ternary operator

### Phase 2: Agent-driven deep analysis (6 parallel agents)

Launch six focused review agents in parallel. Name each agent
descriptively when launching (e.g. "Agent 1: Model Contracts")
to provide progress visibility. Each agent has a tight scope
and a specific checklist. Agents are READ-ONLY — they must
never edit or write files.

**Tool-agnostic agent contract**: Each agent described below is
a self-contained review mission. In Claude Code, launch them as
general-purpose subagents. In other tools, implement each as
whatever subprocess, prompt chain, or analysis pass the tool
supports. The key requirement is that each agent:
- Has read access to all source files in scope
- Can search/grep the codebase to trace symbols
- Reports findings in the structured format below
- Applies confidence thresholds: >80 = confirmed finding,
  60–79 = investigation target (max 10 total across all
  agents), <60 = suppress
- Does NOT duplicate findings from Phase 1 lint output
  (pass lint output as context to each agent)

See **Agent missions** below for the six agents.

### Phase 3: Consolidation and reporting

Merge lint script output and all agent findings. Deduplicate
(same file+line+issue = one finding). Apply confidence scoring.
Format the final report using the output format below.

## Agent missions

Launch all six agents in parallel. Pass each agent:
1. The list of files in scope
2. The Phase 1 lint output (so they skip already-flagged issues)
3. Their specific mission below

Each agent should read all files in scope, then focus on its
assigned categories.

---

### Agent 1: Model Contracts

**Scope**: QAbstractItemModel signal protocol, role system,
index validity, proxy model correctness.

**Check for**:
- `beginInsertRows`/`endInsertRows` balance — every structural
  model change (add/remove/move) must use the correct begin/end
  pairs. `layoutChanged` is NOT a substitute for insert/remove.
- `roleNames()` returning roles that `data()` does not handle
  (missing switch cases, fall-through to default)
- `dataChanged` emitted with empty roles vector (forces full
  refresh instead of targeted update)
- `beginRemoveRows` called with `first > last` (edge case when
  container is empty — QAIM contract violation)
- `flags()` returning inappropriate flags (e.g. `ItemIsEditable`
  for non-editable items)
- `setData()` returning true without emitting `dataChanged`
- Proxy models accessing source model internals instead of going
  through `data()`/`index()` API
- Filter/proxy models using source-model indices to index into
  filtered containers (wrong index space)

**References**: `references/qt-review-checklist.md` § Model
Contracts

---

### Agent 2: Ownership & Lifecycle

**Scope**: Memory ownership, parent-child, resource cleanup,
Rule of Five, RAII correctness.

**Check for**:
- Structs/classes with raw pointers where `new` is visible and
  no corresponding `delete`/`deleteLater`/smart-pointer wrapping
  exists (Rule of Five violation)
- Missing `deleteLater()` on QNetworkReply in finished handlers
- `Q_ASSERT` wrapping side-effectful expressions (compiled out
  in release builds — the side effect disappears)
- `Q_ASSERT` as the sole null guard (crashes in release)
- Polymorphic QObject subclasses missing `Q_DISABLE_COPY_MOVE`
- Polymorphic classes missing virtual destructor
- QTimer/QObject created with `new` but no parent and no other
  lifecycle management (scope, smart pointer, explicit delete)
- `QObject::connect()` called with potentially null
  sender/receiver outside a null guard (runtime warning)
- `m_recentlyAccessed`-style tracking lists that maintain
  pointers to objects that may be deleted elsewhere (dangling)
- Unbounded container growth (append without cap or trim)
- Destructor not cleaning up owned children recursively
- Abstract interfaces with no implementations beyond one class
  (YAGNI violation — codebase scope only)

**References**: `references/qt-review-checklist.md` § Ownership
& Lifecycle, § Polymorphic Classes, § RAII Classes

---

### Agent 3: Thread Safety

**Scope**: Cross-thread QObject access, mutex consistency,
signal emission from worker threads.

**Check for**:
- QObject member variables written from `QtConcurrent::run()`
  or `QThread` worker without synchronization (mutex, atomic,
  queued connection, or other thread-safe primitive)
- Signals emitted from worker threads connected with
  `Qt::DirectConnection` (or explicit non-queued connections)
  to main-thread receivers
- Model mutations (`addNote`, `removeRows`, etc.) from
  background threads
- Shared containers (`QList`, `QHash`) modified from multiple
  threads without consistent synchronization
- Non-atomic increment/decrement of shared counters
  (`m_operationCount++` from multiple threads)
- QTimer or other QObject operations from non-owner thread

**References**: `references/qt-review-checklist.md` § Thread
Safety

---

### Agent 4: API, Naming & C++ Correctness

**Scope**: Qt naming conventions, const-correctness, move
semantics, enum hygiene, noexcept correctness.

**Check for**:
- `get`-prefix on mere getters (Qt reserves `get` for user
  interaction or out-parameter decomposition)
- Non-const getter methods (especially Q_PROPERTY READ
  accessors — UB via meta-object system)
- Missing `std::forward<T>()` on forwarding/universal references
- `return std::move(localVar)` preventing NRVO
- `const` local variable preventing implicit move on return
  (e.g. `const QJsonDocument doc(...); return doc;` forces copy)
- `const` method returning mutable pointer through raw pointer
  indirection (`findById() const` returning `T*` lets callers
  mutate via a const accessor — const doesn't propagate through
  raw pointers)
- `noexcept` on functions containing `Q_ASSERT` (incompatible —
  Q_ASSERT may throw for testing, noexcept terminates)
- Unscoped enums without explicit underlying type
- Missing trailing comma on last enumerator
- `switch` over enum with `default:` label (suppresses -Wswitch)
- `QList<QString>` instead of `QStringList`
- Missing `const` on methods that don't modify state
- Case-sensitive string comparison for user-facing sort
- Duplicated validation logic across classes
- `const QMetaObject::Connection` preventing handle cleanup

**References**: `references/qt-review-checklist.md` § API &
Naming, § Enums, § Methods, § Move Semantics, § Operators

---

### Agent 5: Error Handling & Validation

**Scope**: Missing error checks, input validation, security.

**Check for**:
- `QFile::open()` return value ignored
- `QJsonDocument::fromJson()` result not checked for
  `isNull()`/`isObject()` before use
- `QNetworkReply::error()` not checked before `readAll()`
- XML writer `hasError()` not checked after writing
- Hardcoded `http://` instead of `https://` in URLs
- No SSL error handling (`QNetworkAccessManager::sslErrors`)
- No timeout on network requests (`setTransferTimeout`)
- Negative values accepted where only positive are valid
  (e.g. timer intervals, font sizes)
- No schema/version validation on imported data
- No input length validation on imported/downloaded data
  (unbounded strings from untrusted sources)
- `QString::arg()` with wrong placeholder count
- `saveToFile()` returning true regardless of I/O errors
- Inconsistent error reporting patterns across methods

**References**: `references/qt-review-checklist.md` § Error
Handling & Validation

---

### Agent 6: Performance & Code Quality

**Scope**: Performance anti-patterns, dead code, unnecessary
copies, code smells.

**Check for**:
- `QRegularExpression` constructed inside a loop (expensive
  compilation on every iteration)
- `roleNames()` rebuilding QHash on every call (should cache)
- Non-const range-for over COW-shared QList/QHash triggering
  unnecessary detach/deep-copy
- Non-const `operator[]` on shared QHash (triggers detach) —
  use `.value()` for reads
- Expensive operation before cheap early-exit check (wasted
  allocation)
- Dead/unreachable code (functions never called, branches
  that are always true/false given preconditions)
- Magic numbers without named constants
- God classes violating Single Responsibility
- Copy-pasted validation/logic across classes
- Stale member caches not invalidated on model changes
  (e.g. search cache surviving data edits)
- `QMap`/`QHash` iteration order nondeterminism when selecting
  a "best" or "first" entry (`.first()` changes if keys are
  added; use deterministic tie-breaking)
- `QMap` for small fixed-size constant data (use array/switch)
- Returning QList/container by value from frequently-called
  methods (implicit deep copy on every call — return const ref
  or cache)
- Member variables maintained (appended, capped) but never
  read by any method (dead state — wasted CPU and memory)
- Missing re-entrancy guard on methods that emit signals
  which could trigger re-entry
- Setter silently resetting unrelated state without signal
- Early return skipping status/signal updates

**References**: `references/qt-review-checklist.md` §
Performance & Code Quality

---

## Confidence scoring guidelines

| Confidence | Meaning | Action |
|------------|---------|--------|
| 90–100 | Certain: direct rule violation with full symbol trace | Report as finding |
| 80–89 | High: rule violation confirmed but edge case possible | Report as finding |
| 60–79 | Medium: likely issue but cannot fully verify | Report as investigation target |
| <60 | Low: suspicion only | Suppress entirely |

**Investigation targets** are findings the agent believes are real
but cannot fully verify — e.g. noexcept correctness requiring
whole-program analysis, dead code that may have callers outside
scope, or design-intent judgments like virtual access levels.
These are presented in a separate section for human verification.
Maximum 10 investigation targets per report, prioritized by
confidence within the 60–79 band.

## Output format

Present the final report as follows. Use exactly this structure.

```
## Qt Code Review Report

**Scope**: [diff: `git diff HEAD~1..HEAD` | files: <paths>]
**Files reviewed**: N
**Issues found**: N (M from lint, K from deep analysis)

---

### Lint findings

For each lint finding:

#### [L-NNN] <Short title>
- **File**: `path/to/file.cpp:42`
- **Rule**: <rule ID from checklist>
- **Finding**: <what the script detected>
- **Mitigation**: <what to do, in prose — no code patches>

---

### Deep analysis findings

For each agent finding:

#### [D-NNN] <Short title>
- **File**: `path/to/file.cpp:42`
- **Category**: <agent name: Model Contracts | Ownership &
  Lifecycle | Thread Safety | API & C++ Correctness | Error
  Handling | Performance & Quality>
- **Confidence**: NN/100
- **Finding**: <description of the issue>
- **Trace**: <how the issue was confirmed — which symbols were
  followed, what was checked>
- **Mitigation**: <what to do, in prose — no code patches>

---

### Investigation targets (human verification needed)

Findings the agent identified but could not fully verify.
Maximum 10, sorted by confidence. These require human judgment.

For each investigation target:

#### [I-NNN] <Short title>
- **File**: `path/to/file.cpp:42`
- **Category**: <agent name>
- **Confidence**: NN/100
- **Finding**: <what the agent suspects>
- **Unverified because**: <what the agent could not confirm —
  e.g. "cannot trace all callees for throw potential",
  "only one implementation visible in scope">
- **How to verify**: <specific action for the reviewer>

---

### Summary

| Category | Lint | Deep | Investigate | Total |
|----------|------|------|-------------|-------|
| ...      | N    | N    | N           | N     |
| **Total**| **M**| **K**| **I**       | **N** |

Findings below confidence 60 are suppressed entirely.
```

## References

The following reference files contain detailed checklists
extracted from the Qt wiki "Things To Look Out For In Reviews":

- `references/qt-review-checklist.md` — Universal Qt6 C++ review
  rules (always loaded)
- `references/qt-framework-checklist.md` — Qt framework/module
  development rules (loaded only in framework mode)
- `references/qt-deprecated-classes.md` — Classes and patterns
  that should no longer be used in Qt implementation
- `references/lint-scripts/qt_review_lint.py` — Single-pass
  Python linter (runs all 60+ checks in <1s)