Validate Training Materials

Run comprehensive validation checks on training materials. Execute from repository root.

See ../shared/repo-conventions.md for directory mapping and file conventions.

Skill Dependencies (MANDATORY)

This skill MUST invoke other skills during validation. Do not skip these.

Task	Skill	When
Check code block highlights	/check-highlights	Always
Check inline code formatting	/check-inline-code	Always

Scope

Ask user to specify what to validate if not clear:

• Specific side quest (e.g., “debugging”)
• Specific module (e.g., “hello_nextflow”)
• Entire repository (only if explicitly requested)

Determining Scope

Based on the user’s request, determine the scope:

1. Specific side quest (e.g., “debugging”):

   • Documentation file: docs/side_quests/{name}.md
   • Example scripts: side-quests/{name}/**/*.nf
   • Solution files: side-quests/solutions/{name}/**/*.nf

2. Specific module (e.g., “hello_nextflow”):

   • Documentation files: docs/{module}/**/*.md
   • Example scripts: {module}/**/*.nf or hello-nextflow/**/*.nf
   • Solution files: {module}/solutions/**/*.nf

3. Entire repository (only if explicitly requested):

   • All files: docs/**/*.md, **/*.nf

Tasks to Perform

Perform the following checks only on files within the determined scope:

1. Check Heading Numbering

   • Run: uv run .github/check_headings.py [scoped-path]/**/*.md
   • Report any heading numbering issues found
   • If errors exist, ask if user wants to auto-fix with --fix flag

2. Find TODO/FIXME Comments

   • Search markdown files in scope
   • Search Nextflow scripts in scope
   • Categorize by priority (high, medium, low)
   • Report files with most TODOs

3. Check Nextflow Script Conventions

   • Find .nf files in scope
   • Verify they start with #!/usr/bin/env nextflow
   • Check for DSL2 syntax
   • Report any that don’t follow conventions

4. Find Orphaned Files

   • Check if main documentation file is referenced in docs/en/mkdocs.yml
   • Look for solution files without corresponding exercise documentation
   • Report any orphaned files within scope

5. Verify Admonition Syntax

   • Search for common admonition formatting errors in scoped files
   • Check for proper indentation (4 spaces)
   • Report any malformed admonitions

6. Check Code Block Highlights

   >>> STOP. INVOKE /check-highlights on the scoped files NOW.
   
   Record results before continuing.

7. Check Inline Code Formatting

   >>> STOP. INVOKE /check-inline-code on the scoped files NOW.
   
   Record results before continuing.

8. Check Writing Style

   • Search for LLM-style patterns that should be avoided:
     • Remember when or Remember that callbacks
     • Don't worry reassurances
     • Exclamation marks used for emphasis (not in code/output)
   • Check for em-dash elaborations (space-hyphen-space followed by lowercase) that could be periods
   • Flag any issues found for manual review
   • Do NOT flag: Let's / let's, worth mentioning, or important to note — these are acceptable in tutorial prose

9. Deep Lesson Review (when reviewing a specific lesson file)

   If the user asks to review a specific lesson, use the checklist in references/deep-review-checklist.md.

Output Format

Structure your report with these sections:

# Validation Report

## Heading Numbering
## TODO/FIXME Comments (count by priority, list top files)
## Nextflow Scripts (conventions check)
## Orphaned Files
## Admonitions
## Code Block Highlights (from /check-highlights)
## Inline Code Formatting (from /check-inline-code)
## Writing Style
## Summary

For deep lesson reviews, add sections for: Structure, Formatting, Content Accuracy, Teaching Effectiveness, Cross-References, Examples & Code, Writing Style, Overall Assessment, Positive Aspects.

Important: Always provide actionable next steps for any issues found. If no issues found, give clear confirmation.