Cqa Vale Check

CQA P1: Vale DITA Check

Parameter

P1: Content passes Vale dita-tools:dita-validate-asciidoc check with no errors or warnings. Level: Required. Target: Score 4 (0 errors, 0 warnings).

Step 1: Identify the docs repo

Ask the user for the path to their Red Hat modular documentation repository. This is the directory that contains assemblies/, topics/ (or modules/), and titles/ directories.

Store this as DOCS_REPO for all subsequent steps.

Vale must be installed (v3.x+). For assembly/topic scope, the dita-tools:dita-validate-asciidoc skill checks this automatically. For repo-wide scope, verify manually:

vale --version

If not installed, stop and tell the user to install Vale v3.x+. Do not install it for them.

Step 2: Run Vale

Choose the approach based on scope.

For repo-wide scope — direct Vale invocation

Run Vale directly against all AsciiDoc files in the repo. This catches every .adoc file, including orphan files not referenced by any assembly.

IMPORTANT: CQA P1 requires checking with AsciiDocDITA rules only. The repo may have its own .vale.ini with different styles (e.g., RedHat, AsciiDoc, RHEL10). Do NOT use the repo's own Vale config for CQA P1 — those are for the repo's CI, not for CQA assessment. Always create and use a dedicated CQA config file.

Create .vale-cqa.ini in the docs repo root (overwrite if it exists):

StylesPath = .vale/styles

MinAlertLevel = warning

Packages = https://github.com/jhradilek/asciidoctor-dita-vale/releases/latest/download/AsciiDocDITA.zip

[*.adoc]
BasedOnStyles = AsciiDocDITA

Then sync and run with the CQA config explicitly:

cd "$DOCS_REPO"
vale --config=.vale-cqa.ini sync
find . -name '*.adoc' -not -type l | xargs vale --config=.vale-cqa.ini

Do NOT run vale without --config=.vale-cqa.ini — without it, Vale picks up the repo's own .vale.ini which may use different style packages and produce errors/warnings unrelated to CQA P1.

For assembly scope — dita-validate-asciidoc

Invoke the dita-tools:dita-validate-asciidoc skill, which discovers all included files and runs Vale with content-type-aware ShortDescription filtering:

Skill: dita-tools:dita-validate-asciidoc, args: "$DOCS_REPO/assemblies/admin/assembly_installing.adoc"

For single-topic scope — dita-validate-asciidoc

Skill: dita-tools:dita-validate-asciidoc, args: "$DOCS_REPO/topics/con-overview.adoc"

If the result is 0 errors, 0 warnings (or no output for dita-validate-asciidoc) — score 4 and skip to Step 6.

Step 3: Categorize warnings

Group the output by rule name. Common rules and their fixes:

| Rule | Meaning | Fix | |------|---------|-----| | ContentType | Missing :_mod-docs-content-type: | Add attribute as first line | | ShortDescription | Missing [role="_abstract"] | Add abstract paragraph after title | | ConceptLink | Link/xref in body of CONCEPT or ASSEMBLY | Move link to .Additional resources section. Rewrite surrounding text. | | TaskInclude | include:: inside .Procedure | Inline the included content directly into procedure steps | | RelatedLinks | Non-link content inside .Additional resources | Ensure only links appear. Use proper == headings (not bold pseudo-headings) after .Additional resources to close the section. | | TaskStep | Content after .Procedure is not ordered list | Convert * to . | | TaskSection | == subsections in a PROCEDURE | Remove subsection headings or split into multiple procedures | | TaskTitle | Procedure title not imperative | Rename to imperative phrase | | BlockTitle | Unsupported block title in wrong module type | Remove .Procedure from concepts, etc. | | ExampleBlock | Nested ==== delimiters | Restructure to avoid nesting example blocks |

Step 4: Fix by priority

Process fixes in this order to avoid cascading issues:

1. ContentType + ShortDescription — structural metadata (quick fixes)
2. TaskStep + TaskSection + TaskTitle + BlockTitle — structural violations
3. ConceptLink — move links to Additional resources (most labor-intensive)
4. TaskInclude — inline snippets into procedure steps
5. RelatedLinks — fix Additional resources sections

ConceptLink fix pattern

For each flagged link/xref in a CONCEPT or ASSEMBLY file:

1. Read the file and locate the inline link
2. Move the link to an [role="_additional-resources"] .Additional resources section (create one at end of file if none exists)
3. Rewrite the surrounding sentence to make sense without the inline link
4. If the file has bold pseudo-headings (**text**), convert to == headings (CONCEPT files allow subsections)

TaskInclude fix pattern

For each include:: inside a .Procedure:

1. Read the included snippet file
2. Copy the snippet content directly into the procedure step
3. Remove the include:: directive
4. Verify the inlined content renders correctly in context

RelatedLinks fix pattern

The .Additional resources section ends only when Vale encounters a recognized heading (a line matching == Title or .Title format). Bold pseudo-headings (**text**) are NOT recognized as headings.

For each RelatedLinks warning:

1. Check if there is a bold pseudo-heading after .Additional resources — convert it to a == subsection heading
2. Ensure only links (link:, xref:, >, bare URLs) appear inside the .Additional resources section
3. If the .Additional resources is mid-file, ensure a proper == heading follows it to close the section

Step 5: Verify

Re-run the same method used in Step 2. The result MUST be clean before scoring.

For repo-wide scope — direct Vale invocation

cd "$DOCS_REPO"
find . -name '*.adoc' -not -type l | xargs vale --config=.vale-cqa.ini

For assembly or topic scope — dita-validate-asciidoc

Skill: dita-tools:dita-validate-asciidoc, args: "$ASSEMBLY_OR_TOPIC"

If warnings remain, return to Step 3. Do not score until the output is clean.

Step 6: Score

| Score | Criteria | |-------|----------| | 4 | 0 errors, 0 warnings | | 3 | 0 errors, fewer than 10 warnings | | 2 | Errors present or 10+ warnings | | 1 | Vale not configured or not run |

Record the score, the exact Vale output (file count, error count, warning count), and the Vale version used.

Common mistakes

• Using the repo's own Vale config instead of .vale-cqa.ini — the repo's .vale.ini may use RedHat, AsciiDoc, or RHEL10 styles that produce errors unrelated to CQA P1 (e.g., RedHat.TermsErrors for "vs"). CQA P1 only checks AsciiDocDITA rules.
• Suppressing warnings in Vale config instead of fixing content
• Moving links to Additional resources but leaving a bold pseudo-heading after it (causes RelatedLinks warnings)
• Forgetting to convert bold pseudo-headings to == headings in concept files
• Running Vale on symlinked directories and getting inflated counts

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhatt-rh
• Source: abhatt-rh/redhat-docs-agent-tools
• License: Apache-2.0
• Homepage: https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.