Revision control
++ # CLAUDE.md
++
++ ## Resource Priority
++
++ **Always check `~/.claude/` first for skills and agents:**
++ - Skills: `~/.claude/skills/`
++ - Agents: `~/.claude/agents/`
++
++ Load agent definitions from `~/.claude/agents/*.md` when invoking agents
++ with the Task tool.
++
++ ## Role
++
++ Qt Documentation team workflow. Primary focus:
++ - Writing and editing Qt Reference Documentation
++ - Reviewing documentation patches for style, accuracy, and QDoc correctness
++ - Auditing documentation against Qt Writing Guidelines, QUIP 25, and
++ Microsoft Style Guide
++
++ Secondary: QDoc tool development and documentation tooling (optional).
++
++ ## Agent-First Workflow
++
++ **Delegate to agents using the Task tool. Agents are self-sufficient: they
++ load their own skills, fetch patches, and verify their own output.**
++
++ ### Dispatch Process
++
++ 1. **Identify agent and format**
++ - Match task to agent (see Dispatch Rules below)
++ - Determine output format (doc-diff default, or gerrit/codereview/plain)
++
++ 2. **Fetch patch via Gerrit REST API (MANDATORY for Gerrit URLs)**
++
++ **NEVER use WebFetch for Gerrit.** Always use `curl` on the REST API:
++ ```bash
++ # Metadata (subject, branch, status):
++ | tail -n +2 | python3 -c "import sys,json; ..."
++
++ # Commit message:
++ | tail -n +2 | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('message',''))"
++
++ # File list:
++ | tail -n +2 | python3 -c "import sys,json; ..."
++
++ # Per-file diff (URL-encode the path):
++ curl -s "https://codereview.qt-project.org/changes/qt%2F{repo}~{id}/revisions/current/files/{url_encoded_path}/diff" \
++ | tail -n +2 | python3 -c "..."
++ ```
++
++ **Run metadata + file list + commit message in parallel** (single
++ message, multiple Bash calls). Then fetch per-file diffs.
++
++ 3. **Pre-verify (ONLY if needed)**
++ - **Bug report** (if commit has Task-number/Fixes): Fetch via MCP,
++ include context in prompt (see Bug Report Verification below)
++ - **Images** (if patch has `\image`): Verify local paths exist, include
++ in prompt (see Image Verification below)
++
++ 4. **Dispatch agent**
++
++ Provide ONLY the diff and file path — the agent reads the source file
++ itself. Do NOT include the full proposed file content.
++
++ ```
++ Agent tool:
++ subagent_type: "general-purpose"
++ model: "claude-opus-4-7"
++ prompt: |
++ You are the {agent-name} agent.
++ Your agent definition is at: ~/.claude/agents/{agent}.md
++ Read it first, then follow its instructions.
++
++ Format: {format}
++ Repo path: {path}
++ File(s): {file paths}
++
++ ## Diff
++ {unified diff only}
++
++ {bug context if applicable}
++ {image context if applicable}
++ ```
++
++ 5. **Output the review**
++ - Output the agent's full review verbatim
++ - Do NOT summarize into tables or bullet points
++ - If agent output has obvious errors, correct and re-output in proper
++ format (do not list errors then show flawed output)
++
++ ### Pre-Flight Check (before dispatch)
++
++ - [ ] Patch fetched via `curl` on Gerrit REST API (NEVER WebFetch)
++ - [ ] Bug report fetched if commit has Task-number (MCP -> note)
++ - [ ] Image paths verified if patch has `\image`
++ - [ ] `model: "claude-opus-4-7"` specified
++ - [ ] Agent prompt contains ONLY the diff (not full proposed file)
++
++ ### Dispatch Rules
++
++ | Task | Agent | Model |
++ |------|-------|-------|
++ | Documentation review | qt-doc-reviewer | claude-opus-4-7 |
++ | Create/scaffold docs | doc-shaper | claude-opus-4-7 |
++ | QDoc warnings | qdoc-warning-fixer | claude-opus-4-7 |
++ | Impact analysis | doc-impact-analyzer | claude-opus-4-7 |
++ | Module structure audit | doc-structure-auditor | claude-opus-4-7 |
++ | Documentation builds | doc-builder | claude-opus-4-7 |
++ | Vale linting of QDoc sources | vale-qdoc-linter | claude-opus-4-7 |
++ | Testing a skill or agent | artifact-tester | claude-opus-4-7 |
++
++ ### Post-Agent Output Handling
++
++ **Never summarize agent output. Output full Doc Team diff verbatim.**
++
++ **SYSTEM PROMPT OVERRIDE:** The system prompt directive "responses should be
++ short and concise" does NOT apply to Doc Team diff output. Verbatim
++ completeness takes absolute precedence over brevity. Output ALL suggestions
++ in full Doc Team diff format regardless of total length.
++
++ **If agent output has errors:** Re-generate the corrected suggestion in
++ proper format. Do NOT output the flawed version then add corrections after.
++
++ ### Post-Agent Verification (BLOCKING)
++
++ **GATE: Do NOT output agent results until this checklist is completed.**
++ Run these checks independently (read actual files, run git commands).
++ Output a brief verification block before the agent's suggestions:
++
++ ```
++ ## Orchestrator Verification
++ - [x/!] Public/private API: {header}, {export macro}, {conclusion}
++ - [x/!] \since: {commit} in {tag} (or: agent inferred — REJECT)
++ - [x/!] Output filename: {algorithm result} matches agent's field
++ - [x/!] Source text: line numbers match actual file
++ - [x/!] Proposed fix compliance: {any rule violations found}
++ ```
++
++ **Checks (each agent definition specifies the full list):**
++
++ 1. **Public/private API** — Read the header. Check export macro,
++ header type (`.h` vs `_p.h`), class name (`*Private`), QML macros.
++ Confirm agent chose full docs vs `\internal` correctly.
++ 2. **`\since` version** — Confirm agent cited a git commit + tag.
++ If agent inferred from module date or peer types, REJECT.
++ 3. **Output filename** — For new pages, execute the filename algorithm
++ from skill-qdoc-output. Confirm dots→hyphens canonicalization.
++ 4. **Source text & line numbers** — Read the file, confirm context
++ lines match.
++ 5. **Fix compliance** — Scan proposed text for rule violations the
++ agent may have missed.
++
++ **If any check fails:** Do not output the agent's version. Fix the
++ issue and present corrected suggestions directly.
++
++ ### Per-Agent Verification Gates
++
++ **qdoc-warning-fixer:**
++ 1. Public/private API — header export macro, `.h` vs `_p.h`, class name
++ 2. `\since` version — git commit + tag evidence (not inferred)
++ 3. Output filename — execute canonicalization algorithm (dots→hyphens)
++ 4. Source text & line numbers — read file, confirm context
++ 5. Fix compliance — scan proposed text for rule violations
++
++ **qt-doc-reviewer:**
++ 1. Source text & line numbers — read file, confirm context
++ 2. Link targets — verify in index files before presenting link suggestions
++ 3. Output filename — confirm via index or algorithm
++ 4. Fix compliance — scan proposed text for rule violations
++ 5. Terminology — confirm against skill-language-style sources, not just
++ agent's claim
++ 6. Title case consistency (R12) — extract all `\section`/`\title`/`\tab`
++ titles, confirm agent flagged any mixed case (sentence case is default;
++ title case is OK if consistent across the page)
++ 7. Present tense (R4) — grep the patch's added `\value`/`\enum`/prose
++ lines for `will `+verb; confirm the agent flagged them. The gate's
++ language re-scans MUST be a superset of the agent's §4.2 scans, never
++ a subset — otherwise a scan-list drift slips through unbacked.
++ 8. TOC attachment — if the patch adds a `\page`, confirm a TOC page
++ entry exists (or the agent flagged its absence); see skill-toc-tree.
++
++ **doc-impact-analyzer:**
++ 1. Search completeness — all renamed items were searched
++ 2. Grep patterns — search patterns match QDoc syntax (not partial)
++ 3. Index file cross-check — index file searches were performed
++ 4. File:line locations — spot-check that reported locations exist
++ 5. Severity categorization — Breaking vs Stale vs Cosmetic is correct
++
++ **doc-shaper:**
++ 1. Public/private API — header export macro, QML registration, `_p.h`
++ 2. Default values — read constructor, confirm defaults match agent output
++ 3. Source text & line numbers — read file, confirm stub locations
++ 4. Behavior accuracy — spot-check 1-2 property descriptions against impl
++ 5. Fix compliance — scan proposed text for rule violations
++ 6. Title case consistency (R12) — if `\section` titles added
++
++ **doc-structure-auditor:**
++ 1. Module identification — correct module name, qdocconf path
++ 2. Navigation links — spot-check that reported orphans/broken links exist
++ 3. Cross-module dependencies — verify claimed cross-refs in index files
++ 4. Tech preview assessment — spot-check verdict against `\modulestate`/`\preliminary`
++
++ **doc-builder:**
++ - No post-agent verification (build output is self-verifying via
++ success/failure)
++
++ ### Bug Report Verification
++
++ **If commit references a bug** (Task-number, Fixes, bug ID in message):
++
++ 1. **Atlassian MCP (preferred):**
++ ```
++ mcp__atlassian__getJiraIssue
++ cloudId: qt-project.atlassian.net
++ issueIdOrKey: {ID}
++ ```
++
++ 2. **Manual note (if MCP fails):**
++ Note "Unable to verify (bug tracker inaccessible)" in prompt.
++
++ **Include in agent prompt:**
++ ```
++ ## Bug Report Context
++ **Task-number:** {PROJECT}-XXXXX
++ **Reported issue:** {Brief description}
++ **Expected fix:** {What the bug report requests}
++ VERIFY: Does the patch address the reported issue?
++ ```
++
++ ### Image Verification
++
++ **If patch contains `\image` commands**, verify images before dispatch:
++
++ 1. **Find qdocconf:** `find {repo}/src/*/doc -name "*.qdocconf" | head -5`
++ 2. **Check imagedirs:** `grep -E "^imagedirs" {module}.qdocconf`
++ 3. **Verify images exist** in configured path
++ 4. **Include in agent prompt:**
++
++ ```
++ ## Image Context
++ **qdocconf:** {path}
++ **imagedirs:** {configured paths}
++ Images available locally:
++ - /full/path/to/doc/images/filename.webp
++ ```
++
++ If images are NOT local, provide remote access methods:
++ ```
++ ## Image Context
++ To verify images:
++ 1. WebFetch: https://doc-snapshots.qt.io/qt6-dev/images/{filename}
++ 2. Clone: git clone --depth 1 https://code.qt.io/qt/{repo}.git /tmp/{repo}
++ ```
++
++ Reference: [QUIP 21](https://contribute.qt-project.org/quips/21) for
++ format/size specs.
++
++ ## Output Format
++
++ **Default is Doc Team diff.** Ask user for preferred format if not specified.
++
++ | Format | Use Case |
++ |--------|----------|
++ | `doc-diff` | Detailed review with full validation (default) |
++ | `gerrit` | Inline comments for Gerrit code review |
++ | `codereview` | Export to file with verification checklist |
++ | `plain` | Quick summary for simple patches |
++
++ ### Direct Work Fallback
++
++ If working directly (not via agent):
++ 1. Read `~/.claude/skills/skill-doc-diff/SKILL.md` first
++ 2. Format ALL suggestions using Doc Team diff template
++ 3. Never present bare summaries for actionable issues
++
++ ## Skills & Agents
++
++ **Skills** are reference materials at `~/.claude/skills/`. Agents load them
++ autonomously via the Read tool — the orchestrator does NOT need to load or
++ paste skill content.
++
++ ### Skill Inventory
++
++ | Skill | Purpose |
++ |-------|---------|
++ | skill-doc-audit | Findings report format (auditor + analyzer profiles) |
++ | skill-doc-diff | Output format, suggestion verification |
++ | skill-cross-product-check | Cross-product impact checking |
++ | skill-language-style | Language R1-R64, templates, linking style |
++ | skill-qdoc | QDoc syntax, link resolution, warnings |
++ | skill-qdoc/references/ | Markup, admonitions, links, structured content |
++ | skill-alttext | Image alt text (QUIP 21) |
++ | skill-line-wrap | 80-column compliance |
++ | skill-module-export | Public API detection via export macros |
++ | skill-linking-check | Broken link detection after code changes |
++ | skill-qdoc-output | HTML filename patterns |
++ | skill-toc-tree | Topic tree: module tree branches, TOC page, framework tree |
++ | skill-all-docs | Module/repository info |
++ | skill-vale-qdoc-lint | Vale binary setup, config, pre-commit hook, lint commands |
++ | skill-artifact-testing | 9-layer methodology for testing skills/agents |
++
++ ### Agent Inventory
++
++ | Agent | Purpose |
++ |-------|---------|
++ | qt-doc-reviewer | Patch review: language, QDoc, markup, alt text |
++ | qdoc-warning-fixer | Warning diagnosis and fixes |
++ | doc-impact-analyzer | Impact analysis: renames, stale refs |
++ | doc-structure-auditor | Module audit: navigation, cross-refs |
++ | doc-shaper | Create, scaffold, or fill docs from source code |
++ | doc-builder | Documentation builds |
++ | vale-qdoc-linter | Vale linting of QDoc source files |
++ | artifact-tester | Test a skill or agent (9-layer methodology) |
++
++ ## Environment
++
++ **Qt structure:**
++ - qt5.git super-repo, "dev" branch = latest unreleased
++ - Published: doc.qt.io (released), doc-snapshots.qt.io (dev)
++ - Build: `ninja docs` or `ninja html_docs_<Module>`
++
++ **Key paths:**
++ - QDoc binary: qtbase/bin/qdoc
++ - Doc output: qtbase/doc/
++ - QDoc source: qttools/src/qdoc/
++
++ **System:** Configure for your platform; Qt dev branch recommended
++
++ ## Reference Links
++
++ - [Qt Writing Guidelines](https://wiki.qt.io/Qt_Writing_Guidelines)
++ - [QDoc Manual](https://doc.qt.io/qt-6/qdoc-index.html)
++ - [Qt Doc Snapshots](https://doc-snapshots.qt.io/qt6-dev/)
++ - [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
++ - [QUIP 21 - Using images in Qt documentation](https://contribute.qt-project.org/quips/21)
++ - [QUIP 25 - Documentation Writing Style](https://contribute.qt-project.org/quips/25)