tutorial-run

name	tutorial-run
trigger	/hyper-tutorial-run
description	Interactively walks the user through a tutorial folder generated by /hyper-tutorial-generator. Reads tutorial.md section by section, answers questions in context, and surfaces linked code samples and output files on demand.

Tutorial Run

This skill reads any tutorial produced by /hyper-tutorial-generator and walks the user through it interactively — one section at a time, with in-context Q&A and on-demand access to code samples and supporting files.

---

When to use this skill

• When the user runs /hyper-tutorial-run and wants to work through an existing tutorial.
• When the user wants an interactive guided read (not a plain file open) of a tutorials/<name>/ folder.

---

How to use it

Step 0 — Choose a tutorial (HITL Gate #1)

List all subdirectories of tutorials/ (numbered). If the directory does not exist or is empty, inform the user and suggest running /hyper-tutorial-generator first.

Use AskUserQuestion to let the user select which tutorial to run. Wait for the selection before proceeding.

---

Step 1 — Load the tutorial

1. Read tutorials/<name>/tutorial.md in full.
2. Extract the section headings to build a section list (use ## or ### level headings).
3. Scan for available supporting subdirectories and note what's present:
   • code_samples/ — runnable code examples
   • output_files/ — expected outputs
   • architecture_evolution/ — diagrams and comparison tables
   • input_files/ — setup or example input files
4. Display a brief ready message:

Ready to begin: <Tutorial Title>
Sections: N
Supporting files: code_samples/ (X files), output_files/ (Y files)

Let's start with Section 1.

---

Step 2 — Walk through sections (iterative HITL loop)

For each section in the tutorial:

1. Present the full section content as plain text (render markdown headers and lists).

2. Offer options via AskUserQuestion:

   Section <N>/<Total>: <Section Title>
   
   Options:
   - Option A: Next section
   - Option B: I have a question about this section
   - Option C: Show me the code sample referenced in this section
   

   Only show Option C if the section references a file in code_samples/.

3. Handle each response:

   • Option A — move to the next section. If this was the last section, go to Step 3.
   • Option B — answer the question using the tutorial content and your knowledge of the project. Do not move forward. Re-present the same section prompt after answering.
   • Option C — identify the referenced code_samples/ file from the section text, read it in full, and display it. Then re-present the same section prompt.

---

Step 3 — Finish

After the last section, use AskUserQuestion:

You've reached the end of "<Tutorial Title>".

Options:
- Option A: Run the verification command from the tutorial
- Option B: Open a supporting file (output_files/, architecture_evolution/, etc.)
- Option C: Done — end this session

• Option A — display the verification command from the tutorial's "Expected Output" or "Verify it" section. Do not run it automatically; show it and tell the user to run it in their terminal.
• Option B — list available supporting files and use AskUserQuestion to let the user pick one to read.
• Option C — close with: "Tutorial complete. You can re-run it anytime with /hyper-tutorial-run."

---

Constraints

• Never skip a section — always present sections in order.
• Never run commands automatically — display verification commands for the user to copy-paste.
• Always use AskUserQuestion at every gate — do not advance without user input.
• Do not modify tutorial files — this skill is read-only.