Best Practices for Dives

Planning first, not code. I started with a one-pager. THis covered the persistence spectrum (ephemeral / one-off / durable / embedded), the five design principles, the five-phase build workflow, the data-layer priority order: schema, comments, views, macros. Then I turned it into a slide-by-slide outline. 15 slides, build states per slide, real verbatim prompts with the typos left in, speaker notes that trust silence.

The Dive is one React component. A `slides` array, each entry a function returning JSX. A `Slide` primitive with three variants: `light` (cream), `dark` (charcoal), `statement` (centered, lots of room). A `Code` block for prompt examples. Brand colors match from our website so anyone watching both gets continuity. Coral, JetBrains Mono, Inter.

Once I have the narrative in a good place, I added navigation. Arrows, space, home/end, `f` for fullscreen. Tap to advance — left half back, right half forward. Wheel scroll with a cooldown so a trackpad gesture doesn't skip three slides at once. (Got bit by that previously so I fixed it here.)

Slide 19 is the heavy lifter. DABstep tier comparison, live SQL against `agentic_sql_results_public.results`, Recharts bar chart, macros bar in coral, the other three muted. Cost row underneath, one cell per bar. The chart animates on slide-active so the bars grow when you land. Otherwise you arrive and the punchline has already been delivered.

A few tweaks worth keeping:

- Shot/chaser grid needed the chaser text bumped from `#888` to `#aaa` on dark slides.
- Slide 2 had a generic "30%" treatment. Replaced with a 14rem coral number for emphasis.
- Persistence spectrum started as four equal columns. I ended up tuning for aesthetics.
- Slide 9, the "it's just code" reveal, shows a stripped-down `dive.tsx` snippet — `useSQLQuery`, `REQUIRED_DATABASES`, the React shell. The renderer choked on the literal `export` keywords inside the template literal. Preprocessor was reading them as top-level exports. Five-minute bug, ugly fix: `${'export'}` interpolations. Same rendered output, no parser confusion.
- NBA Game Quality Explorer link was the workspace UUID URL. Switched to the public dive-gallery slug.

I needed eight-ish iteration passes. Most of the time went into narrative: having a good setup, planting call backs, adding reveals. Each piece building on the pieces before it.