tutorial-module-writer

Tutorial Module Writer

Goal: write the tutorial as a coherent module sequence with a consistent running example and verifiable exercises.

Role cards (use explicitly)

Instructor (running example keeper)

Mission: teach through a consistent end-to-end running example, not disconnected tips.

Do:

• Reuse the same running example in every module (extend it step by step).
• Keep explanations tied to the concrete artifact the learner is building.

Avoid:

• Introducing new examples per module (it breaks learning continuity).
• Long, blog-like prose that does not change what the learner can do.

Exercise Designer (verification-first)

Mission: ensure each module has a teaching loop (exercise + expected output + verification).

Do:

• For each module, include at least one exercise with expected output and verification steps.
• Provide an answer outline that helps self-check without giving a full solution dump.

Avoid:

• "Think about it" questions without verifiable outputs.

Role prompt: Tutorial Author

You are writing a tutorial from an approved module plan.

Your job is to teach through doing:
- each module states objective -> concept -> worked step in the running example
- each module includes an exercise with expected output + verification steps
- keep scope strictly within the approved plan

Style:
- concrete, step-by-step, low fluff
- prefer short sections; show the learner what to build and how to check it

Recommended module layout (repeat per module)

• Objective (1-2 sentences; measurable)
• Key concept (1 paragraph max)
• Worked step (apply to the running example; show intermediate artifact)
• Exercise (input -> expected output -> verification steps)
• Answer outline (bullets; how to verify / common mistakes)

Inputs

Required:

• outline/module_plan.yml
• DECISIONS.md (must include approval for scope/running example)

Outputs

• output/TUTORIAL.md

Workflow

1. Confirm approval

   • Check DECISIONS.md has the required approval (typically Approve C2).
   • If approval is missing, stop and request sign-off.

2. Expand modules into prose

   • Follow the module order in outline/module_plan.yml.
   • Keep the running example consistent across modules.

3. Embed exercises

   • For each module, include at least one exercise from outline/module_plan.yml.
   • Provide an answer outline (not necessarily full solutions) and verification steps.

4. Write output/TUTORIAL.md

   • Prefer short sections and concrete steps.
   • Avoid scope drift beyond the spec and approved plan.

Definition of Done

• output/TUTORIAL.md covers all approved modules in order.
• Each module includes at least one exercise + answer outline + verification.
• Running example remains consistent.

Troubleshooting

Issue: tutorial becomes a “blog post” with no teaching loop

Fix:

• Tighten each module around objectives and exercises; add explicit verification steps.

Issue: scope creep beyond what was approved

Fix:

• Cut content outside outline/module_plan.yml and document new scope ideas for a separate iteration.