From cqa-tools
Assesses CQA parameters O6-O10 for Red Hat docs onboarding to docs.redhat.com: support disclaimers, SME/QE verification, AsciiDoc format, Pantheon publishing, and official site publication.
npx claudepluginhub redhat-documentation/redhat-docs-agent-tools --plugin cqa-toolsThis skill is limited to using the following tools:
| # | Parameter | Level |
Assesses CQA legal/branding parameters in Red Hat docs repos: official product names via attributes, Tech Preview disclaimers, conscious language, non-RH links, copyright using Python scripts.
Reviews Red Hat documentation for SSG legal and support compliance including no cost/pricing references, no future release promises, and proper Developer Preview and Technology Preview admonitions.
Validates documentation quality for research software using Vale prose linting, HTMLProofer link checking, markdownlint Markdown validation, code example testing, container instructions, and CI integration.
Share bugs, ideas, or general feedback.
| # | Parameter | Level |
|---|---|---|
| O6 | Content supported or clear disclaimers about support level | Required |
| O7 | Procedures tested and verified by SME or QE | Required |
| O8 | Source files in RH prescribed format (AsciiDoc) | Required |
| O9 | Content published through Pantheon | Required |
| O10 | Content published to official Red Hat site | Required |
Some repos use modules/ instead of topics/ for content files. All topics/ references in this skill apply equally to modules/. The automation scripts accept --scan-dirs to override the default scan directories.
cqa-tools:cqa-legal-branding. Use the cqa-legal-branding TP/DP disclaimer results as evidence for O6 compliance. O6 adds the community-supported component and unsupported configuration checks.cqa-tools:cqa-procedures — a high percentage of procedures with .Verification sections is supporting evidence of testability.Ask the user for the path to their Red Hat modular documentation repository. Store as DOCS_REPO.
All content must be clearly identified as supported, Technology Preview, or Developer Preview. Community-supported components and unsupported configurations must have explicit disclaimers.
Technology Preview features: Verify all TP features have the standard [IMPORTANT] disclaimer via snip_technology-preview.adoc. Cross-reference with the P19/O5 check in cqa-tools:cqa-legal-branding.
Developer Preview features: Verify all DP features have the standard DP disclaimer. DP features receive zero Red Hat support.
Community-supported components: Identify any components that are community-supported rather than Red Hat-supported (e.g., upstream Eclipse Che components, community plugins). These must have disclaimers.
Unsupported configurations: Check for documented configurations that are explicitly NOT supported (e.g., non-OpenShift Kubernetes distributions, specific cloud provider limitations). These must have [WARNING] or [IMPORTANT] blocks stating the support boundary.
Support scope consistency: Verify that support level claims are consistent across the guide. A feature cannot be "fully supported" in one topic and "Technology Preview" in another.
# Find all support-related disclaimers
grep -rn -i 'technology preview\|tech preview\|developer preview\|not supported\|unsupported\|community' topics/ modules/ assemblies/ --include='*.adoc'
# Find TP/DP snippet includes
grep -rn 'snip_technology-preview\|snip_developer-preview' topics/ modules/ assemblies/ --include='*.adoc'
| Score | Criteria |
|---|---|
| 4 | All TP/DP features have proper disclaimers. Community components identified. Unsupported configurations disclaimed. Support levels consistent across guides. |
| 3 | Most disclaimers in place. 1-2 features missing TP/DP disclaimer. Minor consistency issues. |
| 2 | Multiple features lack required disclaimers. Community components not identified. Inconsistent support claims. |
| 1 | No support-level identification. Missing disclaimers on TP/DP features. |
All procedures must be tested and verified by a Subject Matter Expert (SME) or Quality Engineering (QE) team member before publication. This ensures technical accuracy and that documented steps produce the expected results.
This parameter requires human confirmation and cannot be fully assessed through static analysis. Evaluate the following evidence:
Merge request review process: Check the repository's merge request (MR) workflow:
.gitlab-ci.yml for automated validation (Vale, reference checks)SME contribution history: Check git log for commits from engineering team members:
git log --format="%an" --since="1 year ago" | sort | uniq -c | sort -rn
CI/CD pipeline validation: Verify the pipeline runs automated checks that catch technical issues:
validate-refs.py)SME merge requests: Check for recent MRs from SMEs that update technical content:
git log --oneline --since="6 months ago" --grep="SME\|fix\|update\|correct"
Verification sections: Procedures with .Verification sections provide a built-in testing path. A high percentage of procedures with verification sections is evidence of testability.
| Evidence | Strength |
|---|---|
| SME-authored MRs with technical content updates | Strong — direct SME involvement |
| QE team sign-off on MRs (GitLab approvals) | Strong — formal verification |
| CI pipeline with automated validation | Medium — catches structural issues but not technical accuracy |
.Verification sections in procedures | Medium — enables testing but does not confirm it was done |
| Git history showing engineering contributors | Weak — presence does not guarantee testing |
| Score | Criteria |
|---|---|
| 4 | MR workflow requires SME/QE approval. Recent SME MRs demonstrate active involvement. CI pipeline validates content. Verification sections in critical procedures. |
| 3 | SME involvement confirmed for most content. CI pipeline in place. Some procedures lack formal verification. |
| 2 | Limited SME involvement. No formal review process. CI pipeline missing or incomplete. |
| 1 | No evidence of SME/QE testing. No review process. No CI validation. |
All source content files must be in AsciiDoc (.adoc) format following the Red Hat modular documentation framework. The repository structure must conform to Red Hat documentation standards.
File format verification:
# Count all content files by extension
find "$DOCS_REPO/topics" "$DOCS_REPO/modules" "$DOCS_REPO/assemblies" "$DOCS_REPO/snippets" -type f 2>/dev/null | sed 's/.*\.//' | sort | uniq -c | sort -rn
All content files must be .adoc. No .md (Markdown), .xml (DocBook), .dita, or .html source files.
Encoding verification:
# Check for non-UTF-8 files in all content directories
file "$DOCS_REPO/topics/"**/*.adoc "$DOCS_REPO/modules/"**/*.adoc "$DOCS_REPO/assemblies/"**/*.adoc "$DOCS_REPO/snippets/"**/*.adoc 2>/dev/null | grep -v "UTF-8\|ASCII"
All files must be UTF-8 encoded.
Line endings:
# Check for Windows line endings (CRLF)
grep -rPl '\r\n' "$DOCS_REPO/topics/" "$DOCS_REPO/modules/" "$DOCS_REPO/assemblies/" "$DOCS_REPO/snippets/" --include='*.adoc' 2>/dev/null | head -5
All files must use LF (Unix) line endings, not CRLF (Windows).
Directory structure: Verify the repo follows Red Hat modular docs layout:
titles/ — publishable guide entry points with master.adocassemblies/ — assembly files (collections of topics)topics/ (or modules/) — individual content modulessnippets/ — reusable inline fragmentscommon/ — shared attributes and metadataimages/ — image assets.editorconfig presence: Check for .editorconfig enforcing UTF-8, LF, consistent indentation:
cat "$DOCS_REPO/.editorconfig"
| Score | Criteria |
|---|---|
| 4 | All content files are .adoc. UTF-8 encoding. LF line endings. Standard Red Hat modular docs directory structure. .editorconfig present. |
| 3 | All files are .adoc with correct encoding. Minor structure deviations (e.g., missing .editorconfig). |
| 2 | Mixed file formats. Some non-UTF-8 files. Non-standard directory structure. |
| 1 | Content not in AsciiDoc or no standard structure. |
Content must be publishable through Pantheon, Red Hat's documentation publishing platform. This requires ccutil compatibility and proper build configuration.
Pantheon directory structure: Verify the pantheon/ directory exists with symlinks to titles/:
ls -la "$DOCS_REPO/pantheon/"
Each subdirectory should symlink to a titles/*/ directory.
ccutil build configuration: Verify tools/ccutil.sh exists and is functional:
cat "$DOCS_REPO/tools/ccutil.sh"
ccutil compile test: Run a test build (requires podman or the ccutil container):
cd "$DOCS_REPO"
bash tools/ccutil.sh
The build must complete without errors. Warnings should be reviewed.
docinfo.xml: Verify docinfo.xml exists in each titles/*/ directory:
ls "$DOCS_REPO/titles/"*/docinfo.xml
master.adoc entry points: Verify each guide has a master.adoc entry point:
ls "$DOCS_REPO/titles/"*/master.adoc
CI pipeline ccutil job: Verify the CI pipeline includes a ccutil build job:
grep -A 10 'ccutil' "$DOCS_REPO/.gitlab-ci.yml"
ccutil should produce these formats:
html-single — single-page HTML (primary format for Pantheon)html — multi-page HTMLpdf — PDF outputepub — EPUB output| Issue | Cause | Fix |
|---|---|---|
| Duplicate ID errors | Same [id="..."] in files included by multiple assemblies | Remove duplicate includes or use unique IDs |
| Unresolved attributes | Attribute not defined in common/attributes.adoc | Add attribute definition |
| Missing include files | include:: path does not resolve via symlinks | Fix symlink or include path |
| Bare language source blocks | [bash,...] instead of [source,bash] | Add source, prefix |
Nested ==== delimiters | Example block inside admonition block | Restructure to avoid nesting |
| Score | Criteria |
|---|---|
| 4 | pantheon/ directory configured. ccutil build completes with 0 errors. CI pipeline includes ccutil job. All output formats generated. |
| 3 | ccutil builds with minor warnings. CI pipeline present. 1-2 output format issues. |
| 2 | ccutil build fails. Missing pantheon/ configuration. No CI pipeline. |
| 1 | No Pantheon publishing infrastructure or not assessed. |
Content must be published to the official Red Hat documentation site (docs.redhat.com) and accessible to customers.
Stage branch existence: Verify stage branches exist for the current and previous releases:
git -C "$DOCS_REPO" branch -r | grep 'stage'
Stage branch pipeline: Verify the stage branch triggers the Pantheon publishing pipeline. The pipeline should have:
single_source — assembles content from Antora sourcesccutil — validates and compiles the assembled contentgit_push — pushes generated Pantheon files back to the branchPublished URL verification: If you have access, verify the content is accessible at the published URL. The URL pattern is typically:
https://docs.redhat.com/en/documentation/__<product_slug>__/__<version>__/html-single/__<guide_name>__/common/attributes.adoc.Version coverage: Verify that published documentation covers the current supported versions.
Content freshness: Check that the most recent stage branch reflects the latest content updates:
git -C "$DOCS_REPO" log --oneline -5 origin/<product>-<X.Y>-stage
| Score | Criteria |
|---|---|
| 4 | Content published to docs.redhat.com. Stage branches exist and pipeline works. Current and previous versions covered. Content is fresh. |
| 3 | Published to docs.redhat.com. Stage branches exist. Minor delays in content freshness. |
| 2 | Published but with significant gaps. Stage pipeline has issues. Not all versions covered. |
| 1 | Content not published to docs.redhat.com or publishing infrastructure not in place. |
After assessing all parameters, compile the evidence:
# Summary checks
ls "$DOCS_REPO/pantheon/"
ls "$DOCS_REPO/titles/"*/master.adoc
ls "$DOCS_REPO/titles/"*/docinfo.xml
ls "$DOCS_REPO/.editorconfig"
git -C "$DOCS_REPO" branch -r | grep 'stage'