rhpds/showroom:verify-content

---

context: main model: claude-sonnet-4-6

Content Verification Skill

Orchestrates parallel agents to verify workshop or demo content against Red Hat quality standards. Presents one consolidated findings table. User picks which issue to fix first.

Architecture

This skill is an orchestrator. It delegates work to agents:

• showroom:scaffold-checker (Haiku) — checks root config files
• showroom:module-reviewer (Sonnet) — reviews each .adoc module, one agent per file in parallel

The orchestrator handles: repo detection, pre-flight extraction, cross-module logic, result merging, findings presentation, and fix loop.

---

ph_payload — Headless Mode (Publishing House)

If ph_payload is present, skip Phase 1 auto-detect and Phase 6 fix loop. Return structured JSON.

ph_payload:
  content_path: content/modules/ROOT/pages/
  modules: []                    # empty = all modules
  lab_type: workshop
  shared_context:
    defined_attributes: {ocp_version: "4.18", user: user1}
    nav_order: [index, 01-overview, 02-details, 03-module-01]
    first_use_map: {AAP: 01-overview.adoc}

Headless return (JSON only):

{
  "findings": [
    {"id": "E.3a", "module": "03-module-01.adoc", "line": 47, "severity": "High", "message": "..."}
  ],
  "summary": {"critical": 0, "high": 1, "medium": 0, "warnings": 3}
}

---

Phase 1 — Auto-detect (silent, no questions)

Check CWD for Showroom structure:

• content/modules/ROOT/pages/ exists and contains .adoc files → use it, proceed silently

If CWD is not a Showroom repo, output:

📁 No Showroom content found in [CWD].

Provide a local path or GitHub URL:

Wait for user response:

• Local path → use it, proceed
• GitHub URL → ask to clone to /tmp/[repo-name], then proceed

Detect content type silently:

• Has === Verify sections or numbered exercise steps → Workshop
• Has Know/Show structure, presenter notes → Demo
• Cannot determine → default to Workshop

Detect lab type silently from ui-config.yml:

• console-openshift-console or rhods-dashboard → ocp
• /wetty with port: or AAP/Cockpit URLs → vm
• AI/ML workloads referenced → ai
• RHEL/bastion pattern → rhel
• Cannot determine → unknown

Confirm in one line:

📋 Workshop content detected (ocp lab, 6 modules). Launching parallel review...

---

Phase 2 — Pre-flight (orchestrator, inline)

Before spawning agents, extract shared context that all module agents need. Run silently.

2a. Read content/modules/ROOT/nav.adoc Extract: ordered list of module filenames → module_order

2b. Read content/antora.yml Extract: all keys under asciidoc.attributes → defined_attributes

2c. Scan all .adoc files Build first_use_map: for each acronym (OCP, AAP, RHOAI, RHEL, etc.), record which module file contains its first expansion.

2d. Cross-module structure checks (B.1–B.7)

Run these inline now — they require seeing all modules at once:

| ID | Check | Fail condition | Severity | |---|---|---|---| | B.1 | index.adoc exists | Missing | Critical | | B.2 | Workshop: index.adoc is learner-facing. Demo: facilitator-facing | Wrong framing | High | | B.3 | 01-overview.adoc present with scenario/value framing | Missing or no framing | High | | B.4 | 02-details.adoc present | Missing | High | | B.5 | Workshop: ≥1 hands-on module (03-* or higher). Demo: ≥1 Know/Show module | None found | Critical | | B.6 | nav.adoc lists all module files | Any .adoc not in nav | High | | B.7 | Conclusion module exists | Missing | High |

Collect findings. Continue regardless.

Output SHARED_CONTEXT:

{
  "module_order": ["index.adoc", "01-overview.adoc", "..."],
  "defined_attributes": {"ocp_version": "4.18", "user": "user1"},
  "first_use_map": {"OCP": "01-overview.adoc", "AAP": "03-module-01.adoc"},
  "lab_type": "ocp",
  "content_type": "workshop"
}

---

Phase 3 — Spawn agents (parallel)

Spawn all agents simultaneously using the Task tool.

3a. Scaffold agent:

Task tool:
  subagent_type: showroom:scaffold-checker
  prompt: |
    REPO_PATH: <absolute path to repo root>
    CONTENT_TYPE: <workshop|demo>
    SHARED_CONTEXT: <SHARED_CONTEXT JSON>

3b. Module agents (one per .adoc file, all in parallel):

For each module in module_order (skip nav.adoc):

Task tool:
  subagent_type: showroom:module-reviewer
  prompt: |
    MODULE_FILE: <absolute path to .adoc file>
    CONTENT_TYPE: <workshop|demo>
    LAB_TYPE: <ocp|rhel|vm|ai|unknown>
    SHARED_CONTEXT: <SHARED_CONTEXT JSON>
    REPO_PATH: <absolute path to repo root>
    is_first_module: <true if this is 01-overview.adoc>
    is_conclusion: <true if filename contains "conclusion" or "99-">

All agents run concurrently. Wait for all to complete before proceeding.

---

Phase 4 — Merge results (orchestrator, inline)

Collect JSON outputs from all agents.

4a. Apply cross-module logic:

• D.2 (acronym first-use): For each D.2 finding from a module-reviewer, check if the acronym appears in first_use_map. If the first use is in an earlier module, suppress the finding (the expansion already happened).
• E.5 (undefined attributes): For each E.5 finding, check if the attribute appears in defined_attributes. If it does, suppress.

4b. Flatten all findings:

• B.1–B.7 findings from pre-flight (Phase 2)
• All findings from scaffold-checker JSON output
• All findings from module-reviewer JSON outputs (after cross-module suppression)

4c. Deduplicate: same ID + same file + same line → keep one.

4d. Sort: Critical → High → Medium → Warning → Info. Within severity: scaffold (S) before cross-module (B.1–B.7) before content (B.8–F).

---

Phase 5 — Present findings table

Output one table with all findings. Nothing else before it.

## Verification Results

| # | ID | Issue | Severity | Location |
|---|---|---|---|---|
| 1 | S.2a | ui-config.yml missing | Critical | repo root |
| 2 | B.5 | No hands-on module found | Critical | pages/ |
| 3 | E.3a | [source,bash] missing role="execute" | High | module-01.adoc:47 |
| 4 | D.2 | "AAP" used without first-use expansion | Warning | 03-module-01.adoc:12 |

**Total: 4 issues — 2 Critical, 1 High, 0 Medium, 1 Warning**

If zero findings:

✅ No issues found. Content passes all checks.

Then ask:

Which issue do you want to fix first? (Enter the number, e.g. "3")
Or say "all critical", "all high", or "skip" to finish.

---

Phase 6 — Fix loop

When the user picks an issue:

1. Show: BEFORE / AFTER / why (one sentence)
2. Apply the fix
3. Confirm: "Fixed #3. X issues remaining."
4. Re-show remaining table (fixed items removed)
5. Ask: "Which one next?"

Repeat until user says "done", "skip", or no issues remain.

Never fix multiple issues at once unless the user says "all critical" or "all high".

---

Special fix — E.3a: missing role="execute" (bulk replace)

When E.3a is selected:

1. Inform the user:

   This fix replaces [source,bash] / [source,sh] / [source,shell] / [source,console] /
   [source,terminal] / [source,tty] / [source,wetty] → [source,role="execute"]
   across all .adoc files.
   
   It will NOT touch [source,text], [source,yaml], [source,json], or other non-shell blocks.
   
   Apply bulk fix to all module files? [Y/n]
   

2. If YES — replace in each module file. Skip blocks inside [source,asciidoc] fences.

3. Report: "Fixed: replaced N occurrences across M files."

---

Severity reference

| Severity | Meaning | |---|---| | Critical | Lab broken — learner cannot proceed | | High | Key functionality broken or degraded | | Warning | Standards violation — lab works but doesn't meet quality bar | | Info | Optional improvement | | Recommendation | Feature is optional — shown only to inform, not to block or flag. No action required. |

Only Critical and High mark a lab as "not ready". Recommendations are shown at the bottom of the table, separated from issues.

---

Related Skills

• /showroom:create-lab — Create new workshop modules
• /showroom:create-demo — Create presenter-led demo content
• /showroom:blog-generate — Transform workshop to blog post