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.
Designed for Claude Code, GitHub Copilot, and similar agents.
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.
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
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:
Pass --framework to the linter (if supported)
Load references/qt-framework-checklist.md alongside the
universal checklist
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.
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.
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:
The list of files in scope
The Phase 1 lint output (so they skip already-flagged issues)
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
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
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
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
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)
