Walk through a training tutorial as a user would, progressively building examples exactly as instructed, running all commands, and verifying results against solutions. Use when testing tutorials end-to-end or validating that instructions are correct and complete.
Walk through a training tutorial lesson as a learner would, progressively building code, running commands, and verifying the learning journey works end-to-end.
This skill supports two distinct modes. Ask the user which mode if not clear from context:
Walk through as a learner would, editing starter files progressively. Use when:
Run solution files and verify documentation matches actual outputs. Use when:
Key difference: In Mode A, you progressively edit starter files (then reset). In Mode B, you run solutions directly and check docs for accuracy.
Starter files (e.g., hello-nextflow/hello-config.nf) represent the end state of the previous chapter. They are the starting point for learners beginning a new lesson.
| Scenario | Action |
|---|---|
| Bug or syntax error inherited from previous chapter | ✅ Fix and commit |
| Changes made while running through exercises | ❌ Reset before committing |
If you modified starter files while walking through exercises, reset them:
git checkout hello-nextflow/*.nf
Only keep changes to:
solutions/**/*) - these should be correct and completedocs/**/*.md) - fix code snippets, outputs, examplesThis walkthrough MUST invoke other skills. Do not skip these.
| Checkpoint | Skill | Condition |
|---|---|---|
| Before Phase 2 | /docker-setup | If Docker environment selected |
| Before Phase 2 | /validate | Always - check lesson structure first |
| Phase 3 | /test-example | For each solution file |
Use AskUserQuestion to determine:
If Docker selected:
>>> STOP. INVOKE /docker-setup NOW.
Do not proceed until the container is confirmed running.
If existing environment: Verify Nextflow is installed with nextflow -version
Always use the strict syntax parser when running Nextflow commands:
NXF_SYNTAX_PARSER=v2 nextflow run ...
In Docker:
docker exec -e NXF_SYNTAX_PARSER=v2 nf-training nextflow run ...
This validates tutorials against the strict syntax that will become default in future Nextflow versions.
See ../shared/repo-conventions.md for full directory mapping table.
Key pattern: documentation uses underscores (hello_nextflow), working directories use hyphens (hello-nextflow).
When verifying documentation (especially in Mode B), watch for these frequent problems:
.process instead of .nameparams.greeting vs params.input'file.csv' vs 'data/file.csv'nextflow config output examples must match what the config actually producesWhile your actual hashes will differ from documented ones, check that docs are internally consistent:
[j6/abc123] contain invalid characters (only 0-9, a-f allowed)nextflow run commands showing identical hashes (unless cached)hl_lines highlight the correct lines (count from line 1 of snippet, not linenums)Use TodoWrite to track progress through phases and sections.
>>> STOP. INVOKE /validate on the lesson file NOW.
Record any issues found. Do not proceed to Phase 2 until validation completes.
Complete steps 2.1-2.6 for each section before moving to the next. Do not batch sections together.
For each numbered section in the lesson:
Before applying any code change:
Edit tool to make incremental changes, mimicking how a learner would typeBash toolBefore moving to the next section:
TodoWrite to mark section completeFor documentation verification mode, skip progressive editing of starter files. Instead:
nextflow run solutions/<lesson>/script.nf -c solutions/<lesson>/nextflow.config
nextflow run solutions/<lesson>/script.nf -c solutions/<lesson>/nextflow.config -profile test
nextflow run solutions/<lesson>/script.nf -c solutions/<lesson>/nextflow.config -profile my_laptop,test
nextflow config -profile <profiles>
Compare output against documented nextflow config examples in the lesson.
For each documented output block:
Run these checks on ALL documentation files in scope:
# 1. Check for invalid hex characters in hashes
grep -oE '\[[^]]+\]' docs/path/to/*.md | grep -E '\[[^0-9a-f/\]]' | head -20
# 2. Find duplicate hashes (may indicate copy-paste errors)
grep -oE '\[[a-z0-9]{2}/[a-z0-9]{6}\]' docs/path/to/*.md | sort | uniq -c | sort -rn | head -20
For any duplicates found, verify they are legitimate:
-resume showing cached results from earlier in same lesson (acceptable)nextflow run commands without -resume (NOT acceptable - flag as issue)See references/acceptable-differences.md for detailed hash validation rules.
After completing all sections:
Read the solution file and compare with what was built. Minor differences (whitespace, comments) may be acceptable. Report any significant differences.
>>> STOP. INVOKE /test-example on each solution file.
For each solution script, verify:
- Fresh run works
- Resume caches correctly
- Parameter handling (if applicable)
- Output matches documentation
Record results before proceeding.
Only if walkthrough succeeded with no issues:
git checkout "${WORKING_DIR}/"If issues found: Leave files in place for Phase 4. Save work directory paths for troubleshooting.
If fixable issues were identified, follow references/pr-workflow.md to create a PR.
Key points:
AskUserQuestion before making changesStructure your report with these sections:
# Tutorial Walkthrough: <lesson-name>
## Environment
Mode, Nextflow version, working directory
## Section N: <exact title from document>
- State verification: matches "Before" ✓ or mismatch details
- Code changes applied
- Commands run with results
## Validation Results (from /validate)
## Solution Tests (from /test-example)
## Solution Comparison
## Summary
Sections completed, mismatches, failures, discrepancies
## Issues Found
Categorize as Critical / Warning / Minor
## Proposed Fixes (if any)
Table with file, line, current, proposed, reason
# Documentation Verification: <module-name>
## Environment
Container name, Nextflow version, working directory
## Solutions Tested
| Solution | Base Run | With Profiles | Issues |
|----------|----------|---------------|--------|
| 1-hello-world | ✓ | N/A | None |
| 6-hello-config | ✓ | ✓ test | Fixed: .process→.name |
## Hash Consistency Check
- Invalid hex characters found: [list or "None"]
- Duplicate hashes across different runs: [list or "None - all legitimate"]
- Prose/output mismatches: [list or "None"]
## Documentation Issues Found
### Critical (breaks functionality)
- File: `06_hello_config.md`, Lines 893-931
- Issue: `.process` property doesn't exist, should be `.name`
- Also affects: `solutions/6-hello-config/hello-config.nf`
### Minor (cosmetic/clarity)
- ...
## Fixes Applied
| File | Change | Reason |
|------|--------|--------|
| docs/.../06_hello_config.md | `.process` → `.name` | Property doesn't exist |
| solutions/.../nextflow.config | `params.greeting` → `params.input` | Wrong parameter name |
| docs/.../03_config.md | `[f0/35723c]` → `[2b/9a7d1e]` | Duplicate hash for different run |
When encountering ??? exercise blocks:
??? solution blockSome tutorials have optional paths: