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 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 exactly as `short-description-expert` does:
+
+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** (same rules as `short-description-expert`):
+- 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,83 @@
+---
+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`, `snippet_*.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
+
+## 5. RHEL 10 Conventions
+
+- NO module type prefixes in filenames (no `con_`, `proc_`, `ref_`)
+- NO context prefixes in IDs
+- Determine module type by `:_mod-docs-content-type:`, not filename
+
+## 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/Modular documentation templates checklist.md

@@ -0,0 +1,51 @@
+**Modular documentation templates checklist**
+
+**All modules and assemblies:**
+
+* Has :\_mod-docs-content-type: \<TYPE\>, where  \<TYPE\> is ASSEMBLY, CONCEPT, REFERENCE, or PROCEDURE.  
+* Has a topic ID in the following format:  
+  \[id="\<file-name\>\_{context}"\]  
+  	For OCP: \[\_{context}"\] does not belong in Assemblies.  
+
+* Has one and only one level 0 (=) title (H1) title  
+* Has a short introduction  
+* Has a blank line between the level 0 (=)  title and the short introduction  
+* For any images, has alternative text descriptions enclosed in quotation marks ("")  
+* Admonitions do not include titles.
+
+**Nested assembly files:**
+
+* Contains the following conditional statement at the top of the document:  
+  ifdef::context\[:parent-context: {context}\]  
+* Contains the following conditional statement at the bottom of the document:  
+  ifdef::parent-context\[:context: {parent-context}\]  
+  ifndef::parent-context\[:\!context:\]  
+* Has the context variable declared and defined (:context: some-assembly).
+
+**All assembly files:**
+
+* Has a blank line between each include statement.  
+* Does not contain a level 2 (===) section title (H3) or lower.   
+* Does not include block titles.
+
+**Concept or reference module:**
+
+* Does not contain an instruction (imperative statement).  
+* Does not contain a level 2 (===) section title (H3) or lower..  
+* Does not contain block titles, except .Additional references or .Next steps. Note that .Next steps will not be mapped to \<related-links\>, .Additional resources will.
+
+**Procedure module:**
+
+* Includes the .Procedure block title followed by one ordered or unordered list.  
+* Includes only one .Procedure block title and list.  
+* Does not contain embellishments of .Procedure, for example .Procedure for installing X.  
+* Does not contain content following the last step of the procedure except the optional sections in the order listed:  
+  \* Prerequisites or Prerequisite  
+  \* Procedure  
+  \* Verification, Results, or Result  
+  \* Troubleshooting, Troubleshooting steps, or Troubleshooting step  
+  \* Next steps or Next step  
+  \* Additional resources  
+
+* Does not contain any other block titles. 
+