run-tutorial-walkthrough by nextflow-io

---
name: Run Tutorial Walkthrough
description: 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.
---

# Run Tutorial Walkthrough

Walk through a training tutorial lesson as a learner would, progressively building code, running commands, and verifying the learning journey works end-to-end.

---

## Operating Modes

This skill supports two distinct modes. **Ask the user which mode** if not clear from context:

### Mode A: Learner Simulation (Progressive Build)

Walk through as a learner would, editing starter files progressively. Use when:

- Testing that tutorial instructions are complete and correct
- Verifying the learning path works step-by-step

### Mode B: Documentation Verification

Run solution files and verify documentation matches actual outputs. Use when:

- Checking that code snippets, terminal outputs, and examples in docs are accurate
- Validating solution files work correctly

**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

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.

### When to Edit Starter Files

| Scenario                                           | Action                  |
| -------------------------------------------------- | ----------------------- |
| Bug or syntax error inherited from previous chapter | ✅ Fix and commit        |
| Changes made while running through exercises       | ❌ Reset before committing |

### After Testing

If you modified starter files while walking through exercises, reset them:

```bash
git checkout hello-nextflow/*.nf
```

Only keep changes to:

- **Solution files** (`solutions/**/*`) - these should be correct and complete
- **Documentation** (`docs/**/*.md`) - fix code snippets, outputs, examples
- **Starter files with genuine bugs** - errors that exist before the lesson begins

---

## Skill Dependencies (MANDATORY)

This 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 |

---

## Initial Setup

Use `AskUserQuestion` to determine:

1. **Which tutorial/lesson** to walk through (specific file, module, or side quest)
2. **Environment**: Docker (recommended) or existing local environment

### Environment Setup

**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`

### Strict Syntax Parser (v2)

**Always use the strict syntax parser** when running Nextflow commands:

```bash
NXF_SYNTAX_PARSER=v2 nextflow run ...
```

In Docker:

```bash
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.

---

## Working Directory Mapping

See [../shared/repo-conventions.md](../shared/repo-conventions.md) for full directory mapping table.

Key pattern: documentation uses underscores (`hello_nextflow`), working directories use hyphens (`hello-nextflow`).

---

## Common Documentation Issues

When verifying documentation (especially in Mode B), watch for these frequent problems:

### Code Snippets

- **Non-existent properties/methods**: e.g., `.process` instead of `.name`
- **Parameter name mismatches**: e.g., `params.greeting` vs `params.input`
- **Missing path prefixes**: e.g., `'file.csv'` vs `'data/file.csv'`

### Configuration Examples

- **Profile parameter names** must match the actual params block
- **`nextflow config` output examples** must match what the config actually produces
- **Path values** in test profiles must be valid relative to the working directory

### Terminal Output Examples

- Version numbers (acceptable to differ from your run)
- Work directory hashes (acceptable to differ from your run)
- Process execution order (acceptable to differ)
- **Error messages** (must match if showing expected errors)

### Work Directory Hashes (within docs - CRITICAL)

While your actual hashes will differ from documented ones, check that docs are internally consistent:

- **Invalid hex**: Hashes like `[j6/abc123]` contain invalid characters (only 0-9, a-f allowed)
- **Copy-paste duplicates**: Multiple different `nextflow run` commands showing identical hashes (unless cached)
- **Prose mismatch**: Text referencing a hash that doesn't appear in nearby output
- **Cache confusion**: Non-cached processes (no "cached: N") should have unique hashes per run

### Before/After Code Blocks

- Verify "Before" matches the actual prior state
- Verify "After" produces working code
- Check that `hl_lines` highlight the correct lines (count from line 1 of snippet, not `linenums`)

---

## Walkthrough Process

Use `TodoWrite` to track progress through phases and sections.

### Phase 1: Preparation

1. **Read the lesson file** to understand the structure and sections
2. **Identify starting files** - What files should already exist vs. what the user creates
3. **Prepare a clean working state** - Reset or backup existing files to avoid conflicts
4. **Verify prerequisites** - Check that required data files and configs exist

#### CHECKPOINT: Validate Before Proceeding

```
>>> STOP. INVOKE /validate on the lesson file NOW.

Record any issues found. Do not proceed to Phase 2 until validation completes.
```

### Phase 2: Progressive Execution

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:

#### 2.1 Read and Understand

- Read the section instructions
- Identify what code changes are expected (Before/After blocks, inline snippets)
- Note what commands should be run

#### 2.2 Verify Current State Matches "Before"

Before applying any code change:

1. Read the current file content
2. Compare with the "Before" block in the documentation
3. If they don't match, stop and report the discrepancy

#### 2.3 Apply Code Changes Progressively

- **Don't copy the final solution** - Apply only the changes shown in this section
- Use the `Edit` tool to make incremental changes, mimicking how a learner would type
- If creating a new file, use the exact content shown at that point (not the final version)

#### 2.4 Run Commands Exactly As Shown

- Execute bash commands in the order they appear using the `Bash` tool
- Use the exact syntax shown (don't "improve" or modify commands)
- Capture output for comparison
- **If a section changes code but doesn't include a "run this" instruction, run the workflow anyway** to verify changes work

#### 2.5 Verify Outputs

- Compare console output with documented "Output" blocks
- See [references/acceptable-differences.md](references/acceptable-differences.md) for what to flag vs. ignore

#### 2.6 Confirm Section Complete

Before moving to the next section:

1. Verify the workflow/script ran successfully (exit code 0)
2. Confirm output matches documentation (within acceptable differences)
3. Update `TodoWrite` to mark section complete

### Phase 2B: Solution Testing (Mode B only)

For documentation verification mode, skip progressive editing of starter files. Instead:

#### 2B.1 Run Each Solution Directly

```bash
nextflow run solutions/<lesson>/script.nf -c solutions/<lesson>/nextflow.config
```

#### 2B.2 Test with Profiles (if applicable)

```bash
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
```

#### 2B.3 Verify Config Resolution

```bash
nextflow config -profile <profiles>
```

Compare output against documented `nextflow config` examples in the lesson.

#### 2B.4 Compare All Outputs Against Documentation

For each documented output block:

1. Find the corresponding section in the docs
2. Run the command/workflow
3. Compare actual vs documented output
4. Flag discrepancies (use acceptable-differences.md to filter noise)

#### 2B.5 Verify Hash Consistency (MANDATORY)

Run these checks on ALL documentation files in scope:

```bash
# 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:
- Same output shown twice (acceptable)
- `-resume` showing cached results from earlier in same lesson (acceptable)
- Prose reference to nearby terminal output (acceptable)
- Different `nextflow run` commands without `-resume` (NOT acceptable - flag as issue)

See [references/acceptable-differences.md](references/acceptable-differences.md) for detailed hash validation rules.

### Phase 3: Final Verification

After completing all sections:

#### 3.1 Compare Final Code with Solutions

Read the solution file and compare with what was built. Minor differences (whitespace, comments) may be acceptable. Report any significant differences.

#### 3.2 Test Solution Files

```
>>> 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.
```

#### 3.3 Cleanup

**Only if walkthrough succeeded with no issues:**

- Reset modified files: `git checkout "${WORKING_DIR}/"`
- Remove work directories and logs

**If issues found:** Leave files in place for Phase 4. Save work directory paths for troubleshooting.

### Phase 4: Propose Fixes and Create PR (if issues found)

If fixable issues were identified, follow [references/pr-workflow.md](references/pr-workflow.md) to create a PR.

Key points:
- Categorize as auto-fixable vs. requires review
- Present fixes to user with **actual section headings** (read from document - do not guess!)
- Get user approval via `AskUserQuestion` before making changes

---

## Output Format

Structure 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
```

### Mode B Output Format

```
# 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 |
```

---

## Special Cases

### Exercises

When encountering `??? exercise` blocks:

1. Attempt the exercise based on instructions given
2. Check against `??? solution` block
3. Report if instructions are unclear or incomplete

### Branching/Optional Steps

Some tutorials have optional paths:

- Note which path was taken
- Ask user if they want to test alternative paths
- Document any untested branches