Revision control
++ # Agent Comparison
++
++ ## At a Glance
++
++ | Agent | What It Does | Input | Output |
++ |-------|-------------|-------|--------|
++ | **qt-doc-reviewer** | Reviews existing doc patches for style, QDoc, linking, alt text | Gerrit URL or patch diff | Doc-diff suggestions |
++ | **qdoc-warning-fixer** | Diagnoses and fixes QDoc build warnings | Warning text or log file | Doc-diff fixes |
++ | **doc-impact-analyzer** | Predicts doc breakage from code changes *before* warnings appear | Commit SHA or code diff | Impact report (Breaking/Stale/Cosmetic) |
++ | **doc-shaper** | Creates new documentation from source code | Header/source files or module path | Doc-diff with new/stub docs |
++ | **doc-structure-auditor** | Audits a module's entire doc structure for health | Module name/path | Audit report (Missing/Orphan/Broken/Incomplete) |
++ | **doc-builder** | Builds documentation locally | Product/module name + branch | Build output or troubleshooting |
++ | **artifact-tester** | Tests a skill or agent against the 9-layer methodology | Skill/agent path or Gerrit change | Per-layer report + verdict + fixture |
++
++ ## Sample Prompts
++
++ | Agent | Example |
++ |-------|---------|
++ | **qt-doc-reviewer** | "Review https://codereview.qt-project.org/c/qt/qtbase/+/612345" |
++ | **qdoc-warning-fixer** | "Fix: src/gui/doc/src/richtext.qdoc:42: (qdoc) Cannot find 'QTextFormat::type' in any header file" |
++ | **doc-impact-analyzer** | "Does commit abc123 (renamed QFoo to QBar) break any docs?" |
++ | **doc-shaper** | "Write full docs for qtbase/src/corelib/io/qsavefile.h" |
++ | **doc-structure-auditor** | "Audit Qt Wayland Compositor module documentation health" |
++ | **doc-builder** | "Build Qt Multimedia docs from dev branch" |
++ | **artifact-tester** | "Test the skill at skills/skill-line-wrap using artifact-tester" |
++
++ ## Pipeline View
++
++ The agents form a natural pipeline with minimal overlap:
++
++ ```
++ Code change
++ -> doc-impact-analyzer (predict what will break)
++ -> doc-shaper (create missing docs)
++ -> doc-builder (build to get warnings)
++ -> qdoc-warning-fixer (fix warnings from build)
++ -> qt-doc-reviewer (review the final patch)
++ -> doc-structure-auditor (periodic health check)
++ ```
++
++ ## Overlap Analysis
++
++ ### Where Boundaries Touch
++
++ 1. **qt-doc-reviewer vs qdoc-warning-fixer** — Both fix QDoc issues, but
++ the reviewer works from *patches* (human-authored changes) while the
++ warning-fixer works from *QDoc build output* (compiler warnings). The
++ reviewer checks language/style; the warning-fixer doesn't.
++
++ 2. **doc-impact-analyzer vs qdoc-warning-fixer** — Both deal with broken
++ references, but impact-analyzer is *predictive* (before the build) while
++ warning-fixer is *reactive* (after warnings appear).
++
++ 3. **doc-shaper vs qdoc-warning-fixer** — Both can write new documentation.
++ The shaper creates docs from scratch (header -> full docs). The
++ warning-fixer only writes the minimum needed to resolve a specific
++ warning (e.g., adding a missing `\brief`).
++
++ 4. **doc-structure-auditor vs doc-impact-analyzer** — Both find broken
++ links, but the auditor does a *broad module sweep* while the
++ impact-analyzer does *targeted analysis* of a specific change.
++
++ No real redundancy. Each has a distinct trigger (patch, warning, code
++ change, header, module, build) and a distinct goal.
++
++ ## Deep Dive: doc-shaper vs doc-structure-auditor
++
++ ### Core Difference
++
++ | | doc-shaper | doc-structure-auditor |
++ |---|---|---|
++ | **Verb** | *Creates* | *Inspects* |
++ | **Question it answers** | "Write the docs for this" | "Are the docs complete?" |
++ | **Output** | Doc-diff with actual QDoc content | Audit report (MISSING/ORPHAN/BROKEN/INCOMPLETE) |
++ | **Scope** | Single type, file, or module scaffold | Entire module, all 13 check categories |
++
++ ### Where They Touch: Scaffold Mode
++
++ The closest overlap is doc-shaper scaffold mode vs doc-structure-auditor.
++ Both examine module-level structure (qdocconf, index page, groups,
++ examples). But they do different things with what they find:
++
++ | Check | doc-shaper (scaffold) | doc-structure-auditor |
++ |-------|----------------------|----------------------|
++ | Missing qdocconf | **Generates** one from scratch | **Reports** it as MISSING |
++ | Missing index page | **Generates** the page with sections | **Reports** which sections are absent |
++ | Missing examples group | **Generates** the `\group` page | **Reports** undocumented examples |
++ | Broken cross-refs | Not checked | **Traces** every `\l` link across modules |
++ | Orphan pages | Not checked | **Maps** full navigation tree, flags orphans |
++ | Image/snippet integrity | Not checked | **Verifies** every `\image` and `\snippet` path |
++ | Attribution pages | Not checked | **Cross-checks** against `qt_attribution.json` |
++
++ ### When to Use Which
++
++ | Scenario | Agent |
++ |----------|-------|
++ | New module, docs don't exist yet | **doc-shaper** (scaffold) -> generates the structure |
++ | New module exists, want to check completeness | **doc-structure-auditor** -> finds gaps |
++ | Undocumented class needs docs | **doc-shaper** (stub/full) |
++ | Pre-release "are we ready?" check | **doc-structure-auditor** |
++ | Major restructuring — need new layout | **doc-shaper** (scaffold) |
++ | Major restructuring — verify nothing broke | **doc-structure-auditor** |
++
++ ### Natural Pipeline
++
++ They're sequential, not redundant:
++
++ ```
++ doc-shaper (scaffold) -> creates module structure
++ doc-shaper (stub/full) -> creates API docs
++ doc-structure-auditor -> verifies everything is wired up
++ ```
++
++ The auditor has 13 check categories (index, navigation, examples, CMake,
++ C++ API, QML API, cross-refs, attributions, images, snippets, includes,
++ example groups, tech preview status) — far broader than what the shaper validates. The shaper's
++ self-verification is limited to "is my generated output syntactically
++ correct," not "does this module's documentation form a complete, navigable
++ whole."
++
++ ### Key Distinction
++
++ **doc-shaper** = "Here's nothing, make something."
++ **doc-structure-auditor** = "Here's something, tell me what's wrong."