Showroom:create Lab

context: main model: sonnet

Lab Module Generator

Guide you through creating a single Red Hat Showroom workshop module from reference materials (URLs, files, docs, or text) with business storytelling and proper AsciiDoc formatting.

Workflow Diagram

What You'll Need Before Starting

Have these ready before running this skill:

Required:

• 📁 Target directory path - Where to create modules (default: content/modules/ROOT/pages/)
• 📚 Reference materials - At least one of:
  • URLs to documentation, blogs, or guides
  • Local files with technical content
  • Text/notes describing what to build
• 🎯 Learning objective - What should learners accomplish?

Helpful to have:

• 🏢 Company/scenario context - Business story for the lab (e.g., "ACME Corp needs...")
• ⏱️ Target duration - How long should this module take? (e.g., 15 min, 30 min)
• 👥 Audience level - Beginner, Intermediate, or Advanced
• 📝 Previous modules - If continuing existing lab, know which module comes before this one

Access needed:

• ✅ Write permissions to the Showroom repository directory

When to Use

Use this skill when you want to:

• Create a new workshop module from scratch
• Convert documentation into hands-on lab format
• Add a module to an existing workshop
• Transform technical content into engaging learning experience

Don't use this for:

• Creating demo content → use /create-demo
• Converting to blog posts → use /blog-generate
• Reviewing existing content → use /verify-content

Shared Rules

IMPORTANT: This skill follows shared contracts defined in .claude/docs/SKILL-COMMON-RULES.md:

• Version pinning or attribute placeholders (REQUIRED)
• Reference enforcement (REQUIRED)
• Attribute file location (REQUIRED)
• Image path conventions (REQUIRED)
• Navigation update expectations (REQUIRED)
• Failure-mode behavior (stop if cannot proceed safely)

See SKILL-COMMON-RULES.md for complete details.

Arguments (Optional)

This skill supports optional command-line arguments for faster workflows.

Usage Examples:

/create-lab                                    # Interactive mode (asks all questions)
/create-lab <directory>                        # Specify target directory
/create-lab <directory> --new                  # Create new lab in directory
/create-lab <directory> --continue <module>    # Continue from specific module

Parameters:

• <directory> - Target directory for module files
  • Example: /create-lab content/modules/ROOT/pages/
  • If not provided, defaults to content/modules/ROOT/pages/
• --new - Flag to create new lab (generates index + overview + details + module-01)
• --continue <module-path> - Continue from specified previous module
  • Example: /create-lab content/modules/ROOT/pages/ --continue content/modules/ROOT/pages/03-module-01-intro.adoc
  • Reads previous module to detect story continuity

How Arguments Work:

• Arguments skip certain questions (faster workflow)
• You can still use interactive mode by calling /create-lab with no arguments
• Arguments are validated before use

Workflow

CRITICAL RULES

1. Ask Questions SEQUENTIALLY

• Ask ONE question or ONE group of related questions at a time
• WAIT for user's answer before proceeding
• Do NOT ask questions from multiple steps together
• Do NOT skip workflows based on incomplete answers

2. File Generation Order (First Module ONLY)

If this is the FIRST module of a NEW lab, you MUST generate files in this EXACT order:

1. index.adoc - Learner landing page (NOT facilitator guide)
2. 01-overview.adoc - Business scenario and learning objectives
3. 02-details.adoc - Technical requirements and setup
4. 03-module-01-*.adoc - First hands-on module

NEVER skip index/overview/details for first module!

File naming convention:

• index.adoc (no number prefix)
• 01-overview.adoc
• 02-details.adoc
• 03-module-01-*.adoc
• 04-module-02-*.adoc
• 05-module-03-*.adoc
• etc.

If continuing existing lab:

• Detect next file number from existing modules
• Generate: 0X-module-YY-*.adoc (where X = next sequential file number)
• Example: If existing has 03-module-01, 04-module-02, next is 05-module-03
• Skip index/overview/details (already exist)

3. Manage Output Tokens

• NEVER output full module content - Use Write tool to create files
• Show brief confirmations only - "✅ Created: filename (X lines)"
• Keep total output under 5000 tokens - Summaries, not content
• Files are written, not displayed - User reviews with their editor
• Token limit: Claude Code has 32000 token output limit - stay well below it

Example of WRONG approach:

❌ Asking all at once:
1. Module file name?
2. UserInfo variables?
3. Learning objective?
4. Number of exercises?

Example of CORRECT approach:

✅ Ask sequentially:
Step 2: Complete overall lab story planning
[WAIT for completion]

Step 3.1: Module file name?
[WAIT for answer]

Step 3.2: Reference materials?
[WAIT for answer]

etc.

Step 0: Reference Repository Setup (IMPORTANT)

Before generating content, we need access to real Showroom examples for quality reference.

CRITICAL: This step MUST happen before any content generation to ensure quality matches real Showroom standards.

Ask the user:

📚 Reference Repository Check

To generate high-quality content that matches Showroom standards, I need access to real Showroom examples.

Do you have a Showroom repository cloned locally that I can reference for patterns and examples?

Options:
1. Yes - I have a local Showroom repo (Recommended - best quality)
2. No - Clone template to /tmp/ for me
3. Skip - Generate without reference (Not recommended - may need manual rewrites)

Your choice: [1/2/3]

If Option 1 (YES - Local repo):

Great! Please provide the path to your Showroom repository:

Example: ~/work/showroom-content/my-workshop

Path:

Validation:

• Check if path exists using Read tool
• Verify it contains content/modules/ROOT/pages/*.adoc files
• If invalid, ask again or offer Option 2

Once valid path provided:

1. Read 2-3 example modules from content/modules/ROOT/pages/*.adoc
2. Analyze and learn from:
   • Section structure (= Title, == Heading, === Subheading)
   • Code block formatting and syntax highlighting
   • Admonition usage (TIP, NOTE, WARNING, IMPORTANT)
   • Image and diagram patterns (link=self,window=blank usage)
   • Navigation includes and xrefs
   • List formatting (blank lines before/after lists)
   • External link patterns (^ caret usage)
   • Business scenario integration
3. Use these patterns as templates for generating new content

If Option 2 (NO - Clone template):

I'll clone the Showroom template repository to /tmp/showroom-reference for you.

This provides standard Showroom examples to ensure quality output.

Proceed? [Yes/No]

If Yes:

git clone https://github.com/rhpds/showroom-template /tmp/showroom-reference

Then:

1. Read example modules from /tmp/showroom-reference/content/modules/ROOT/pages/*.adoc
2. Analyze patterns (same as Option 1)
3. Use for content generation

If No or clone fails:

• Warn user: "⚠️ Without reference examples, generated content quality may require significant manual rewrites"
• Ask: "Continue anyway? [Yes/No]"
• If Yes, proceed with generic templates (lower quality expected)
• If No, exit skill

If Option 3 (Skip):

⚠️  WARNING: Generating without reference repository

Without real Showroom examples, the generated content:
- May not match Showroom quality standards
- Will likely need manual rewrites
- May miss important formatting patterns
- Could take 5x longer to finalize

This is the issue reported: "Module 2 is crap, requires manual rewrite with actual showroom docs"

Are you sure you want to skip reference repository? [Yes/No]

If Yes: Proceed with generic templates, but add note in final output warning about potential quality issues If No: Go back to Option 1 or 2

Why This Step Matters:

Before this fix:

• ❌ Module 2 was "crap"
• ❌ Required manual rewrite using actual Showroom docs
• ❌ 5 days of rework time
• ❌ WebFetch tried to get examples from GitHub URLs but got 404 errors

After this fix:

• ✅ Modules generated with quality matching real Showroom content from first iteration
• ✅ Reduces manual rewrites from days to hours
• ✅ AI learns from actual examples, not generic patterns
• ✅ Faster iteration, fewer back-and-forth edits

Store reference path for later use:

• Save reference repository path to use throughout content generation
• When generating modules, read reference examples to match quality
• Apply learned patterns to new content

Step 1: Parse Arguments (If Provided)

Check if user invoked skill with arguments.

Pattern 1: /create-lab <directory> --new

Parsing arguments: "<directory> --new"

✓ Target directory: <directory>
✓ Mode: Create new lab
✓ Will generate: index.adoc → 01-overview → 02-details → 03-module-01

Validating directory...
[Check if directory exists, create if needed]

Skipping: Step 1 (mode already known: NEW lab)
Proceeding to: Step 2 (Plan Overall Lab Story)

Pattern 2: /create-lab <directory> --continue <module-path>

Parsing arguments: "<directory> --continue <module-path>"

✓ Target directory: <directory>
✓ Mode: Continue existing lab
✓ Previous module: <module-path>

Validating directory...
[Check if directory exists]

Reading previous module: <module-path>
[Extract story, company, progression]

Skipping: Step 1 (mode already known: CONTINUE)
Skipping: Step 2 (story detected from previous module)
Proceeding to: Step 3 (Module-Specific Details)

Pattern 3: /create-lab <directory>

Parsing arguments: "<directory>"

✓ Target directory: <directory>

Validating directory...
[Check if directory exists]

Skipping: Target directory question
Proceeding to: Step 1 (still need to ask: new vs continue)

Pattern 4: /create-lab (no arguments)

No arguments provided.

Using interactive mode.
Target directory: Will use default (content/modules/ROOT/pages/)

Proceeding to: Step 1 (Determine Context)

Argument Validation:

• If directory doesn't exist, ask user: "Directory not found. Create it? [Yes/No]"
• If --continue but module path invalid, fall back to asking for story recap
• All arguments are optional - skill always works in interactive mode

Step 2: Determine Context (New Lab vs Existing Lab)

SKIP THIS STEP IF:

• User provided --new flag in arguments (already know: NEW lab)
• User provided --continue <module> in arguments (already know: EXISTING lab)

CRITICAL: DO NOT read any files or make assumptions before asking this question!

First, ask the user:

Welcome! Let's create your workshop together.

Are you starting a brand new lab or adding to an existing one?

1. 🆕 NEW lab (I'll create the whole thing: index → overview → details → first module)
2. ➕ EXISTING lab (I'll add the next module and continue your story)
3. 🤔 Something else (tell me what you need)

What's your situation? [1/2/3]

ONLY AFTER user answers, proceed based on their response.

Step 2.5: Ask for Target Directory (if not provided as argument)

SKIP THIS STEP IF: User provided <directory> as argument

Ask the user:

Where should I create the lab files?

Default location: content/modules/ROOT/pages/

Press Enter to use default, or type a different path:

Validation:

• If directory doesn't exist, ask: "Directory not found. Create it? [Yes/No]"
• If Yes, create the directory
• If No, ask again for directory

If option 1 (NEW lab):

• Generate ALL workshop files: index.adoc, 01-overview.adoc, 02-details.adoc, 03-module-01-*.adoc
• Proceed to Step 2 (Plan Overall Lab Story)

If option 2 (EXISTING lab):

• Detect next file number from existing modules
• Generate ONLY next module: 0X-module-YY-*.adoc
• Skip Step 2 (already have overall story)
• Ask for previous module path or story recap

If continuing existing lab:

• Option 1: Provide path to previous module (I'll read and auto-detect story)
• Option 2: If previous module not available, I'll ask for story recap:
  • Company name and scenario
  • What was completed in previous modules
  • Current learning state
  • What comes next in progression

Fallback behavior:

• If user says "continuing" but cannot provide previous module content or workspace access:
  • Ask user to paste content of last module (or key sections)
  • OR ask short "Story Recap" questions:
    1. Company/scenario name?
    2. What topics were covered in previous modules?
    3. What skills have learners gained so far?
    4. What's the current state in the story?
  • This prevents broken continuity

Step 3: Plan Overall Lab Story (if first module)

Awesome! Let's design your workshop together. I'll ask you some questions to build the perfect learning experience.

IMPORTANT: Ask these as conversational, open-ended questions. Do NOT provide multiple choice options.

Question 1 - What Should We Call This?:

What's the name of your workshop?

Example: "Building AI/ML Workloads on OpenShift AI"

I'll use this to set up your lab title and generate a clean URL-friendly slug.

Your lab name:

[After user provides title, I'll suggest a slug like "building-ai-ml-workloads-openshift-ai"]

Question 2 - The Learning Goal:

What's the main goal of this lab?

What should learners be able to do when they finish?

Example: "Learn to build and deploy AI/ML workloads on OpenShift AI"

Your lab goal:

Question 3 - Who's Learning?:

Who is this lab designed for?

Examples: Developers, Architects, SREs, Data Scientists, Platform Engineers

Your target audience:

What's their experience level?
- Beginner (new to the technology)
- Intermediate (some hands-on experience)
- Advanced (production experience)

Their level:

Question 4 - The Learning Journey:

By the end of this lab, what should learners understand and be able to do?

List the key skills they'll gain:

Your learning outcomes:

Question 5 - Make It Real:

What company or business scenario should we use to make this relatable?

Examples: "ACME Corp", "RetailCo", "FinTech Solutions"
Or create your own!

Company name:

What business challenge are they facing that drives this learning?

Their challenge:

Question 6 - How Long?:

How much time should learners budget for the complete lab?

Typical options: 30min, 1hr, 2hr

Your target duration:

Question 7 - Technical Environment:

Let's nail down the technical details:

OpenShift version? (e.g., "4.18", "4.20", or I can use {ocp_version} placeholder)

Product versions? (e.g., "OpenShift Pipelines 1.12, OpenShift AI 2.8")

Cluster type? (SNO or multinode)

Access level? (admin only, or multi-user with keycloak/htpasswd)

Your environment details:

Note: If you're not sure, I'll use placeholders that work across versions.

Then I'll recommend:

• Suggested module breakdown (how many modules, what each covers)
• Progressive learning flow (foundational → intermediate → advanced)
• Story arc across modules
• Key milestones and checkpoints

You can:

• Accept the recommended flow
• Adjust module count and topics
• Change the progression

Step 3.1: Update Lab Configuration Files (REQUIRED for new labs)

CRITICAL: Update these files with the lab name BEFORE generating any content files.

Using the lab title and slug from Step 2, update:

1. site.yml (line 3):

   site:
     title: {{ lab_title }}  # e.g., "Building AI/ML Workloads on OpenShift AI"
   

2. content/antora.yml (line 2):

   name: modules
   title: {{ lab_title }}  # Same as site.yml
   

3. content/antora.yml (line 9):

   asciidoc:
     attributes:
       lab_name: "{{ lab_slug }}"  # e.g., "building-ai-ml-workloads-openshift-ai"
   

Example transformation:

• User says: "Building AI/ML Workloads on OpenShift AI"
• Generated slug: building-ai-ml-workloads-openshift-ai
• site.yml title: "Building AI/ML Workloads on OpenShift AI"
• antora.yml title: "Building AI/ML Workloads on OpenShift AI"
• antora.yml lab_name: "building-ai-ml-workloads-openshift-ai"

Note: These files must be updated BEFORE Step 8 (Generate Files).

Step 4: Gather Module-Specific Details

Now for this specific module:

1. Module file name and numbering:

   • Naming convention: 0X-module-YY-<slug>.adoc (e.g., 03-module-01-pipelines-intro.adoc)
   • Title convention: = Module X: <Title> (e.g., = Module 1: Pipeline Fundamentals)
   • Files go in content/modules/ROOT/pages/
   • Number prefix: 03 for first module, 04 for second, etc. (after 01-overview, 02-details)
   • Conflict detection: If file exists, suggest next available number
   • Warning: Don't overwrite existing modules without confirmation

2. Reference materials (optional but recommended):

   • URLs to Red Hat product documentation
   • Local file paths (Markdown, AsciiDoc, text, PDF)
   • Pasted content
   • Better references = better content quality
   • If not provided: Generate from templates and common patterns

3. UserInfo variables (optional, for accurate showroom content):

   • I must ask the user:

   Q: Do you have access to a deployed environment on demo.redhat.com or integration.demo.redhat.com?
   
   If YES (RECOMMENDED - easiest and most accurate):
   Please share the UserInfo variables from your deployed service:
   
   1. Login to https://demo.redhat.com (or integration.demo.redhat.com)
   2. Go to "My services" → Your service
   3. Click "Details" tab
   4. Expand "Advanced settings" section
   5. Copy and paste the output here
   
   This provides exact variable NAMES like:
   - openshift_cluster_console_url
   - openshift_cluster_admin_username
   - gitea_console_url
   - [custom workload variables]
   
   CRITICAL: I will use these to know WHICH variables exist, NOT to replace them with actual values!
   Variables will stay as placeholders: {openshift_cluster_console_url}
   Showroom replaces these at runtime with actual deployment values.
   
   If NO:
   Q: Would you like to use placeholder attributes for now?
   
   If YES:
   I'll use placeholders: {openshift_console_url}, {user}, {password}
   You can update these later when you get Advanced settings.
   
   If NO (RHDP internal team only):
   I can extract variables from AgnosticV repository if you have it cloned locally.
   This requires AgV path and catalog name.
   Note: Less reliable than Advanced settings.
   

4. Main learning objective:

   • Example: "Create and run a CI/CD pipeline with Tekton"

5. Business scenario:

   • Auto-detect from previous module (if exists)
   • Or ask for company name (default: ACME Corp)

6. Technology/product focus:

   • Example: "OpenShift Pipelines", "Podman"

7. Number of exercises:

   • Recommended: 2-3

8. Diagrams, screenshots, or code blocks (optional):

   • Do you have diagrams, screenshots, or code examples to include?
   • If yes: Provide file paths or paste content
   • I'll save them to content/modules/ROOT/assets/images/
   • And reference them properly in AsciiDoc

9. Troubleshooting section (optional):

   Q: Would you like to include a troubleshooting section in this module?
   
   A troubleshooting section helps learners solve common issues they may encounter.
   
   Options:
   1. Yes, include troubleshooting (Recommended for production workshops)
   2. No, skip it for now (I'll add it later if needed)
   
   Your choice? [1/2]
   

   When to recommend "Yes":

   • Production-ready workshops
   • Complex technical modules with many potential failure points
   • Modules involving external dependencies (registries, APIs, networks)

   When "No" is acceptable:

   • Simple introductory modules
   • Proof-of-concept content
   • Modules with very straightforward steps

Step 5: Get UserInfo Variables (if applicable)

If UserInfo variables weren't already provided in Step 3, I'll ask for them now.

RECOMMENDED: Get from Deployed Environment (Primary Method)

I'll ask: "Do you have access to a deployed environment on demo.redhat.com or integration.demo.redhat.com?"

If YES (recommended):

Please share the UserInfo variables from your deployed service:

1. Login to https://integration.demo.redhat.com (or demo.redhat.com)
2. Go to "My services" → Find your service
3. Click on "Details" tab
4. Expand "Advanced settings" section
5. Copy and paste the output here

This shows all available variables like:

• openshift_cluster_console_url
• openshift_api_server_url
• openshift_cluster_admin_username
• openshift_cluster_admin_password
• gitea_console_url
• gitea_admin_username
• gitea_admin_password
• Custom workload-specific variables

If NO (fallback): I'll use common placeholder variables:

• {openshift_console_url}
• {openshift_api_url}
• {user}
• {password}
• {bastion_public_hostname}

Alternative: Clone collections from AgV catalog

• Read common.yaml from user-provided AgV path
• Clone collections from any repository (agnosticd, rhpds, etc.)
• Read workload roles to find agnosticd_user_info tasks
• Extract variables from data: sections
• Note: Less reliable than deployed environment output

Map to Showroom attributes:

{openshift_cluster_console_url}
{openshift_api_server_url}
{openshift_cluster_admin_username}
{gitea_console_url}
{{ custom_variable }}

CRITICAL: DO NOT Replace Variables with Actual Values:

• ALWAYS keep variables as placeholders: {openshift_console_url}
• NEVER replace with actual values like https://console-openshift-console.apps.cluster-abc123.abc123.example.opentlc.com
• Showroom will replace these at runtime with actual deployment values
• Each deployment gets different URLs - variables MUST stay dynamic
• Example in module content:

  . Navigate to the OpenShift Console at {openshift_cluster_console_url}
  . Login with username: {openshift_cluster_admin_username}
  . Password: {openshift_cluster_admin_password}
  

What UserInfo variables are for:

• Understanding WHICH variables are available
• Learning the correct variable names
• Seeing what endpoints/tools exist in the environment
• NOT for hardcoding actual values in content

Step 6: Handle Diagrams, Screenshots, and Code Blocks (if provided)

If you provided visual assets or code:

For images (diagrams, screenshots):

Path convention:

• All images go in: content/modules/ROOT/assets/images/

Required for every image:

1. Meaningful alt text (for accessibility)
2. Clickable link (link=self,window=blank - ALWAYS required)
3. Width guidance (500-800px typical)
4. Descriptive filename (no generic names like "image1.png")

AsciiDoc syntax (REQUIRED):

image::pipeline-execution-1.png[Tekton pipeline showing three tasks executing in sequence,link=self,window=blank,width=700,title="Pipeline Execution in Progress"]

CRITICAL: ALWAYS include link=self,window=blank to make images clickable. This allows learners to see full resolution without losing their place in the workshop.

Optional - Center alignment:

image::architecture-diagram.png[Architecture overview,link=self,window=blank,align="center",width=800,title="System Architecture"]

Placeholders:

• If real image doesn't exist yet: Insert placeholder and add to "Assets Needed" list
• Example placeholder:

  // TODO: Add screenshot
  image::create-task-screenshot.png[OpenShift console showing task creation form,link=self,window=blank,width=600,title="Creating a Tekton Task"]
  

Assets Needed list: At end of module, include:

== Assets Needed

. `pipeline-execution-1.png` - Screenshot of pipeline running in OpenShift console
. `task-definition.png` - YAML editor showing task definition

For code blocks:

• If you provide code snippets: Format them in AsciiDoc
• Detect language (bash, yaml, python, etc.)
• Add proper syntax highlighting:

  [source,bash]
  ----
  oc create deployment my-app --image=myimage:latest
  ----
  

Recommended image naming:

• Architecture diagrams: architecture-overview.png, deployment-flow.png
• UI screenshots: console-project-view.png, dashboard-metrics.png
• Command outputs: oc-get-pods-output.png, build-logs.png
• Step-by-step: step-1-create-task.png, step-2-run-pipeline.png

Clickable Images (Links): If an image should be clickable and link to external content, use ^ caret to open in new tab:

// Using image macro with link attribute
image::architecture-diagram.png[Architecture,600,link=https://docs.redhat.com/architecture^]

// Using link macro around image
link:https://docs.redhat.com/architecture^[image:architecture-diagram.png[Architecture,600]]

Critical: Clickable images linking to external URLs MUST use ^ caret to open in new tab, just like text links.

Step 7: Fetch and Analyze References

Based on your references, I'll:

• Fetch URLs with WebFetch
• Read local files (supports PDF)
• Extract procedures, commands, concepts
• Identify hands-on opportunities
• Combine with AgnosticV variables (if provided)
• Integrate provided code blocks and diagrams

Reference Enforcement:

• Every non-trivial claim must be backed by provided references
• If not backed by reference, mark clearly: **Reference needed**: <claim>
• Track which reference supports which section
• If references conflict:
  • Call out the conflict
  • Choose based on version relevance
  • Note the decision in module

Reference Tracking (for conclusion generation):

• Track all references used across all modules
• Store reference URLs, titles, and which modules used them
• References will be consolidated in the conclusion module, NOT in individual modules
• Each module can cite sources inline (e.g., "According to the Red Hat documentation...") but the formal References section will only appear in the conclusion

IMPORTANT: External Link Format:

• ALL external links MUST use ^ caret to open in new tab
• Format: link:https://example.com[Link Text^]
• The ^ ensures users don't lose their place in the workshop
• Internal xrefs (module navigation) should NOT use ^
• Examples:
  • External: link:https://docs.redhat.com/...[Red Hat Documentation^]
  • Internal: xref:03-module-02-next.adoc[Next Module] (no caret)

Step 8: Read Templates and Verification Criteria (BEFORE Generating)

CRITICAL: I MUST read all these files BEFORE generating content to ensure output meets all standards.

Templates to read:

• .claude/templates/workshop/templates/00-index-learner.adoc - Learner-facing index template
• .claude/templates/workshop/templates/03-module-01.adoc - Module template
• .claude/templates/workshop/example/00-index.adoc - Example index (but write for LEARNERS, not facilitators)
• .claude/templates/workshop/example/01-overview.adoc - Example overview
• .claude/templates/workshop/example/02-details.adoc - Example details
• .claude/templates/workshop/example/03-module-01.adoc - Example module

Verification criteria to read and apply DURING generation:

1. .claude/prompts/enhanced_verification_workshop.txt - Complete quality checklist
2. .claude/prompts/redhat_style_guide_validation.txt - Red Hat style rules
3. .claude/prompts/verify_workshop_structure.txt - Structure requirements
4. .claude/prompts/verify_technical_accuracy_workshop.txt - Technical accuracy standards
5. .claude/prompts/verify_accessibility_compliance_workshop.txt - Accessibility requirements
6. .claude/prompts/verify_content_quality.txt - Content quality standards

How I use these:

• Read ALL verification prompts BEFORE generating
• Apply criteria WHILE generating content
• Generate content that ALREADY passes all checks
• No separate validation step needed - content is validated during creation

Step 9: Generate Files (Using Verification Criteria)

IMPORTANT: Use Reference Repository from Step 0

Before generating ANY content, refer back to the reference repository examples from Step 0:

1. Read reference examples again if needed to refresh patterns
2. Match structure and style from real Showroom modules
3. Apply learned patterns to new content:
   • Section structure matches reference examples
   • Code block formatting follows reference style
   • Image references use same patterns (link=self,window=blank)
   • List formatting matches reference (blank lines before/after)
   • External links follow reference pattern (^ caret for new tabs)
   • Business scenario integration follows reference approach

This ensures generated content matches real Showroom quality instead of generic templates.

CRITICAL: If this is the FIRST module of a NEW lab, generate files in this order:

Step 9.1: Generate index.adoc (First Module Only)

Purpose: Learner-facing landing page - NOT a facilitator guide

Content:

= {{ Workshop Title }}

Welcome to the {{ workshop name }} workshop!

== What you'll learn

In this workshop, you will:

* {{ Learning objective 1 }}
* {{ Learning objective 2 }}
* {{ Learning objective 3 }}
* {{ Learning objective 4 }}

== Who this is for

This workshop is designed for {{ target audience }} who want to {{ main goal }}.

== Prerequisites

Before starting this workshop, you should have:

* {{ Prerequisite 1 }}
* {{ Prerequisite 2 }}
* Access to {{ environment/tools }}

== Workshop environment

{{ Brief description of the lab environment }}

* OpenShift cluster: {openshift_console_url}
* Login credentials will be provided

== Let's get started!

Click on the next section to begin the workshop.

What NOT to do:

• ❌ Don't copy facilitator guide template from workshop/templates/00-index.adoc
• ❌ Don't include facilitator instructions
• ❌ Don't write "This guide helps workshop facilitators..."

What TO do:

• ✅ Write for LEARNERS, not facilitators
• ✅ Simple welcome and what they'll learn
• ✅ Prerequisites and environment info
• ✅ Encouragement to get started

Step 9.2: Generate 01-overview.adoc (First Module Only)

Purpose: Business scenario and learning objectives

Content: See workshop/example/01-overview.adoc for pattern

• Business scenario/story
• Detailed learning objectives
• Expected outcomes
• Estimated time

Step 9.3: Generate 02-details.adoc (First Module Only)

Purpose: Technical requirements and setup

Content: See workshop/example/02-details.adoc for pattern

• Module timing breakdown
• Technical requirements
• Environment details
• Authors/contact

Step 9.4: Generate 03-module-01-*.adoc (Always)

I'll create a complete module with:

CRITICAL: Image Syntax Enforcement: When generating ANY image reference in the module content, you MUST include link=self,window=blank:

✅ CORRECT - Always use this format:

image::filename.png[Description,link=self,window=blank,width=700]
image::pipeline-view.png[Pipeline Execution,link=self,window=blank,width=700,title="Pipeline Running"]

❌ WRONG - Never generate images without link parameter:

image::filename.png[Description,width=700]
image::pipeline-view.png[Pipeline Execution,width=700]

Why: This makes images clickable to open full-size in new tab, preventing learners from losing their place in the workshop.

CRITICAL: AsciiDoc List Formatting Enforcement: When generating ANY list in the module content, you MUST include blank lines before and after the list:

✅ CORRECT - Always use proper spacing:

**Learning objectives:**

* Understand how Tekton tasks work
* Create and execute pipelines
* Troubleshoot failed runs

By the end of this module...

❌ WRONG - Text runs together when rendered:

**Learning objectives:**
* Understand how Tekton tasks work
* Create and execute pipelines
* Troubleshoot failed runs
By the end of this module...

Required blank lines:

1. Blank line after bold heading (**Text:**) or colon (:)
2. Blank line before first list item
3. Blank line after last list item (before next content)

Why: Without blank lines, Showroom renders lists as plain text, causing content to run together and become unreadable.

CRITICAL: Content Originality - No Plagiarism: All generated content MUST be original. Never copy from external sources without proper attribution.

✅ CORRECT - Original with attribution:

According to link:https://kubernetes.io/docs/...[Kubernetes documentation^],
Kubernetes is "an open-source system for automating deployment." Red Hat OpenShift
extends Kubernetes with enterprise features including integrated CI/CD and security.

❌ WRONG - Copied without attribution:

Kubernetes is an open-source system for automating deployment, scaling,
and management of containerized applications.

Prohibited:

• Copying documentation verbatim from external sources
• Slightly rewording existing tutorials
• Presenting others' examples as original work

Required:

• Write original explanations
• Add Red Hat-specific context
• Use proper attribution with quotes and links

CRITICAL: No Em Dashes: Never use em dashes (—). Use commas, periods, or en dashes (–) instead.

✅ CORRECT:

OpenShift, Red Hat's platform, simplifies deployments.
The process is simple. Just follow these steps.
2020–2025 (en dash for ranges)

❌ WRONG - Em dash used:

OpenShift—Red Hat's platform—simplifies deployments.
The process is simple—just follow these steps.

Why: Follows Red Hat Corporate Style Guide and improves readability.

CRITICAL: External Links Must Open in New Tab: All external links MUST use ^ caret to open in new tab, preventing learners from losing their place.

✅ CORRECT - External links with caret:

According to link:https://docs.redhat.com/...[Red Hat Documentation^], OpenShift provides...
See the link:https://www.redhat.com/guides[Getting Started Guide^] for more details.

❌ WRONG - Missing caret:

According to link:https://docs.redhat.com/...[Red Hat Documentation], OpenShift provides...
See the link:https://www.redhat.com/guides[Getting Started Guide] for more details.

Internal links (NO caret):

✅ CORRECT - Internal navigation without caret:
Navigate to xref:04-module-02.adoc[Next Module] to continue.
See xref:02-details.adoc#prerequisites[Prerequisites] section.

Why: External links without caret replace current tab, causing learners to lose their place in the workshop. Internal xrefs should NOT use caret to keep flow within the workshop.

CRITICAL: Bullets vs Numbers - Knowledge vs Tasks: Knowledge/information sections use bullets (*). Task/step sections use numbers (.).

✅ CORRECT - Bullets for knowledge, numbers for tasks:

== Learning Objectives

By the end of this module, you will understand:

* How Tekton tasks encapsulate CI/CD steps
* The relationship between tasks and pipelines
* Best practices for pipeline design

== Exercise 1: Create Your First Pipeline

Follow these steps:

. Open the OpenShift Console at {openshift_console_url}
. Navigate to Pipelines → Create Pipeline
. Enter the pipeline name: my-first-pipeline
. Add a task from the catalog
. Click Create

=== Verify

Check that your pipeline was created successfully:

* Pipeline appears in the list
* Status shows "Not started"
* All tasks are configured correctly

❌ WRONG - Mixed up bullets and numbers:

== Exercise 1: Create Your First Pipeline

Follow these steps:

* Open the OpenShift Console  ← WRONG (should be numbers)
* Navigate to Pipelines
* Click Create

=== Verify

. Pipeline appears in the list  ← WRONG (should be bullets)
. Status shows "Not started"

Rule:

• Learning objectives → Use bullets (*) for concepts to understand
• Exercise steps → Use numbers (.) for sequential actions
• Verification → Use bullets (*) for success indicators
• Prerequisites → Use bullets (*) for requirements list
• Benefits/features → Use bullets (*) for information points

Why: Bullets indicate information to absorb; numbers indicate sequential actions to perform.

Required Structure:

• Learning objectives (3-4 items)
• Business introduction with scenario
• 2-3 progressive exercises
• Step-by-step instructions with commands
• Verification checkpoints (REQUIRED - see below)
• Image placeholders
• Troubleshooting section (OPTIONAL - if user requested in Step 3, see below)
• Learning outcomes checkpoint (REQUIRED - see below)
• Module summary

Note: References are NOT included in individual modules. All references will be consolidated in the mandatory conclusion module.

Mandatory: Verification Checkpoints: Each major step must include:

=== Verify

Run the following to confirm success:

[source,bash]
----
oc get pods
----

Expected output:
----
NAME                     READY   STATUS    RESTARTS   AGE
my-app-xxxxx-xxxxx      1/1     Running   0          2m
----

✓ Pod status is "Running"
✓ READY shows 1/1

Optional: Troubleshooting Section (If Requested): If the user requested troubleshooting in Step 3, include this section:

== Troubleshooting

**Issue**: Pod stuck in "ImagePullBackOff"
**Solution**:
. Check image name: `oc describe pod <pod-name>`
. Verify registry credentials
. Common fix: `oc set image-lookup <deployment>`

**Issue**: Permission denied errors
**Solution**:
. Verify you're in correct project: `oc project`
. Check RBAC: `oc whoami` and `oc auth can-i create pods`

**Issue**: Command not found
**Solution**:
. Verify OpenShift CLI installed: `oc version`
. Expected version: {ocp_version}

Guidelines for troubleshooting section:

• Include 3-5 common issues specific to the module's technology
• Provide clear, actionable solutions
• Use real commands and expected outputs
• Tailor scenarios to the module's exercises
• If user declined troubleshooting, skip this section entirely

Mandatory: Learning Outcomes Checkpoint: Every module must include a learning confirmation (not just technical validation):

== Learning Outcomes

By completing this module, you should now understand:

* ✓ How Tekton tasks encapsulate reusable CI/CD steps
* ✓ The relationship between tasks, pipelines, and pipeline runs
* ✓ How to troubleshoot failed pipeline executions using logs and status
* ✓ When to use sequential vs parallel task execution patterns

Guidelines:

• 3-5 bullet outcomes tied to original learning objective
• Focus on understanding ("understand how X works") not just doing ("created X")
• Use outcomes later for blog transformation
• Helps reviewers, instructors, and people skimming modules

Optional but Recommended: Cleanup: If module changes shared state:

== Cleanup (Optional)

To reset your environment:

[source,bash]
----
oc delete project my-project
----

Quality:

• Valid AsciiDoc syntax
• Proper Red Hat product names
• Sentence case headlines
• Second-person narrative
• Code blocks with syntax highlighting

Step 10: Final Quality Check

Since verification criteria were applied during generation (Step 7-8), the module should already meet all standards.

Quick final checks:

1. AsciiDoc Syntax:

   • ✓ All code blocks have proper syntax: [source,bash]
   • ✓ No broken includes
   • ✓ All attributes defined
   • ✓ External links use ^ caret to open in new tab

2. Completeness:

   • ✓ All required sections present (see Step 8)
   • ✓ Verification checkpoints after major ste

…(truncated)