[RHIDP#12779]: CQA tooling optimization and content modularization

.claude/CLAUDE.md

@@ -0,0 +1,23 @@
+# Red Hat Developer Hub Documentation
+
+## CQA Compliance
+
+When editing `.adoc` files, ALWAYS run the relevant CQA scripts to validate and fix changes before considering the task done. Run all 17 checks at once with `build/scripts/cqa.sh`, or run individual scripts. All share a common interface via `build/scripts/cqa-lib.sh`:
+
+```bash
+# Report issues for a title
+./build/scripts/cqa.sh titles/<title>/master.adoc
+
+# Auto-fix issues
+./build/scripts/cqa.sh --fix titles/<title>/master.adoc
+
+# Run across all titles
+./build/scripts/cqa.sh --all
+
+# Auto-fix across all titles
+./build/scripts/cqa.sh --fix --all
+```
+
+Output markers: `[AUTOFIX]` (auto-fixable), `[FIXED]` (applied), `[MANUAL]` (needs human), `[-> CQA #NN]` (delegated).
+
+For full CQA workflow, load `.claude/skills/cqa-main-workflow.md`. Individual skill files are in `.claude/skills/cqa-*.md`.

.claude/MEMORY.md

@@ -4,205 +4,53 @@ This file contains persistent knowledge about working with the RHDH documentatio
 
 ## CQA 2.1 Compliance Process
 
-### Critical Workflow Rule
-
 **ALWAYS use the checklist for CQA work:**
 
-When starting CQA 2.1 compliance for any title:
-
 1. **FIRST:** Load the workflow files
    ```
-   Read .claude/skills/cqa-master-workflow.md, .claude/cqa-checklist.md, .claude/MEMORY.md
+   Read .claude/skills/cqa-main-workflow.md, .claude/cqa-checklist.md, .claude/MEMORY.md
    ```
-   - The master workflow orchestrates all 17 CQA requirements in optimal order
-   - The checklist follows the same 5-phase structure (updated 2026-03-13)
+   - The main workflow orchestrates all 17 CQA requirements in optimal order
+   - The checklist follows the same 5-phase structure
    - **Idempotency requirement:** Re-execute each requirement until no changes, then re-run entire workflow until stable
 
 2. **VERIFY required information** - If any are missing, ASK the user:
    - JIRA ticket number (e.g., RHIDP-12345)
-   - Title name (e.g., "Installing Red Hat Developer Hub on OpenShift Container Platform") OR
-   - Path to master.adoc file (e.g., `titles/installing-rhdh-ocp/master.adoc`)
+   - Title name or path to master.adoc file
 
 3. **THEN:** Use the master workflow as the guide
-   - Create a TodoWrite with items from cqa-master-workflow.md following the sequence defined in cqa-master-workflow.md
+   - Create a TodoWrite following the sequence in cqa-main-workflow.md
    - Read individual CQA skills (.claude/skills/cqa-##-*.md) for detailed assessment
-   - Run each step sequentially: always await for the previous task completion before running the next task
-   - Respect the sequence order.
+   - Run each step sequentially; respect the sequence order
 
-4. **IMPORTANT:** Fill in the checklist header:
-   - Title name
-   - JIRA number (RHIDP-XXXXX)
-   - Target file path
-
-5. **NEVER claim completion unless:**
-   - ALL checkbox items are marked ✓
+4. **NEVER claim completion unless:**
+   - ALL checkbox items are marked with a checkmark
    - Idempotency verified (re-running workflow produces no changes)
    - TodoWrite shows all tasks complete
-   - User has explicitly verified completion
-
-### Why This Matters
-
-**The problem:** CQA has 17 main steps with multiple sub-steps. Without a checklist, steps get forgotten and completion is claimed prematurely.
-
-**The solution:** The checklist is the single source of truth. If it's not checked, it's not done.
-
-### Automation Scripts
-
-Use these scripts for systematic tasks:
-
-1. **Content Type Detection/Fixing:**
-   ```bash
-   ./build/scripts/cqa-03-content-is-modularized.sh [--fix] titles/<title>/master.adoc
-   ```
-   - Auto-detects and fixes content type metadata
-   - Normalizes .Procedure and .Verification list formatting
-   - Validates PROCEDURE structure
-   - Shows violation breakdown
-
-2. **Title/ID/Filename Alignment:**
-   ```bash
-   ./build/scripts/cqa-10-titles-are-brief-complete-and-descriptive.sh [--fix] titles/<title>/master.adoc
-   ```
-   - Ensures content type metadata exists (calls cqa-03-content-is-modularized.sh if needed)
-   - Fixes title forms (gerund → imperative)
-   - Aligns IDs to match titles
-   - Renames files with git mv
-   - Updates xrefs and includes automatically
-
-3. **Orphaned Module Detection:**
-   ```bash
-   ./build/scripts/fix-orphaned-modules.sh          # Dry-run (lists only)
-   ./build/scripts/fix-orphaned-modules.sh --execute # Actually deletes
-   ```
-   - Finds files not referenced by any include statement
-   - **Dynamic attribute detection** (updated 2026-03-13):
-     - Automatically detects ANY `{...}` attribute substitution
-     - No hardcoded patterns - works with {platform-id}, {context}, {product}, future attributes
-     - Converts include patterns to regex (e.g., `proc-install-on-{platform-id}.adoc` → `proc-install-on-.*[.]adoc`)
-   - Excludes template files (*.template.adoc) - these are code generation sources
-   - Uses `cut -d: -f2-` to extract only include paths (not grep filename prefixes)
-
-4. **Short Description Verification:**
-   ```bash
-   ./build/scripts/cqa-09-short-description-format.sh [--fix] titles/<title>/master.adoc
-   ```
-   - Verifies [role="_abstract"] presence
-   - Checks 50-300 character requirement
-   - Validates no empty line after marker
-
-5. **Build and Preview Generation:**
-   ```bash
-   ./build/scripts/build-ccutil.sh              # ALWAYS run without arguments
-   ```
-   - **IMPORTANT:** Always run without arguments (builds all titles for current branch)
-   - Uses Podman to run ccutil container (quay.io/ivanhorvath/ccutil:amazing)
-   - Processes all titles/*/master.adoc files (excludes rhdh-plugins-reference)
-   - Generates HTML single-page output in titles-generated/${BRANCH}/
-   - Copies referenced images to output directory
-   - Creates navigation index.html
-   - Runs htmltest for link validation
-   - Supports branch-specific builds with `-b <branch>` flag (rarely needed)
 
 ### Reference Materials
 
-**CQA reference materials are updated using:**
-```bash
-./build/scripts/update-cqa-resources.sh
-```
+Updated using `./build/scripts/update-cqa-resources.sh` (weekly minimum, daily maximum).
 See `.claude/skills/update-all-resources.md` for details.
 
-**Update frequency:** Weekly minimum (7 days), daily maximum (1 day)
-
-**Resources maintained:**
+- **SSG:** `.claude/resources/red-hat-ssg.md` — grammar, style, formatting (CQA 8, 9, 10, 12, 16)
+- **Peer Review:** `.claude/resources/red-hat-peer-review.md` — titles, grammar, editorial quality (CQA 10, 12)
+- **Modular Docs:** `.claude/resources/red-hat-modular-docs.md` — content types, module templates (CQA 2-6, 10, 13)
+- **Vale:** `.vale-dita-only.ini` (CQA 1), `.vale.ini` (CQA 12). Sync with `vale sync`. `attributes.adoc` excluded from Vale.
 
-1. **Red Hat Supplementary Style Guide (SSG):**
-   - **Location:** `.claude/resources/red-hat-ssg.md`
-   - **When to reference:** CQA #8, #9, #10, #12, #16 (grammar, style, formatting)
-   - **Key topics:** Conscious language, short descriptions, titles, user-replaced values, Technology Preview
-
-2. **Red Hat Peer Review Guide:**
-   - **Location:** `.claude/resources/red-hat-peer-review.md`
-   - **When to reference:** CQA #10 (titles), CQA #12 (grammar), editorial quality
-   - **Key topics:** Style checklist, grammar rules, formatting standards, review workflow
-
-3. **Red Hat Modular Documentation Guide:**
-   - **Location:** `.claude/resources/red-hat-modular-docs.md`
-   - **When to reference:** CQA #2, #3, #4, #5, #6, #10, #13 (modularization, content types)
-   - **Key topics:** Content types (ASSEMBLY, CONCEPT, PROCEDURE, REFERENCE), module templates, file naming
-
-4. **Vale Linting Rules:**
-   - **Timestamp:** `.claude/.vale-sync-timestamp`
-   - **Sync command:** `vale sync` (automated by update script)
-   - **When to sync:** Before CQA #1 (DITA validation) or CQA #12 (grammar/style validation)
-   - **Configurations:** `.vale-dita-only.ini` (CQA #1), `.vale.ini` (CQA #12)
-   - **Excluded:** `attributes.adoc` is excluded from Vale validation (defines attribute values using literal product names, which triggers false positives for `DeveloperHub.Attributes` rules)
-   - **All DITA warnings must be fixed** — no acceptable warnings. See `.claude/skills/cqa-01-asciidoctor-dita-vale.md` for fix guidance
-
-### Best Practices Learned
+### Best Practices
 
 1. **Scripts first, manual second:** Run all automated scripts before manual fixes
 2. **One step at a time:** Don't batch steps, even if they seem related
 3. **Verify after fixes:** Re-run scripts after manual changes to confirm alignment
 4. **Git mv for renames:** Always use git mv to preserve history
-5. **Update includes last:** Fix filenames before updating include statements
-6. **Check SSG currency:** Before style-related CQA work, ensure SSG is current (within 7 days)
-7. **Sync Vale styles:** Before Vale validation (CQA #1, #12), ensure Vale is synced (within 7 days)
-8. **Idempotency:** Re-run each CQA requirement until no changes, then re-run full workflow until stable
-9. **Settings.json hygiene:**
-   - Use wildcard patterns (e.g., `Bash(find *)`) not specific commands
-   - Never commit sensitive information (usernames, API keys, absolute paths with usernames)
-   - Use relative paths (.claude, .claude/resources) not absolute paths
-   - Alphabetize permissions for maintainability
-   - Verify with `jq . .claude/settings.json` before committing
-
-### Common Pitfalls to Avoid
-
-❌ **Don't:** Skip the checklist and try to remember all steps
-✅ **Do:** Load checklist first, mark items as done
-
-❌ **Don't:** Claim "CQA complete" without showing all ✓ items
-✅ **Do:** Show checklist with all items marked before claiming completion
-
-❌ **Don't:** Run steps out of order
-✅ **Do:** Follow exact sequence in checklist
-
-❌ **Don't:** Batch steps together ("I'll do 2-4 at once")
-✅ **Do:** Complete each step fully, mark it ✓, then proceed
+5. **Idempotency:** Re-run each CQA requirement until no changes, then re-run full workflow until stable
 
 ### Pull Request Guidelines
 
-**CRITICAL:** When creating PR descriptions, **never use `#` notation for CQA numbers** (e.g., avoid "CQA #1", "CQA #2").
-
-❌ **Don't write:** "CQA #1", "CQA #2", "CQA #17"
-✅ **Do write:** "CQA 1", "CQA 2", "CQA 17"
-
-**Reason:** GitHub automatically creates links for `#number` patterns, linking to unrelated issues/PRs and creating noise.
-
-**PR Description Format for CQA Work:**
-```markdown
-## Summary
-
-Completed CQA 2.1 validation for `titles/<title-name>/master.adoc`:
-
-### Validation Results
-- ✅ **CQA 1**: Vale DITA validation (0 errors, acceptable warnings)
-- ✅ **CQA 2**: Assembly structure compliance
-- ✅ **CQA 3**: Content modularization verified
-...
-- ✅ **CQA 17**: Disclaimers not applicable (no preview features)
-
-### Key Changes
-- List of major changes made
-- File renames, content updates, etc.
-
-### Files Changed
-- List of modified files
+**Never use `#` notation for CQA numbers** in PR descriptions (e.g., write "CQA 1" not "CQA #1"). GitHub auto-links `#number` to unrelated issues/PRs.
 
-## Test Plan
-- [x] All CQA automation scripts pass
-- [x] Vale validations pass
-- [x] Build successful
-```
+PR description format is in `.claude/cqa-checklist.md`.
 
 ## Repository Structure
 
@@ -212,13 +60,9 @@ Completed CQA 2.1 validation for `titles/<title-name>/master.adoc`:
 - `artifacts/` - Reusable snippets and fragments
 - `build/scripts/` - Automation scripts for CQA and validation
 - `.claude/` - Claude Code configuration and documentation
-  - `settings.json` - Repository-specific permissions and settings
-  - `MEMORY.md` - This file - persistent knowledge for Claude
-  - `cqa-checklist.md` - CQA 2.1 compliance checklist template
 
 ## User Preferences
 
 - Uses wildcard patterns in .claude/settings.json (not individual files)
 - Prefers focused, single-purpose tasks over large multi-step processes
 - Values explicit tracking with TodoWrite for complex workflows
-- Commits frequently with descriptive messages including "Co-Authored-By: Claude Sonnet 4.5"

.claude/README.md

@@ -35,8 +35,8 @@ Comprehensive checklist template for CQA 2.1 compliance work. Contains:
 ### `skills/`
 CQA 2.1 compliance assessment skills:
 
-**Master Workflow:**
-- `cqa-master-workflow.md` - Complete CQA process orchestrating all 17 requirements in optimal order
+**Main Workflow:**
+- `cqa-main-workflow.md` - Complete CQA process orchestrating all 17 requirements in optimal order
 
 **Individual Skills (17 total):**
 - `cqa-01-*.md` through `cqa-17-*.md` - One skill per Pre-migration requirement