Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# exposition-plan Card

# Exposition-Plan Cards

An exposition-plan is a **worked process** for how to *present* a subject, and it ends in a concrete set of **rules**. It is **not** a fixed lesson script — don't pre-decide a move-by-move sequence. Its job is to produce *good, deliberate* presentation choices for *this* material and *this* learner, and to leave behind rules you can follow later without re-reasoning.

Write the card in this order — each step feeds the next:

## 1. `learner-translation` (do this FIRST)

Translate what's known about the learner (from the probe / progress, and whether the course is `generic` or for a specific person — see the course's `audience`) into **concrete implications for presentation style**. Not "they're rusty" but "they reason out loud and trust their own intuitions, so lead with their phenomena and let terminology stay loose." This grounds the ratings that follow.

## 2. `approaches` — enumerate and **rate** them

List the candidate ways to present this material, and rate each honestly for *this* material and *this* learner:

```yaml
approaches:
  - { approach: socratic dialog, rating: primary, why: Draws out and reshapes the learner's own model }
  - { approach: a worked figure/manipulative, rating: some, why: Good for the one procedural step; overkill elsewhere }
  - { approach: plain textual exposition, rating: "considered — sparingly", why: Fine for framing, but not the spine here }
```

**Let the concept's `kind` and target `depth` steer the first cut.** A node aimed at *understand* needs an approach that builds the model (dialog, contrasting cases), not a passive read; an *apply* node wants practice or a manipulable; a *remember* fact wants retrieval; an *analyze* principle wants contrasting cases and self-explanation. The (kind, depth) pair from the concept-map is your starting hypothesis for what fits — then rate against *this* learner.

**Why rate, not just list:** you (like anyone) reach for the familiar — and your familiar default is **textual exposition**. Force yourself off it by genuinely considering non-textual options (dialog, a figure or manipulable, a diagram, contrasting cases, an analogy) and saying why each does or doesn't fit.

**But never use a technique just because it exists.** Each one must earn its place for this subject and learner. Different domains and learners call for different techniques. **If mostly-textual is genuinely the right answer here, say so** — variety is not the goal, fit is.

## 3. `rules` — the compiled output

Distill the above into a short list of **concrete, standalone rules** that will guide you later — while you're authoring material or mid-conversation, focused on other things — *without* re-reading this whole card:

```yaml
rules:
  - Open each concept from a phenomenon the learner already has; pull the idea out of it.
  - Use dialog to surface the learner's model before correcting it; never lead with a definition.
  - Reserve prose for framing and transitions, not for carrying a mechanism.
```

These `rules` are **compiled to a box rule that auto-loads while you work in this course**, so write them to stand on their own. Keep the *reasoning* behind them here (and in the body); the rules themselves should be terse and actionable.

## Body

The reasoning narrative — why this shape, and how it should adapt. Living. **Use neutral pronouns (they/them) for the learner** regardless of who they are.

## The `contains:` field

Give this card a one-sentence `contains:` — the prime retrieval field for
`bbx search` and listings. How to write a good one (carry the information when
it's concise, never a list of parts, under 200 characters) is in the agent
guide's ABOUT_CARDS section.

## Templates

### exposition-plan

A plan for how to present a subject (modalities + decisions, with the reasoning kept in)

```bash
bbx create <path>.exposition-plan.card -t exposition-plan
```

Template: exposition-plan
Description: A plan for how to present a subject (modalities + decisions, with the reasoning kept in)
Card types: exposition-plan

Arguments:
  title (optional): Display title