notebook-paired-with-prose
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).
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- notebook-paired-with-prose
- metadata
- { "type": "convention" }
- 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).
03 SKILL.md 正文
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); 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; exit code 0 is required for commit. The per-stack execution commands live in one place, the notebook-author agent's Stack-Specific Execution table.
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 requirecd <project> && uv add <pkg>before re-executing. - R:
renv::status()should be clean; new packages requirerenv::install("pkg")thenrenv::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 (notebook_stack, set during /bookwright:init). The notebook-author reads it before drafting; none means a prose-only project and no notebook is ever drafted.
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.
04 同仓库更多 Skills
worldsmith-methodology
Use when working in a project with a worldbuilding documentation ecosystem (docs/ or lore/ directory). Provides the documentation-first methodology: canonical hierarchy, doc roles (timeline, lore, characters, systems), propagation discipline, and the dual canonical and exploratory workflow.
prose-craft
Use when writing fiction, editing fiction prose, reviewing chapters, or drafting scenes. Covers prose craft, dialogue mechanics, scene structure, and common failure modes in AI-assisted fiction. Trigger phrases: "write fiction", "edit chapter", "prose review", "scene draft", "dialogue check", "fiction craft", "edit this scene", "review my prose".
vista
This skill should be used when the user asks about research directions, open problems, future work, or follow-up research from the academic literature. Trigger phrases include "open problems in X", "what's next for Y", "future work for paper Z", "research directions on T", "salient follow-up research", "what should I work on next in", "find me follow-up research unrelated to my prior work", "broad survey of W", "neglected directions in V". Routes the request to the right Vista MCP tool, reads back the structured paper sections, and synthesizes research directions in the conversation.
synthesize
Make a research-agent run conclude and write synthesis.md (outcome, key findings, failed approaches, open questions, recommendations). Signals a live researcher to wrap up, or launches one in synthesis mode when none is running. Use when results are good enough or the agent is stalling.
status
Show the current state of a research-agent run from .research/: liveness, cycles and budget, sub-problem and hypothesis statuses, eval trend, current focus, and branches. Read-only.
resume
Resume an interrupted research-agent run from .research/. Re-launches the researcher to reload its structured state and continue from the current focus, optionally on a named branch or with a new budget. Use after a session restart, crash, or explicit pause.