# Notebook Quality Audit

## Quality Standard

Each curriculum notebook should:

- Have a sequential filename and matching `# Lesson NN:` title.
- Start with CS230 inspiration, demand forecasting focus, learning objectives, and a senior-readiness checkpoint.
- Include at least three concrete learning objectives.
- Include a detailed markdown explanation immediately before every code cell.
- Explain what each code cell does, why it matters, key operations to notice, and what to inspect.
- Include a lesson recap immediately before exercises that summarizes what happened and why it mattered.
- End with at least three exercises.
- Contain runnable, nonempty code cells with no committed outputs or execution counts.
- Avoid placeholder text such as `TODO`, `TBD`, or `FIXME`.
- Run from a clean kernel using only the UV-managed project dependencies.

## Current Course Shape

The curriculum currently contains 23 notebooks:

- Lessons 00-17 cover the CS230-inspired core path from orientation, synthetic data, baselines, neural-network basics, optimization, ML strategy, CNNs, sequence models, transformers, probabilistic forecasting, embeddings, experimentation discipline, Ralph-style DL iteration, interpretability, monitoring, systems, and capstone work.
- Lessons 18-22 add hiring-manager supplemental material: SQL feature engineering, causal inference for promotions, hierarchical reconciliation, decision optimization, and portfolio defense.

## Quality Gates

Use these checks after editing or regenerating notebooks:

```bash
uv run python tools/generate_notebooks.py
uv run python tools/validate_notebooks.py
uv run ruff check src tests tools
uv run python -m compileall src tools
uv run pytest
```

For a deeper runtime check, execute all notebooks with a noninteractive plotting backend. This is intentionally not part of the lightweight validator because several lessons train small neural networks.

## Audit Notes

- Notebook generation is source-controlled through `tools/generate_notebooks.py`; avoid manual one-off edits to generated notebooks unless the generator is also updated.
- The validator now checks curriculum quality, not just notebook JSON syntax.
- Explanation cells and recap cells are generated in `tools/generate_notebooks.py`; improve the generator rather than patching generated notebooks by hand.
- The synthetic data lesson was inserted early because the rest of the curriculum depends on generated demand data.
- The remaining portfolio stretch is to add a real public demand dataset extension, since synthetic data can support learning and stress testing but cannot prove real-world performance by itself.