Cqa Assess

Mode — what to do with issues:

• Assess only — report issues and score, but do not modify any files
• Assess and fix — report issues, fix them, re-verify, then score

Severity filtering — which parameters to run:

• All (default) — run all parameters in dependency order
• Required only — run only Required-level parameters (blockers). Skip Important-level parameters.
• One skill — run only the specified skill (e.g., cqa-legal-branding). Use the Skill Map below to identify which parameters are covered.
• Skip list — run all parameters except the specified ones (e.g., skip O9, O10 if Pantheon is not used)

Steps 1-8: For each parameter

1. Pick a parameter from the checklist (or let the user specify one)
2. Invoke the matching skill for that parameter group
3. Run the check — automated where possible, manual review where needed. Apply to the files within the user's chosen scope only.
4. If assess-and-fix mode: fix issues found during the check, then re-run the check to confirm 0 issues
5. Score the parameter with evidence
6. Report results to the user: score, evidence, files changed (if any)
7. Mark parameter complete on the checklist
8. Repeat for the next parameter

Skill Map

Assessment Order

Recommended order (dependencies flow downward):

1. cqa-tools:cqa-vale-check — foundational; fixes here affect other checks
2. cqa-tools:cqa-modularization — structural compliance
3. cqa-tools:cqa-titles-descriptions — metadata quality
4. cqa-tools:cqa-procedures — procedure structure
5. cqa-tools:cqa-editorial — writing quality
6. cqa-tools:cqa-links — cross-references and URLs
7. cqa-tools:cqa-legal-branding — compliance
8. cqa-tools:cqa-user-focus — content quality
9. cqa-tools:cqa-tables-images — visual elements
10. cqa-tools:cqa-onboarding — publishing readiness
11. cqa-tools:cqa-report — final summary

Include-tree resolution

When the user chooses "One assembly" scope, use resolve-includes.py to build the exact file list before running any checks. This prevents scope leakage (scanning files outside the assembly's include tree).

# List all files included by an assembly (recursively follows include:: directives)
python3 ${CLAUDE_SKILL_DIR}/scripts/resolve-includes.py "$DOCS_REPO/assemblies/admin/assembly_installing.adoc" --base-dir "$DOCS_REPO"

# Tree view showing the include hierarchy
python3 ${CLAUDE_SKILL_DIR}/scripts/resolve-includes.py "$DOCS_REPO/assemblies/admin/assembly_installing.adoc" --base-dir "$DOCS_REPO" --format tree

# JSON output for programmatic use
python3 ${CLAUDE_SKILL_DIR}/scripts/resolve-includes.py "$DOCS_REPO/assemblies/admin/assembly_installing.adoc" --base-dir "$DOCS_REPO" --format json

# Include the root file itself in the output
python3 ${CLAUDE_SKILL_DIR}/scripts/resolve-includes.py "$DOCS_REPO/assemblies/admin/assembly_installing.adoc" --base-dir "$DOCS_REPO" --include-root

The script handles symlinks, attribute placeholders in paths, circular includes, and conditional includes (ifdef/ifndef). Exit codes: 0 (all resolved), 1 (some unresolved), 2 (invalid arguments).

Scoping workflow:

1. Run resolve-includes.py to get the file list for the assembly
2. Pass only those files to each check script via --scan-dirs or by filtering output
3. Score based only on issues within the scoped files

Automation Scripts

Reusable scripts in skills/cqa-assess/scripts/ automate repetitive checks. Each script accepts a docs repo path and exits 0 (pass), 1 (issues found), or 2 (invalid arguments). Python 3.9+ stdlib only.

All check scripts (except check-legal-notices.py) scan assemblies/, modules/, topics/, and snippets/ by default. Use --scan-dirs to override (e.g., --scan-dirs topics assemblies to skip snippets). check-legal-notices.py checks titles/*/ for docinfo.xml and the repo root for LICENSE — use --repo-root to specify the repo root when the docs directory is a subdirectory.

Run all check scripts at once:

for script in scripts/check-*.py; do
  python3 "$script" "$DOCS_REPO"
  echo "---"
done

Important Rules

• Respect the user's chosen mode. In assess-only mode, never modify files. In assess-and-fix mode, fix everything before scoring.
• Respect the user's chosen scope. Only assess files within the scope (repo, assembly + its topics, or single topic). Do not scan files outside the scope. For assembly scope, use resolve-includes.py to determine the exact file list.
• Respect severity filtering. If the user selected "Required only" or provided a skip list, only run the applicable parameters.
• 0 errors, 0 warnings for automated checks. Never suppress or ignore.
• Evidence before claims. Run the verification command, read the output, then state the score.
• Cross-reference awareness. Some parameters overlap across skills (e.g., P12 prerequisites in both cqa-procedures and cqa-modularization). When both skills run, use the canonical skill's result and skip the duplicate. See each skill's Cross-references section.
• Update project rules with any new rules discovered during the assessment.