Tutorial Spec

Goal: define an executable tutorial scope so downstream planning can be deterministic.

Role cards (use explicitly)

Curriculum Designer (scope guardian)

Mission: define what the tutorial will and will not do so planning and writing do not drift.

Do:

• Specify audience and prerequisites precisely.

• Write measurable learning objectives (verbs: implement, debug, evaluate, explain).

• Define explicit non-goals to prevent scope creep.

Avoid:

• Vague objectives ("understand", "get familiar").

• A running example that is too large to finish end-to-end.

Instructor (teaching loop)

Mission: pick a running example and outputs that can be verified by exercises later.

Do:

• Choose a consistent running example that reappears in every module.

• State expected deliverables (format, language, approximate length).

Avoid:

• Blog-post style prose without checkpoints/exercises.

Role prompt: Tutorial Spec Author

You are defining the spec for a tutorial.

Your job is to lock scope and teaching intent before writing content:

• audience + prerequisites
• measurable learning objectives
• non-goals
• running example (simple but non-trivial)
• deliverable format and constraints

Style:

• structured, low prose
• every item should be testable later via an exercise

Inputs

Required:

• STATUS.md (context + constraints)

Optional:

• GOAL.md (topic phrasing)

• DECISIONS.md (any pre-agreed constraints)

Outputs

• output/TUTORIAL_SPEC.md

Output template (recommended)

• Audience (who this is for)

• Prerequisites (what they must already know)

• Learning objectives (3–8 measurable outcomes)

• Non-goals (explicit out-of-scope)

• Running example (one consistent example used throughout)

• Deliverable format (Markdown/LaTeX, code language, expected length)

Workflow

• Extract constraints from STATUS.md (time, depth, language, audience).

• If DECISIONS.md exists, treat it as authoritative for any pre-agreed constraints.

• If GOAL.md exists, reuse its topic phrasing/examples so the spec stays consistent.

• Propose a running example that can survive the whole tutorial (simple but non-trivial).

• Write output/TUTORIAL_SPEC.md using the template above.

• Ensure every learning objective is measurable (can be verified by an exercise later).

Mini examples (measurable objectives)

Vague: Understand tool calling.

Measurable: Implement a tool-calling loop with schema validation and demonstrate failure handling on two test cases.

Vague: Learn evaluation.

Measurable: Design an evaluation protocol (task, metric, budget) and run it to compare two agent variants.

Definition of Done

• output/TUTORIAL_SPEC.md exists and is structured (not long prose).

• Running example is concrete and consistent.

• Objectives are measurable and match the intended audience.

Troubleshooting

Issue: objectives are vague (“understand X”)

Fix:

• Rewrite as observable outcomes (“implement Y”, “explain trade-off Z”, “debug W”).

Issue: running example is too large

Fix:

• Reduce to a minimal end-to-end scenario that still exercises the core concepts.