execute-notebook

Skill: Execute Notebook

Run the notebook at $ARGUMENTS end-to-end with a fresh kernel and persist its outputs back into the file. This is the "restart and run all" hygiene step recommended by Rule 7 of Ten Simple Rules for Writing and Sharing Computational Analyses in Jupyter Notebooks (Rule et al. 2019), automated.

Step 1 — Pre-flight checks

Before invoking papermill, verify:

1. Notebook exists: resolve $ARGUMENTS to an absolute path. If the file does not exist, fail with: Notebook not found: <path>.
2. Papermill installed: run python3 -c "import papermill" via Bash. If it raises ModuleNotFoundError, fail with:

   papermill not installed. Install with one of:
     pip install papermill
     poetry add papermill
   

3. Dependencies sanity check (warning, not error): if neither requirements.txt nor pyproject.toml exists in the notebook's directory or cwd, print:

   WARNING: no requirements.txt or pyproject.toml found. Consider running /freeze-deps first.
   

   Do not abort on this warning — proceed with execution.
4. Kernel availability: read the notebook JSON, extract metadata.kernelspec.name. Run jupyter kernelspec list --json via Bash and verify the kernel exists. If not, fail with:

   Kernel '<name>' not available. Available kernels:
   <output of jupyter kernelspec list>
   

Step 2 — Execute the notebook

Invoke papermill from the notebook's directory as cwd (so relative paths like data/foo.csv resolve correctly):

cd <notebook_dir>
python3 -c "
import papermill as pm
import time
start = time.time()
try:
    pm.execute_notebook(
        input_path='<notebook_filename>',
        output_path='<notebook_filename>',  # overwrite
        kernel_name='<kernel_from_metadata>',
        progress_bar=False,
        log_output=False,
        request_save_on_cell_execute=True,  # save partial output on failure
    )
    print(f'OK {time.time() - start:.1f}')
except pm.PapermillExecutionError as exc:
    print(f'FAIL {time.time() - start:.1f} cell={exc.cell_index} ename={exc.ename} evalue={exc.evalue}')
    raise
"