Build an adaptive tutor with real refinement.

0. Setup

Work from the repository root. Create a scratch folder so the tutorial is safe to edit and rerun.

cd weavemark
mkdir -p outputs/tutorial-tutor

1. Write a useful tutor specification

Save this file as outputs/tutorial-tutor/adaptive-tutor.weavemark.md. It is already a real WeaveMark program: refinements, variables, branching, an output contract, and assertions.

<!-- Save as outputs/tutorial-tutor/adaptive-tutor.weavemark.md -->
@promplet version: 0.7
@refine module:weavemark.std.teaching.socratic_tutoring mingle: true
@refine module:weavemark.std.teaching.misconception_diagnosis mingle: true

# Adaptive learning tutor

@style "Warm, precise, and Socratic. Ask before explaining. Never shame the learner."
  Teach @{topic} to @{learner_context}.

  Learning target: @{learning_goal}

  Start by asking one diagnostic question. Use the learner's
  answer to choose the explanation depth.

  @match learner_level
    "beginner" ==>
      Use a concrete analogy before formal terms.
    "intermediate" ==>
      Connect intuition to the formal rule.
    "advanced" ==>
      Use counterexamples and transfer tasks.

  @if include_practice
    Add three practice tasks: one easy, one transfer,
    and one challenge.

  @output enforce: strict
    Return exactly these sections:
    1. Diagnostic question
    2. Explanation
    3. Likely misconception
    4. Practice
    5. Review plan

  @assert contains: "Likely misconception"
  @assert contains: "Diagnostic question"

The complete, tested specs for this tutorial are checked in under promplets/tutorials/: adaptive-tutor.weavemark.md and, with the @ask variant, adaptive-tutor-guided.weavemark.md.

2. Compose the tutor prompt

Now provide values and compile the concrete tutor prompt. The output should read as one coherent teaching prompt, not a pile of imported fragments.

weavemark outputs/tutorial-tutor/adaptive-tutor.weavemark.md \
  --batch-only \
  --var topic="Bayes' rule" \
  --var learner_context="a product manager who knows basic percentages" \
  --var learning_goal="use Bayes' rule to update a belief after new evidence" \
  --var learner_level=beginner \
  --var include_practice=true \
  --output outputs/tutorial-tutor/bayes-tutor.md

Open outputs/tutorial-tutor/bayes-tutor.md. Check for the five required sections and confirm that the final prompt tells the assistant to diagnose misconceptions before teaching.

3. Learn the language moves in the spec

4. Highlight: ask for missing teaching context with @ask

If a tutor needs a human clarification before compilation, wrap the rest of the spec in @ask. Notice the shape: the body of @ask is the specification to continue compiling after the answer arrives.

<!-- Save as outputs/tutorial-tutor/adaptive-tutor-guided.weavemark.md -->
@promplet version: 0.7

@ask clarifying question detail_level: 35%
  @refine module:weavemark.std.teaching.socratic_tutoring mingle: true
  @refine module:weavemark.std.teaching.misconception_diagnosis mingle: true

  # Guided adaptive learning tutor

  @style "Warm, precise, and Socratic. Prefer short learner turns over long lectures."
    Teach @{topic} to @{learner_context}.

    Clarify what the learner should be able to do by the end.
    Use the clarification answer as the concrete learning outcome.

    @match learner_level
      "beginner" ==>
        Use a familiar analogy, then name the formal idea.
      "intermediate" ==>
        Ask the learner to predict the next step before explaining it.
      "advanced" ==>
        Use a counterexample, then ask for a transfer explanation.

    @if include_practice
      Add a practice ladder:
      - recognition task
      - guided application task
      - transfer task
      - self-explanation prompt

    @output enforce: strict
      Return exactly these sections:
      1. Diagnostic question
      2. Learner model
      3. Socratic explanation
      4. Misconception repair
      5. Practice ladder
      6. Review plan

    @assert contains: "Diagnostic question"
    @assert contains: "Misconception repair"

Run it without --batch-only so WeaveMark can ask the clarification in the terminal:

weavemark outputs/tutorial-tutor/adaptive-tutor-guided.weavemark.md \
  --var topic="gradient descent" \
  --var learner_context="a designer learning machine-learning basics" \
  --var learner_level=beginner \
  --var include_practice=true \
  --output outputs/tutorial-tutor/gradient-descent-tutor.md

5. Adapt the same spec to another lesson

Do not copy the prompt. Reuse the same specification and change the variables. This is where WeaveMark starts paying rent.

weavemark outputs/tutorial-tutor/adaptive-tutor.weavemark.md \
  --batch-only \
  --var topic="Python async task cancellation" \
  --var learner_context="a Python programmer building their first concurrent CLI" \
  --var learning_goal="predict when cancellation propagates and clean up tasks safely" \
  --var learner_level=intermediate \
  --var include_practice=true \
  --output outputs/tutorial-tutor/async-cancellation-tutor.md

Compare the two outputs. The source stays stable, while the compiled prompt changes lesson domain, learner context, and branch behavior.

Final step: Use the output

The compiled tutor files are prompts for a teaching conversation. They do not teach the lesson on their own until an assistant runs the prompt.

What you learned

• Use @refine when reusable behavior should shape the current spec.
• Use mingle: true when the refined material should become one prompt, not an appendix.
• Use @match and @if for readable variation.
• Use @output and @assert to make output obligations explicit.
• Reuse the same spec by changing variables, not by duplicating prompt files.