Cqa Modularization

CQA P2-P7: Modularization

Parameters

| # | Parameter | Level | |---|-----------|-------| | P2 | Assemblies contain only intro + includes (no rendered text between includes) | Required | | P3 | Content is modularized (correct prefixes: assembly, con, proc, ref, snip_) | Required | | P4 | Modules use official templates (Concept, Procedure, Reference) | Required | | P5 | All required modular elements present (content type, ID, title, abstract) | Required | | P6 | Assemblies use official template | Required | | P7 | Content not deeply nested (max 3 levels: master -> assembly -> topic) | Important |

Automation scripts

This skill has an automation script:

| Script | Parameters | What it checks | |--------|-----------|----------------| | check-content-types.py | P3, P4, P5 | Prefix vs content type match, required elements, invalid block titles, procedure structure |

Python 3.9+ stdlib only, no dependencies. Exit code 0 = pass, 1 = issues found.

python3 ${CLAUDE_PLUGIN_ROOT}/skills/cqa-assess/scripts/check-content-types.py "$DOCS_REPO"

Checks: filename prefix matches :_mod-docs-content-type:, [role="_abstract"] present, [id="..._{context}"] present, no procedure-only block titles in non-procedure files, no == subsections in procedures, ordered list after .Procedure.

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/, and titles/ directories.

Store this as DOCS_REPO for all subsequent steps.

Step 2: P2 — Assembly structure (no rendered text between includes)

Assemblies map to DITA maps. DITA maps do not accept rendered text between module includes.

Rule

An assembly has three sections in strict order:

1. Introductory section (before the first include::) — metadata, title, abstract, and one or more paragraphs, admonition blocks, and/or lists. All rendered text must appear here.
2. Include statements — include:: directives for topics, separated only by blank lines and AsciiDoc comments (// ...). No rendered text is allowed between includes.
3. Additional resources (optional, after all includes) — a [role="_additional-resources"] .Additional resources section with links.

Check procedure

For each assembly_*.adoc file in assemblies/:

1. Read the file
2. Find the line number of the first include:: directive
3. Find the line number of the last include:: directive
4. Scan lines between the first and last include:: — only the following are allowed:

• include:: directives
• Blank lines
• AsciiDoc comments (// ...)

1. Any other content (paragraphs, bullet lists, ordered lists, admonition blocks, bold text) is a violation

Fix pattern

Move all rendered text that appears between includes to the introductory section before the first include::. If the text is specific to a particular topic, consider absorbing it into that topic's abstract or content instead.

Scoring

| Score | Criteria | |-------|----------| | 4 | All assemblies have no rendered text between includes | | 3 | 1-2 assemblies with minor text between includes (e.g., a single comment-like sentence) | | 2 | Multiple assemblies with paragraphs, lists, or admonitions between includes | | 1 | Assembly structure not assessed or widespread violations |

Step 3: P3 — Content is modularized

Reference: https://redhat-documentation.github.io/modular-docs/

Rule

Content is modularized when it follows the Red Hat modular documentation framework:

1. All content is organized into discrete modules — each module is an independent, self-contained chunk of information that makes sense on its own.
2. Each module has a single content type — Concept (explains what/why), Procedure (step-by-step how-to), or Reference (lookup data). No mixed types in a single file.
3. Modules are grouped into assemblies — assemblies correspond to user stories and include related modules via include:: directives.
4. Consistent naming prefixes — every file uses the correct prefix for its content type.
5. Content type declaration matches actual content — the :_mod-docs-content-type: attribute, the filename prefix, and the actual content must all agree.

Check 1: File prefix compliance

Ask the user for the directory structure of their docs repo. The typical Red Hat modular docs repo has assemblies/, topics/ (or modules/), and snippets/ directories.

For each .adoc file, verify it uses the correct prefix:

| Directory | Required prefix(es) | |-----------|---------------------| | Assemblies directory | assembly_ | | Topics/modules directory (concepts) | con_ | | Topics/modules directory (procedures) | proc_ | | Topics/modules directory (references) | ref_ | | Snippets directory | snip_ |

List all files and flag any that don't match the expected prefix pattern.

Check 2: Content type declaration

For each .adoc file in the assemblies and topics directories, read the first line and check for :_mod-docs-content-type: attribute. Valid values: ASSEMBLY, CONCEPT, PROCEDURE, REFERENCE, SNIPPET.

Flag any files that:

• Are missing the :_mod-docs-content-type: declaration
• Have an invalid or misspelled value

Check 3: Prefix vs content type cross-check

For each file, verify the filename prefix matches the declared content type:

| Prefix | Expected :_mod-docs-content-type: | |--------|--------------------------------------| | assembly_ | ASSEMBLY | | con_ | CONCEPT | | proc_ | PROCEDURE | | ref_ | REFERENCE | | snip_ | SNIPPET |

Flag any mismatches.

Check 4: Content type vs actual content

Verify the declared content type matches what the file actually contains:

| Content type | Must contain | Must NOT contain | |--------------|-------------|------------------| | PROCEDURE | .Procedure section with ordered list steps (. ) | — | | CONCEPT | Explanatory/descriptive content | .Procedure section | | REFERENCE | Structured data (tables, lists, source blocks) | .Procedure section | | ASSEMBLY | include:: directives | .Procedure section |

Check ALL procedure files for .Procedure with ordered steps. Check ALL concept files to confirm they have no .Procedure section. Check ALL reference files to confirm they contain structured data.

Check 5: Title quality

Reference:

• https://redhat-documentation.github.io/modular-docs/#con-creating-procedure-modules_writing-mod-docs
• https://ccs-internal-documentation.pages.redhat.com/peer-review/#_style

Titles must be brief, complete, and descriptive. Assess three dimensions:

Check 5a: Grammatical form

| Module type | Required form | Examples | |-------------|--------------|----------| | PROCEDURE | Imperative phrase (verb) | "Configure OAuth", "Install Dev Spaces" | | CONCEPT | Noun phrase (NOT gerund) | "Architecture overview", "Server components" | | REFERENCE | Noun phrase | "Supported platforms", "CheCluster fields" | | ASSEMBLY (task-based) | Imperative phrase | "Configure server components" | | ASSEMBLY (non-procedural) | Noun phrase | "Red Hat Process Automation Manager API reference" |

An assembly is task-based if it contains procedure modules. Flag any procedure title not in imperative form, concept/reference titles using imperatives or gerunds, or task-based assembly titles using noun phrases.

Check 5b: Title length

Per the CCS peer review guide, titles should be 3-11 words long and have 50-80 characters.

| Violation | Threshold | Action | |-----------|-----------|--------| | Too short | 1-2 words AND title is vague without context | Flag — add descriptive context | | Too long | Over 11 words OR over 80 resolved characters | Flag — shorten by removing redundant qualifiers | | Borderline short | 2 words but unambiguous (e.g., "Creating workspaces") | Do NOT flag — acceptable in context |

When counting characters, resolve AsciiDoc attributes to their display text (e.g., {prod-short} = "OpenShift Dev Spaces" = 20 chars).

Check 5c: Title quality

| Criterion | Rule | |-----------|------| | Descriptive | A reader should understand what the content covers from the title alone | | Customer-focused | Focus on customer tasks, not product features | | Sentence case | Only proper nouns, product names, and Kubernetes resource names are capitalized | | No weak openers | Do not start concept titles with "About" or "Understanding" — use a noun phrase that directly names the concept | | No vague titles | Single-word titles like "Architecture" or "Gateway" lack context — add the product or component name | | Correct article before attributes | {prod-short} resolves to "OpenShift Dev Spaces" (vowel sound) — use "an {prod-short}", not "a {prod-short}" | | No redundant product names | Do not hardcode product names before attributes that already contain them (e.g., "OpenShift {prod}" doubles "OpenShift") | | Concise phrasing | Remove filler words ("the code of applications running in" → "application code from") |

Scoring

| Score | Criteria | |-------|----------| | 4 | All files use correct prefixes, all content type declarations match, all content matches declared type, all titles follow conventions | | 3 | 1-3 minor issues (e.g., a borderline title, a concept with a minor procedural element) | | 2 | Multiple files with wrong prefixes, missing declarations, or content type mismatches | | 1 | Content is not modularized or no consistent structure |

Record: total file count, count by content type, number of violations per check.

Step 4: P4 — Modules use official templates

Reference: https://github.com/redhat-documentation/modular-docs/tree/main/modular-docs-manual/files

The official templates define the required structural elements for each module type. Every module must conform to its type's template.

Check 1: Required elements (all non-snippet files)

Every module (except snippets) must have these 4 elements:

1. :_mod-docs-content-type: attribute as the first content line (value: CONCEPT, PROCEDURE, REFERENCE, or ASSEMBLY)
2. [id="name_{context}"] anchor with {context} suffix
3. = Title level-1 heading
4. [role="_abstract"] annotation followed by a short description paragraph

For each .adoc file in the assemblies and topics directories, verify all 4 elements are present. Report any files missing any element.

Check 2: Procedure template compliance

Per the official procedure template, procedure modules must have:

• .Procedure section followed by ordered list steps (. )

The following block titles are optional but, when present, must appear in the correct order:

| Block title | Position | Required? | |-------------|----------|-----------| | .Prerequisites or .Prerequisite | Before .Procedure | Optional | | .Procedure | Required position | Required | | .Verification, .Results, or .Result | After .Procedure | Optional | | .Troubleshooting, .Troubleshooting steps, or .Troubleshooting step | After .Verification | Optional | | .Next steps or .Next step | After .Troubleshooting | Optional | | .Additional resources | Last section | Optional |

Each block title can appear at most once per module. Check all procedure files for:

• Presence of .Procedure with ordered list steps
• Correct ordering of optional sections
• No duplicate block titles

Check 3: Procedure-only block titles in wrong module types

These block titles are ONLY allowed in procedure modules:

• .Prerequisites / .Prerequisite
• .Procedure
• .Verification / .Results / .Result
• .Troubleshooting / .Troubleshooting steps / .Troubleshooting step
• .Next steps / .Next step

Search ALL concept, reference, and assembly files for these block titles. Any occurrence is a violation.

Check 4: Additional resources annotation

For every file that contains .Additional resources, verify that [role="_additional-resources"] appears on the line immediately before it. A missing role annotation is a violation.

Check 5: Prerequisites quality

Reference: https://redhat-documentation.github.io/modular-docs/#prerequisites

If a procedure includes prerequisites, verify:

Check 5a: Label format

• Must use .Prerequisites (plural, dot-prefixed AsciiDoc block title), even with a single prerequisite item
• Flag: .Prerequisite (singular), **Prerequisites** (bold pseudo-heading), == Prerequisites (heading)

Check 5b: Formatting

• Prerequisites must be an unordered list using * bullet markers
• List items must have parallel grammatical structure
• Admonition blocks within the prerequisites section must be attached to a list item via + continuation — not placed as standalone blocks between .Prerequisites and .Procedure

Check 5c: Maximum count

• Do not exceed 10 prerequisite items per procedure

Check 5d: No steps in prerequisites (declarative language)

Prerequisites are conditions that must already be true, not steps the user must perform.

| Pattern | Assessment | |---------|------------| | "You have access to..." | GOOD — declarative condition | | "A running instance of..." | GOOD — declarative state | | "tool-name is installed." | GOOD — declarative condition | | "You must have access to..." | BAD — imperative "must have", change to "You have" | | "Install the CLI tool." | BAD — imperative action step | | "Ensure that you have..." | BAD — imperative instruction | | "To get X, rebuild Y." | BAD — imperative action disguised as prerequisite | | "Ask a DNS provider to..." | BAD — imperative action step |

A prerequisite may reference another procedure with an xref for HOW to achieve the condition (e.g., "{prod-cli}. See: xref:procinstalling-the-dsc-management-tool{context}[].").

Check 5e: Placement

• .Prerequisites must appear before .Procedure
• No rendered content (admonitions, paragraphs, snippet includes) between the prerequisites list and .Procedure unless attached to a list item via + continuation

Common placement violations:

| Pattern | Problem | Fix | |---------|---------|-----| | Standalone [WARNING] block between prerequisites and .Procedure | Content gap between sections | Attach to last prerequisite item with + continuation | | include::snippets/... between prerequisites and .Procedure | Snippet renders outside list | Attach to last prerequisite item with + continuation | | [IMPORTANT] block with imperative items between prerequisites and .Procedure | Combines placement and language violations | Convert to proper prerequisite list items with declarative wording |

Scoring

| Score | Criteria | |-------|----------| | 4 | All modules conform to their official template — all required elements present, correct block title usage, no procedure-only titles in wrong types, all Additional resources annotated, all prerequisites use declarative language with correct formatting | | 3 | 1-3 minor issues (e.g., a missing optional annotation, one misplaced block title) | | 2 | Multiple files missing required elements or widespread block title violations | | 1 | Templates not followed or not assessed |

Record: total files checked, checks performed per file, number of violations per check category.

Step 5: P5 — All required modular elements are present

Reference:

• Templates: https://github.com/redhat-documentation/modular-docs/tree/main/modular-docs-manual/files
• Assembly definition: https://redhat-documentation.github.io/modular-docs/#assembly-definition

P5 checks that every non-negotiable modular element is present AND meets quality standards. The structural presence of elements is checked in P4. P5 adds the quality dimension — particularly for the short description (abstract).

Check 1: Structural elements and abstract formatting

Reference: "Rewrite for Impact: DITA short descriptions" (CC

…

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.