queelius/notebook-paired-with-prose

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.