validate-training-materials

# Validate Training Materials Run comprehensive validation checks on training materials. Execute from repository root. See [../shared/repo-conventions.md](../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](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.