Add CQA-related Claude skills

.claude/skills/cqa-reviewer/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: cqa-reviewer
+description: Reviews changes made by other CQA skills, compares before/after Vale results, and flags over-corrections or missed issues.
+---
+
+# CQA reviewer
+
+I am the final quality gate in the Content Quality Assessment (CQA) workflow. I can operate in two modes:
+
+- **Audit Mode** (standalone): Reads `master.adoc`, maps all included files, and reviews every existing abstract across all modules for quality — without requiring any prior skill run or git changes.
+- **Review Mode** (post-skill): Reviews changes made by other skills (short-description-expert, doc-structure-checker), compares before/after Vale results, and flags over-corrections or missed issues.
+
+---
+
+## Audit mode
+
+Use this mode to proactively review abstract quality across an entire guide, including files where `[role="_abstract"]` is already present and Vale passes without errors.
+
+### AM-1. Setup
+
+The user provides a path to `master.adoc`. Recursively map all `include::` files:
+
+1. Open `master.adoc` and follow every `include::` directive.
+2. Recursively open referenced files to find nested includes.
+3. Resolve relative paths from each file's directory.
+4. Build the complete file list.
+
+**Exclude from review**:
+- Assembly files: `assembly_*.adoc` — abstracts live in their first included concept module, not in the assembly itself
+- Attribute files: `attributes*.adoc`, `_title-attributes.adoc`
+- Snippet files: `snip_*.adoc`
+- Non-content includes: `header.adoc`, `ribbons.adoc`
+
+Only review module files: `con_*.adoc`, `proc_*.adoc`, `ref_*.adoc`.
+
+### AM-2. Per-file review
+
+For each module file:
+
+1. Read the file.
+2. Locate the `[role="_abstract"]` paragraph (the paragraph immediately following that tag).
+3. Classify the result:
+
+**MISSING** — no `[role="_abstract"]` tag exists at all.
+
+**PRESENT — evaluate against all criteria:**
+- Follows What+Why formula ("You can [action] to [benefit]", "To [goal], configure [feature]", etc.)
+- 1-2 sentences, 50–300 characters, ≤50 words
+- First paragraph after the title, not buried further down
+- No self-referential language ("This section explains...", "The following...", "This document...")
+- Does not end with a colon
+- Uses AsciiDoc attributes (`{Project}`, `{SmartProxy}`, etc.) rather than hard-coded product names
+- Does not simply restate the title word-for-word
+- Active voice, present tense
+
+### AM-3. Output format
+
+```
+=== CQA Abstract Audit Report ===
+
+Guide: [path to master.adoc]
+Modules reviewed: N
+Assemblies skipped: N (by design)
+
+MISSING abstract [role="_abstract"] tag:
+- path/to/file.adoc — title: "..."
+
+APPROVED (abstract present and meets all criteria):
+- path/to/file.adoc
+
+CONCERNS (present but has issues):
+- path/to/file.adoc
+  - Issue: [describe the specific problem]
+  - Current text: "[quote the abstract]"
+  - Suggestion: [rewrite or targeted fix]
+
+SUMMARY:
+- Missing: N files
+- Approved: N files
+- Concerns: N files
+
+Recommendation: [PASS / PASS WITH NOTES / NEEDS FIXES]
+```
+
+---
+
+## Review Mode
+
+Use this mode after `short-description-expert` or `doc-structure-checker` has made changes, to verify the changes are correct and haven't introduced new problems.
+
+### RM-1. Prerequisites
+
+Before running, ensure:
+- `adoc-file-list.txt` exists (file manifest from the prior skill run)
+- `vale-output.txt` exists (pre-fix Vale results)
+- Other skills have completed their work
+- Changes are visible via `git diff`
+- `vale-output-post.txt` does not exist — remove it if it does
+
+Run Vale again to create post-fix results:
+```
+xargs vale --output line < adoc-file-list.txt > vale-output-post.txt
+```
+
+### RM-2. Review process
+
+#### RM-2.1 Compare Vale results
+1. Parse `vale-output.txt` (before) and `vale-output-post.txt` (after).
+2. Identify:
+   - **Resolved issues**: Errors in "before" that are gone in "after"
+   - **New issues**: Errors in "after" that weren't in "before"
+   - **Unchanged issues**: Errors present in both
+
+**Flag if:** New issues were introduced by the fixes.
+
+#### RM-2.2 Review changed files
+For each file with changes (via `git diff --name-only`):
+
+1. Read the diff to understand what changed.
+2. **Verify short descriptions:**
+   - Follow What+Why formula
+   - Are 1-2 sentences, between 50-300 characters, maximum ~50 words
+   - Don't repeat the title verbatim
+   - No self-referential language ("This document describes...", "This section explains...", "The following examples...", "The examples below...")
+   - Use AsciiDoc attributes, not hard-coded product names
+   - Do not end with a colon
+3. **Verify structural changes:**
+   - Assembly includes are properly ordered
+   - No content was accidentally deleted
+   - Prerequisites are correctly formatted
+4. **Check for over-corrections:**
+   - Content rewritten that was already acceptable
+   - Style changes beyond the scope of the fix
+   - Added content that wasn't requested
+
+#### RM-2.3 Consistency check
+Across all changed files:
+- Terminology is consistent (same product names, feature names)
+- Short description style is consistent
+- No conflicting information introduced
+
+### RM-3. What NOT to do
+
+- Do NOT make changes directly. Flag issues only.
+- Do NOT request endless revision cycles. One review pass is sufficient.
+- Do NOT flag minor stylistic preferences. Focus on errors and quality issues.
+- Do NOT re-review unchanged files.
+
+### RM-4. Output format
+
+```
+=== CQA Review Report ===
+
+Vale Comparison:
+- Issues resolved: X
+- New issues introduced: Y
+- Unchanged issues: Z
+
+Files Reviewed: N
+
+APPROVED (no issues):
+- path/to/file.adoc
+
+CONCERNS (minor, acceptable):
+- path/to/file.adoc: Short description is 302 characters (limit 300) - minor, can accept
+
+ISSUES (needs attention):
+- path/to/file.adoc:
+  - Problem: Short description uses "This section explains..."
+  - Suggestion: Rewrite to start with action or benefit
+
+- path/to/assembly.adoc:
+  - Problem: New Vale error introduced (line 45: RedHat.Spelling)
+  - Suggestion: Check spelling of product name
+
+SUMMARY:
+- Total files: N
+- Approved: X
+- Minor concerns: Y
+- Issues to address: Z
+
+Recommendation: [PASS / PASS WITH NOTES / NEEDS FIXES]
+```
+
+### RM-5. Recommendation criteria
+
+- **PASS**: No issues, all changes look good
+- **PASS WITH NOTES**: Minor concerns only, acceptable to proceed
+- **NEEDS FIXES**: Issues found that should be addressed before committing
+
+### RM-6. After review
+
+If issues are found:
+1. Report them clearly with file paths and line numbers
+2. Suggest specific fixes
+3. User decides whether to run fix skills again or manually adjust
+
+Do NOT automatically trigger another round of fixes. Human decides next steps.

.claude/skills/doc-structure-checker/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: doc-structure-checker
+description: Validates and fixes AsciiDoc structural issues including assembly format, module templates, prerequisites, and nesting depth.
+---
+
+# Document structure checker
+
+I validate and fix structural issues in modular AsciiDoc documentation.
+
+## References
+
+Before starting, read these files in `references/`:
+- `modular_documentation_templates_checklist.md` - **Primary reference** for validation rules
+- `TEMPLATE_ASSEMBLY.adoc` - Canonical assembly structure
+- `TEMPLATE_CONCEPT.adoc` - Canonical concept module structure
+- `TEMPLATE_PROCEDURE.adoc` - Canonical procedure module structure
+- `TEMPLATE_REFERENCE.adoc` - Canonical reference module structure
+
+## 1. File preparation
+
+The user provides a path to `master.adoc`.
+
+**If `adoc-file-list.txt` exists:** Use it. Skip to Section 3.
+
+**If missing:** Create the manifest:
+1. Open `master.adoc` and identify all `include::` files recursively
+2. Create `adoc-file-list.txt` with discovered file paths, one per line
+
+## 2. Files to exclude
+
+Skip: `_attributes*.adoc`, `_title-attributes.adoc`, `snip_*.adoc`, files in `common/` directory.
+
+## 3. Execution workflow
+
+1. **Read** the reference files in `references/` to understand the rules
+2. **Read** `adoc-file-list.txt` to get the file manifest
+3. **Categorize** each file as assembly or module by checking for `:_mod-docs-content-type:`
+4. **Validate** each file against the checklist rules
+5. **Fix** issues with clear solutions (see below)
+6. **Flag** issues needing human decision (see below)
+7. **Summarize** changes made and issues flagged
+
+## 4. What to fix vs flag
+
+**Fix automatically:**
+- Prerequisites using ordered lists → convert to unordered
+- Multi-step procedures using bullets → convert to ordered list
+- Single-step procedures using numbered list → convert to bullet
+- Missing blank lines between include statements
+- Supplementary content under steps missing `+` connector
+
+**Flag for human review:**
+- Missing `[role="_abstract"]` → instruct user to run `short-description-expert`
+- Missing `:_mod-docs-content-type:` declaration
+- Nesting depth exceeding 3 levels
+- Concept/reference modules containing imperative statements
+- Procedure modules with multiple `.Procedure` blocks
+- Block titles not in the allowed list
+
+## 6. Output format
+
+```
+=== Structure Check Summary ===
+
+Files checked: X
+Issues fixed: Y
+Issues flagged for review: Z
+
+FIXED:
+- path/to/file.adoc: [description of fix]
+
+FLAGGED (needs human review):
+- path/to/file.adoc: [issue description]
+
+NO ISSUES:
+- path/to/file.adoc
+```

.claude/skills/doc-structure-checker/references/TEMPLATE_ASSEMBLY.adoc

@@ -0,0 +1,79 @@
+////
+Retains the context of the parent assembly if this assembly is nested within another assembly.
+For more information about nesting assemblies, see: https://redhat-documentation.github.io/modular-docs/#nesting-assemblies
+See also the complementary step on the last line of this file.
+////
+
+ifdef::context[:parent-context: {context}]
+
+
+////
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
+////
+:_mod-docs-content-type: ASSEMBLY
+
+////
+ Base the file name and the ID on the assembly title. For example:
+* file name: assembly-my-user-story.adoc
+* ID: [id="assembly-my-user-story_{context}"]
+* Title: = My user story
+
+ID is a unique identifier that can be used to reference this assembly. Avoid changing it after the module has been published to ensure existing links are not broken. Include {context} in the ID so the assembly can be reused.
+
+Be sure to include a line break between the title and the :context: variable and the :context: variable and the assembly introduction.
+If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
+////
+[id="assembly-my-user-story_{context}"]
+= My user story
+////
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+////
+
+:context: assembly-keyword
+
+[role="_abstract"]
+This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on.
+
+== Prerequisites
+
+* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+* You can also link to other modules or assemblies the user must follow before starting this assembly.
+* Delete the section title and bullets if the assembly has no prerequisites.
+* X is installed. For information about installing X, see <link>.
+* You can log in to X with administrator privileges.
+
+////
+The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
+
+[leveloffset=+1] ensures that when a module title is a level 1 heading (= Title), the heading will be interpreted as a level-2 heading (== Title) in the assembly. Use [leveloffset=+2] and [leveloffset=+3] to nest modules in an assembly.
+
+ Add a blank line after each 'include::' statement.
+////
+
+include::TEMPLATE_CONCEPT_concept-explanation.adoc[leveloffset=+1]
+
+include::TEMPLATE_PROCEDURE_doing-one-procedure.adoc[leveloffset=+2]
+
+include::TEMPLATE_REFERENCE_reference-material.adoc[leveloffset=+2]
+
+== Next steps
+
+* This section is optional.
+* Provide information about the next steps the user might want to take.
+* This section can include text and links.
+
+// If the last module included in your assembly contains an Additional resources section as well, check the appearance of the rendered assembly. If the two Additional resources sections might be confusing for a reader, consider consolidating their content and removing one of them.
+
+[role="_additional-resources"]
+== Additional resources
+////
+Optional. Delete if not used.
+Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text.
+////
+* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
+* xref:some-module_{context}[]
+
+// Restore the context to what it was before this assembly.
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]