schema_version: 1
north_star: 'Students develop systems judgment by experimenting with design choices: discovering what
  improves, what becomes worse, where a choice stops working, and when they should choose differently.'
status: proposed learning design
relationship:
  book: Explain the concepts and causal relationships.
  tinytorch: Build the underlying machinery.
  labs: Explore when a choice helps, what it costs, and when to choose differently.
  staffml: Articulate and defend assumptions and decisions.
learning_cycle:
- Read the situation, decision, and minimum briefing needed to begin.
- Predict a consequence.
- Choose an informative experiment.
- Compare benefit, cost, and unmet or unknown requirements.
- Explain the mechanism using saved evidence.
- Find a boundary or test a changed assumption.
- Defend a choice and a condition that would reverse it.
ownership: Chapter maps own textbook concepts. Each lab map distills the interactive learning claims.
  MLSysIM owns scenario events, track-specific investigations, physical inputs, and separately versioned
  outcome evidence.
scope: These maps specify intended learning and authoring requirements, not implemented experiments, classroom
  outcomes, or grading by the preferred design.
evidence_rule: Keep predictions, observations, analytical bounds, unknowns, and target validation distinct.
  Wrong predictions unlock the same experiments. A justified baseline or hold is valid.
assessment_rule: One integrated discussion can reuse concise part interpretations. Do not require a new
  essay for each metadata field. Judge causal reasoning, controlled comparison, limits, and transfer;
  LLM assistance is permitted.
narrative_contract:
  summary: A short scene and briefing lead to a meaningful choice. Feedback exposes the actual consequences,
    students explain a saved comparison, and the handoff makes the next question necessary.
  stages:
  - stage: Scene
    purpose: A person or team needs a decision because a request, constraint, or observation has changed.
  - stage: Briefing
    purpose: Give the task, relevant prior state or supplied checkpoint, essential terms, fixed conditions,
      and the decision due now.
  - stage: Choice
    purpose: Ask for a prediction and a purposeful supported trial. Let students choose among plausible
      alternatives and retain an uncertain prediction.
  - stage: Feedback
    purpose: Show what changed, what stayed fixed, the benefit and competing cost or unmet requirement,
      and what remains unknown for this actual run.
  - stage: Explanation
    purpose: Invite students to explain the mechanism from saved evidence and test a boundary or changed
      condition. Offer progressively deeper help after an attempt.
  - stage: Handoff
    purpose: State the scoped decision, unresolved obligation, and why the next part or chapter follows.
  visible_from_start:
  - Project, supplied or verified starting point, and chapter decision.
  - Observable learning goals without revealing experimental findings.
  - Full part roadmap, current location, and short previews of later work.
  - Discussion deliverable and the evidence expected to support it.
  - Next part and next lab question, without fabricated prior achievement.
  disclosure_rule: Keep headings and the route visible. Reveal instruments after a prediction and actual
    consequences after a trial; deeper explanations may follow an attempt. Optional background can collapse,
    but the core learning goals and destination remain visible.
  before_choice:
  - Project scene and chapter-owned decision.
  - Only the definitions, units, assumptions, requirements, and starting conditions needed for a meaningful
    first trial.
  - Plausible choices and a clear statement of what the learner can change.
  author_fields_not_to_reveal_as_answers:
  - The learning_claim and misconception describe the intended teaching outcome; show a short concept
    name and motivating question rather than pasting the resolution into the opening.
  - Track evidence descriptions specify what the notebook must expose. They are not fabricated observations
    to display before a run.
  feedback_rules:
  - Use the actual MLSysIM run or identified supplied observation; make a no-effect result, failure, and
    missing evidence intelligible.
  - Connect observed change to the affected component without treating a passing screen as target validation.
  - Let students inspect the result before revealing the full mechanism explanation. Optional help deepens
    explanation; essential gate failures and limitations stay visible.
  - Feedback remains available after any prediction; it does not reward guessing the preferred design.
  - Invite a next experiment when several explanations remain plausible.
  progression: Each chapter uses its own concepts and established prerequisites. Later concepts appear
    as a bounded open question or explicit next step, rather than an unexplained prerequisite.
  animation: Use animation when it makes a supported causal relationship easier to inspect. Tie it to
    the same run values, allow pause/replay or scrubbing, label time scaling, and retain a static view.
