Notebook Paired With Prose

---
name: notebook-paired-with-prose
description: Use when drafting or executing a paired notebook for a bookwright chapter. Covers when notebooks are required vs optional, numerical-sanity-target convention, exec-from-fresh-kernel requirement, and stack-specific execution commands (Jupyter/R Markdown/Quarto).
metadata:
  type: convention
---

# Notebook Paired with Prose (bookwright)

In a technical textbook, paired notebooks are not optional decoration. They are empirical verifiers: a chapter that claims a formula or worked example has a notebook that COMPUTES the formula and shows the empirical result matches. Broken notebook means broken chapter.

## When notebooks are required vs optional

Required:

- Any chapter with a worked numerical example. The notebook must compute the same example and match.
- Any chapter with an algorithm. The notebook implements it and runs it.
- Any chapter with an empirical claim ("the SE is roughly 0.05"). The notebook simulates and verifies.

Optional or omitted:

- Theory-only chapters (no worked examples, no algorithms). Bernoulli's chapters 4, 13, 17 had no notebooks; the master spec marks them theory-only.
- Bridge chapters that exist only to connect Parts.

The master spec's chapter outline marks which chapters have notebooks. The per-chapter plan's notebook task spec lists the content + numerical-sanity targets.

## Numerical-sanity-target convention

The plan lists explicit targets like:

- "Empirical FPR at $\fprate = 0.01$, k=7: within plus-or-minus 0.005 of theoretical 0.0078."
- "Wald CI coverage at $n_0 = 200, \fprate = 0.05$: in $[0.93, 0.97]$ band."

The notebook-author agent computes these and compares. Match = pass. Miss = flag for user review (could be the prose is wrong, could be the notebook is wrong, could be sampling noise).

## Exec-from-fresh-kernel requirement

Notebooks MUST execute end-to-end from a fresh kernel with no errors. The notebook-author runs:

- Python+uv+Jupyter: `cd <project>/notebooks && uv run jupyter nbconvert --to notebook --execute <name>.ipynb --output <name>.ipynb`
- R+renv+RMarkdown: `cd <project>/rmd && Rscript -e 'rmarkdown::render("<name>.Rmd")'`
- Quarto: `cd <project>/qmd && quarto render <name>.qmd`

Exit code 0 is required for commit.

## Common gotchas

- Python: forgetting to seed the RNG produces non-reproducible outputs. Always `np.random.default_rng(seed=42)` or similar.
- Python: dependencies must be in `pyproject.toml`. New dependencies require `cd <project> && uv add <pkg>` before re-executing.
- R: `renv::status()` should be clean; new packages require `renv::install("pkg")` then `renv::snapshot()`.
- Quarto: cell-by-cell execution depends on engine; if mixing R + Python, configure the engine carefully.
- All stacks: explicitly seed any randomness. Markdown cells should describe what the code cell will do, not just narrate it.

## Cell discipline

- Title cell (markdown): names the chapter and notebook.
- Setup cell (code): imports + seeded RNG.
- Body cells: alternating code + markdown for narrative + numerical verification.
- Discussion / open-question cell (markdown): forward-reference downstream chapters if relevant.

Match the cell count of prior chapter notebooks for the project (typically 12-18 cells). Light notebooks have ~10; substantive have ~16-20.

## Pluggable stack

The project's `docs/superpowers/bookwright.config.yaml` records the stack choice (set during `/bookwright:init`). The notebook-author reads this config before drafting. Stack-specific commands above; stack-specific conventions (Python uv, R renv, Quarto rendering) are picked up from the config.

## Skipping a notebook

If a chapter is theory-only per the master spec, skip the notebook task entirely. Do NOT write an empty placeholder notebook (clutters the project). The integration check verifies which chapters have notebooks vs theory-only.