| name | story-gen |
| description | Generate, fact-check, and ship "world-connection stories" (story-bearing bridge edges) for practice-graph knowledge nodes, using the tournament pipeline that won the 2026-07-11 prompt×model experiment. Use when the user asks to add/refresh/improve world-connection stories, hooks, or "wow" content for math skills, or to run the story pipeline on new nodes/domains. Ships via storyRegistry.ts + seedRegistry; prod writes gate on explicit approval. |
Story generation — the tournament pipeline
Stories are verified skill→world payloads on bridge edges (knowledgeNodeEdges.story;
ontology in review/edge-ontology.html). They are
spoken to children as truth, so this pipeline is quality-gated at every stage and its
prime directive is: a skipped node beats a sub-star story, every time. Coverage is not
the goal; wonder is. (Validated empirically: the pipeline below produced 6 star-tier
stories from 10 nodes that two earlier naive passes had skipped as hookless. The nodes
were never hookless — the prompts were.)
The ⭐ bar (the contract every story must clear)
Calibration exemplar: the MEDIANTS story — the "wrong" way to add fractions (add tops,
add bottoms) always lands between the two fractions; it's the mediant, and iterating
it builds the Stern–Brocot tree. Star-tier requires ALL of:
- Anchored in the kid's own experience — reframes something the kid already does,
says, or gets wrong. A revelation inside their world, not a fact about the topic.
- Experienceable in ~60 seconds — the kid can DO it and watch the surprise happen
(compute it, clap it, fold it, divide it). This is the retention mechanism, not a
nicety: self-generated aha moments are remembered for weeks where told facts aren't
(the insight-memory advantage, Danek et al.), and the felt spike predicts the
memory better than the cognitive content.
- An inversion or hidden identity — the wrong/boring/arbitrary thing is secretly
right/deep/chosen. This is Keltner & Haidt's "need for accommodation": awe is the
emotion of schema revision, i.e. the affective signature of real learning.
- Opens a thread — a doorway to a bigger structure (their "vastness"), never a
terminal plaque fact.
- True + specifically sourced — literally verifiable, named source. No myths, no
hedged folklore (the ÷-as-fraction-with-dots origin story died here twice).
Soft criteria that lift a story: a named human with a date (Recorde tired of writing
"is equalle to"; Ulam doodling in a boring meeting); intra-math wonder and world
connection are equally star-eligible (Andy, 2026-07-11).
Slop tells (auto-fail): "used in ⟨industry⟩"; method-history with no reframe; the
superlative doing the work ("first/oldest"); math as decoration; anything a
checkout-counter poster could say.
Delivery note for tutor integration (the #588 rework): open the information gap
before closing it — probe/anomaly first, reveal second (Loewenstein's gap theory; and
the Upworthy caution: a gap without an experienceable payoff is betrayal, which
criterion 2 prevents).
The pipeline (5 stages — do not skip any)
Faux-agent (Copilot CLI) turns are free; spend them liberally. The QB's own tokens are
for the spec, the curation, and the final judgment.
- Generate — tournament method, 2 model families. For each target node the
generator must FIRST brainstorm five distinct one-line candidate wows from different
angles (mistake-inversion, history, nature, music/art, deeper-math), self-score
against the five criteria, and fully write only a winner that clears the bar.
Run it on two families (e.g.
claude-sonnet-5 + gpt-5.5, one research-grounded
arm with web search). Empirical note: the tournament structure is the active
ingredient, not the model — it prevents first-association grabbing, which is what
made a bare "hunt inversions" prompt recycle already-shipped far-ends. Give every
generator the current convex/lib/practice/storyRegistry.ts as exemplars AND as a
dedup blacklist (near-duplicate far-ends/claims are kills, not finds).
- Adversarially verify — a DIFFERENT model family than the generator. Prompt to
REFUTE, kill-on-doubt; every load-bearing number, date, name, and citation checked
(web search allowed). This stage has caught: two origin myths, fabricated batting
statistics, a wrong "first printed book" superlative, and several overclaims. A
plausible-sounding false story delivered to a child with authority is the worst
outcome this pipeline can produce.
- QB curation. Apply REVISE fixes by hand; kill anything that is merely true but
not wonderful (galley division died here); rewrite salvageable concepts whose data
failed verification (Simpson's Paradox was killed for fabricated numbers, then
rebuilt from the verifier's own verified figures — the concept was a star, the
digits were not). Prefer replacing a shipped good-not-great story when a new
star exists for the same node (Andy: "YES DEFINITELY"); replacement = remove the
old registry entry + clear the old prod story via
edgeStories:removeStoryInternal
(the bridge survives story-less — the connection stays, the card changes).
- Ship. Append entries to
STORY_REGISTRY with provenance: "generated", in a
fresh worktree, normal PR flow. Length limits are enforced by validateStory: hook
≤200, narrative ≤600, probe ≤300. Two skills may share one far-end node (one star,
two doorways — the cicada pattern); never mint two far-end nodes for one concept.
- Seed prod (explicit per-turn approval required, from the master checkout):
npx convex run edgeStories:seedRegistry '{}' --prod — idempotent and additive;
a teacher-edited or teacher-deleted story is never clobbered (durable-bridge guard).
Tracking (qualitative-first — see the digest's Stories section)
At pilot N, rates are noise; transcripts are signal. The weekly practice digest carries
a qualitative Stories section (registry deltas, story-adjacent leaps, curation events).
When tutor-side serving lands (#588 rework), add per-serve outcomes there — engage /
did-the-thing / leap / later-recall — and judge stories by leaps and recall, never
engagement (the practice engine's objective-function invariant applies to stories
verbatim). The rubric above is a model of what causes wonder; the funnel exists to
calibrate it. When a predicted star flops with real kids, amend the rubric, not the kid.
