Validate Training Materials

Run comprehensive validation checks on training materials to ensure quality and consistency. This includes both automated checks and deep lesson reviews.

User Input

IMPORTANT: Ask the user to specify what to validate if not clear from the request:

• A specific side quest (e.g., "debugging", "metadata")
• A specific module (e.g., "hello_nextflow", "nf4_science/genomics")
• The entire repository (only if explicitly requested)

If the user provides a path or module name, only validate that specific content.

Working Directory

IMPORTANT: All commands in this skill must be executed from the repository root directory.

• The repository root is the directory containing mkdocs.yml, docs/, and .github/
• Verify you are in the correct directory before running any commands (check for these files/folders)
• All file paths in this skill are relative to the repository root
• Do not change directories during skill execution
• Use paths relative to repository root only

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 nf-training/**/*.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 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. Deep Lesson Review (when reviewing a specific lesson file)

   If the user asks to review a specific lesson, perform this comprehensive checklist:

   a. Structure Check:

   • Proper heading numbering with trailing periods
   • Heading levels match numbering depth (## for 1., ### for 1.1.)
   • Each major section has "### Takeaway"
   • Each major section has "### What's next?"
   • Logical flow from simple to complex
   • Clear learning objectives stated or implied

   b. Formatting Check:

   • Code blocks have proper titles, line numbers, and highlighting
   • Console output properly formatted with console title="Output"
   • File paths use proper markdown formatting
   • Before/After comparisons use tabbed blocks
   • Admonitions properly formatted and indented
   • Each sentence on new line (for clean diffs)

   c. Content Check:

   • Technical accuracy of Nextflow code
   • Commands are correct and runnable
   • Parameter syntax correct (-- for pipeline, - for Nextflow)
   • Examples progress logically
   • Common pitfalls addressed
   • Edge cases explained

   d. Teaching Effectiveness:

   • Clear explanations for beginners
   • Concepts introduced before use
   • Examples are relevant and motivating
   • Exercises appropriate for skill level
   • Solutions available for exercises
   • Good use of tips and warnings

   e. Cross-References:

   • Links to related lessons work
   • References to files/scripts are correct
   • External links are valid
   • Prerequisites clearly stated

   f. Examples & Code:

   • All Nextflow examples are syntactically correct
   • Variable names are clear and consistent
   • Comments explain non-obvious code
   • Examples can be run as shown
   • Output examples match what code produces

Output Format

Provide a structured report. For automated validation checks:

# Validation Report

## Heading Numbering
✓ All headings correctly numbered
[or list of issues with file:line]

## TODO/FIXME Comments
Found 15 total:
- High priority: 3
- Documentation: 8
- Code: 4

Top files:
- docs/side_quests/debugging.md (5 items)
- ...

## Nextflow Scripts
✓ All 23 scripts follow conventions
[or list of non-compliant scripts]

## Orphaned Files
Found 2 orphaned markdown files:
- docs/old/deprecated.md
- ...

## Admonitions
✓ All admonitions properly formatted
[or list of issues]

## Summary
[Overall assessment and recommended actions]

For deep lesson reviews, add:

## Lesson Review: [lesson-name]

### Structure
[Assessment of structure with specific issues/successes]

### Formatting
[Assessment of formatting with specific issues/successes]

### Content Accuracy
[Assessment of technical content]

### Teaching Effectiveness
[Assessment of pedagogical quality]

### Cross-References
[Assessment of links and references]

### Examples & Code
[Assessment of code quality]

### Overall Assessment
[Summary with severity-organized issues and recommendations]

### Positive Aspects
[Things worth preserving]

Notes

• Use Grep and Glob tools for efficient searching
• Run heading check script directly via Bash
• Provide actionable next steps for any issues found
• If no issues found, give clear confirmation