---
description: Safely edit Jupyter Notebook (.ipynb) files
---

# Notebook Editing

Safely edit Jupyter Notebook files using the correct tools.

## Required Rules

1. **Tool usage**: Use only the `NotebookEdit` tool
   - Do not use text editing tools like `Edit`, `Write`, `search_replace`
   - .ipynb files are JSON structures and require dedicated tools

2. **Cell insertion order**: Ensure correct order when creating new notebooks
   - **Important**: Cells are inserted at the beginning if `cell_id` is not specified
   - **Method 1 (recommended)**: Track previous cell's cell_id for sequential insertion
     ```
     Insert first cell -> Returns cell_id='abc123'
     Insert second cell with cell_id='abc123' -> Inserted after first cell
     Insert third cell with cell_id='def456' -> Inserted after second cell
     ```
   - **Method 2**: Insert in reverse order (from last cell to first)
   - **Never**: Insert sequentially without cell_id (causes reverse order)

3. **Source format**: Source may be saved as string when using NotebookEdit
   - **Problem**: `"line1\\nline2"` (string) -> `\n` displayed literally in Jupyter
   - **Correct**: `["line1\n", "line2\n"]` (list of strings)
   - **Solution**: When creating new notebooks, directly write JSON using Python

4. **Post-edit verification**: Always verify after modifications
   - Validate JSON syntax
   - Confirm cell execution order is preserved (check first 30 lines with Read)
   - Check for missing functions/imports/dependencies
   - Preserve cell outputs unless explicitly instructed otherwise

5. **Key Insights verification**: Verify outputs before documenting
   - **Required steps**:
     1. Read notebook output cells (use Read tool)
     2. Read generated data files (CSV, JSON, etc.)
     3. Check visualizations/images if any
   - **Never**: Write insights based only on code flow
   - **Required**: Document data source (e.g., "Source: outputs/analysis.csv")

## Guidelines

- **Use dedicated tool only**: Never use editing tools other than NotebookEdit
- **Preserve structure**: Maintain existing cell order and outputs
- **Verification required**: Immediately verify changes after editing
- **Follow CLAUDE.md**: Adhere strictly to project guidelines

## Path Compatibility

Notebooks in `notebooks/` cannot use project-root relative paths directly.

```python
# First code cell - set PROJECT_ROOT
from pathlib import Path

PROJECT_ROOT = Path.cwd().parent
if not (PROJECT_ROOT / 'outputs').exists():
    PROJECT_ROOT = Path.cwd()

# Use PROJECT_ROOT for all file paths
data = np.load(PROJECT_ROOT / 'outputs/data.npz')
```

## Computation Efficiency

### Avoid
- Repeated model loading across cells
- Re-running inference when results exist
- Computing without caching

### Required patterns
1. **Cache-first**: Load cached results if exist, compute only if missing
2. **Single instance**: Load model once in early cell, reuse throughout
3. **Filter over recompute**: Filter cached results instead of re-running with different parameters

