explain-systems-visually git:20261001.b885f69A

Immutable. This exact content never changes and is served at /api/v1/blob/e07768e7ed411419.

---
name: explain-systems-visually
description: "Create or revise technical teaching slides and visual walkthroughs with prerequisite-aware progression, explicit inputs and outputs, stable color-linked equations and algorithm steps, and checks for understanding and recall. Use when readers must connect a system's purpose, components, mathematics, and execution."
---

# Explain Systems Visually

Teach why each object is needed, what it means, and how it advances the opening
question. A readable diagram and a defined symbol do not establish understanding.
Preserve the overall map while revealing each operation and its consequences.

Respect the requested medium, audience, and duration. A teaching walkthrough and
a short research talk need different depth; do not turn every request into a deck
or add slides automatically. Retain an equation-and-text format when requested.

## Establish the teaching contract

Read the current source and implementation before explaining them. Retain their
notation and abstraction boundaries; identify source disagreements instead of
silently combining versions. Separate supplied method, implementation choices,
proposed extensions, and demonstrated results.

State the audience's starting knowledge and one question the explanation should
enable them to answer. Put the intended output or decision near the beginning,
before its machinery. If audience or duration is missing, state a reasonable
assumption; ask only when the answer would materially change the artifact.

For each meaningful block, establish its role, input, operation, output,
persistent state, initialization, and parameters. Mark quantities as supplied,
measured, inferred, learned, solved, or predicted, as applicable at each phase.
An observed quantity in training may be predicted during deployment. A learned
function, integrator, state, and coordinate transform are different objects.
Keep this contract in authoring notes, not as boilerplate on every slide.

## Plan progression before layout

For a new sequence or a flow repair, read
[references/learning-flow.md](references/learning-flow.md). Check three scales:

- Whole explanation: purpose, dependencies, method, consequence, evidence.
- Within each section: establish the need, teach the operation, use its result.
- Adjacent slides or reveals: the next step consumes something already understood.

Use this compact authoring contract for each substantive reveal:
`question -> established prerequisites -> new move -> interpretation -> next question`.
Keep it off the audience slide. Do not demand identical slide structures or equal
amounts of text. Aim for one coherent conceptual move, not necessarily one equation.

Distinguish physical dependency order, execution order, and teaching order. Match
the algorithm's overall progression where useful, but teach a prerequisite before
invoking its name. Do not draw a sequential pipeline for a simultaneous solve.
Read narration across slide boundaries as a continuous explanation before styling.

## Preserve a visual vocabulary

Use a stable overview when a system map helps. Orient, highlight one block,
expand its input-operation-output, trace a concrete case, then reconnect to the
whole. For stateful systems, distinguish within-step computation, between-step
state updates, and between-run learning. Show what persists or resets.

Keep geometry, names, symbols, and role colors stable across related views.
Reuse semantic colors in blocks, equation terms, port labels, and relevant
algorithm lines. Keep explicit labels and grayscale legibility; color reinforces
identity rather than replacing it. Do not assign a new color to every variable.

Label what moves along arrows. Distinguish physical exchange, data dependency,
state carry, and gradients when several coexist. Containment is not execution;
equation-to-block correspondence lines are not flow arrows. Preserve port
directions and distinguish known inputs from inferred or computed quantities.

For Beamer, read [references/beamer.md](references/beamer.md).

## Link the algorithm to its explanation

Give meaningful algorithm steps stable identifiers and link them to the block,
equation, source, and explanation that implement or explain each operation.
Expose the input/output contract before a compressed function call. Distinguish
an explanatory pseudocode name from an actual API. Identify training, one-step
prediction, rollout, and composition as separate operations when they are.

Use the same semantic color for a step and its block. On an expansion, emphasize
the relevant line range; do not show the complete algorithm on every page. Keep
reference identifiers stable when pagination changes. Check control flow: every
consumed quantity must be available on that path, with consequential solver,
initialization, loss, and stopping choices traced to the appropriate source.
Familiar optimizers need less teaching than the model-specific computation.

## Make the mathematics teach the operation

Introduce purpose and a concrete interpretation before relying on shorthand.
Where abstraction is the obstacle, show a small explicit case before the compact
map, matrix, or function name. Explain domain/codomain, units, direction, sign,
and role where they matter. Define a law by what it maps, not just its title.

Separate physical evolution from inference about it, and parameter fitting from
using fixed parameters. Explain constraints versus rates, values versus their
derivatives, and explicit time dependence versus changing arguments when those
distinctions matter. Do not impose these categories on unrelated topics.

When a governing formulation anchors the story, first show a readable compact
view with an intelligible objective. Revisit it at milestones with the same
equations, row positions, labels, and colors, highlighting what is now understood.
Each return must enable a new answer. Secondary definitions can live in a linked
expansion; omitted conditions must not silently change the problem.
Keep decisions, objectives, hard constraints, penalties, and evaluation metrics
distinct. Improved cost alone does not establish optimality or stability.

Show both contributing terms before demonstrating cancellation. Preserve signs,
transposes, grouping, and units through styling; color is not parentheses.
Put claim-limiting assumptions in the main explanation. Separate physical
consistency, numerical solvability, identification, prediction accuracy, and
experimental evidence. A diagram or successful solve is not a proof of all five.
Label illustrative examples as such; do not manufacture supporting experiments.

## When the walkthrough is a rehearsal for a paper

Use the teaching sequence to expose missing premises and unresolved scientific
questions before polishing a manuscript. A storyboard can precede a full deck;
reuse source-current slides rather than automatically regenerating them.
Map each substantive teaching question to a paper paragraph, figure, equation,
or algorithm step, with its evidence and indispensable assumptions.
Keep symbols, semantic colors, and step identities stable, while consolidating
overlays and repeated recall views for print. Supply in prose any bridge that
previously depended on the speaker. A clear illustration is not measured evidence,
and a successful explanation does not by itself demonstrate a novel contribution.

Use `rigorous-paper-author` for the paper's claim and evidence structure when
available. A small paper edit does not require producing a separate slide deck.

## Review, compress, and verify

For substantial walkthroughs, use the gates and reviewer protocol in
[references/review-and-testing.md](references/review-and-testing.md).
One lead author owns the integrated narrative and notation. Small changes may
use separate review passes; substantial technical work benefits from independent
technical and first-reader reviews when delegation is available and authorized.
Do not equate multiple reviewers with demonstrated audience comprehension.

Before adding a slide, try reordering, replacing abstraction with an example,
recalling an earlier anchor, removing repetition, or moving secondary detail to
backup. Teach a foundation once, then retrieve it at the point of need. Preserve
material assumptions and input/output contracts during compression.

Render the actual deliverable and inspect every page or reveal, including dense
pages at full size and adjacent overlays in order. Check mathematical grouping,
labels, arrows, clipping, and positional drift. Sweep for repeated defect classes
and fix shared macros where appropriate. A clean compile, symbol checker, or
phrase-presence test does not establish comprehension or visual correctness.

Deliver the requested artifact and editable source where appropriate, with
speaker notes when useful. Report the checks actually performed and remaining
limits; if rendering was not inspected, do not call it visually verified.