Cookbook Audit
Instructions
Review the requested Cookbook notebook using the guidelines and rubrics in `style_guide.md`. Provide a score based on scoring guidelines and recommendations on improving the cookbook.
The style guide provides detailed templates and examples for:
- Problem-focused introductions with Terminal Learning Objectives (TLOs) and Enabling Learning Objectives (ELOs)
- Prerequisites and setup patterns
- Core content structure
- Conclusions that map back to learning objectives
**IMPORTANT**: Always read `style_guide.md` first before conducting an audit. The style guide contains the canonical templates and good/bad examples to reference.
Workflow
Follow these steps for a comprehensive audit:
- **Read the style guide**: First review `style_guide.md` to understand current best practices
- **Identify the notebook**: Ask user for path if not provided
- **Run automated checks**: Use `python3 validate_notebook.py <path>` to catch technical issues and generate markdown
- The script automatically runs detect-secrets to scan for hardcoded API keys and credentials
- Uses custom patterns defined in `scripts/detect-secrets/plugins.py`
- Checks against baseline at `scripts/detect-secrets/.secrets.baseline`
- **Review markdown output**: The script generates a markdown file in the `tmp/` folder for easier review (saves context vs raw .ipynb)
- The tmp/ folder is gitignored to avoid committing review artifacts
- Markdown includes code cells but excludes outputs for cleaner review
- **Manual review**: Read through the markdown version evaluating against style guide and rubric
- **Score each dimension**: Apply scoring guidelines objectively
- **Generate report**: Follow the audit report format below
- **Provide specific examples**: Show concrete improvements with line references using the style guide templates
Audit Report Format
Present your audit using this structure:
Executive Summary
- **Overall Score**: X/20
- **Key Strengths** (2-3 bullet points)
- **Critical Issues** (2-3 bullet points)
Detailed Scoring
#### 1. Narrative Quality: X/5 [Brief justification with specific examples]
#### 2. Code Quality: X/5 [Brief justification with specific examples]
#### 3. Technical Accuracy: X/5 [Brief justification with specific examples]
#### 4. Actionability & Understanding: X/5 [Brief justification with specific examples]
Specific Recommendations
[Prioritized, actionable list of improvements with references to specific sections]
Examples & Suggestions
[Show specific excerpts from the notebook with concrete suggestions for improvement]
Quick Reference Checklist
Use this to ensure comprehensive coverage:
**Introduction** (See style_guide.md Section 1)
- [ ] Hooks with the problem being solved (1-2 sentences)
- [ ] Explains why it matters (1-2 sentences)
- [ ] Lists learning objectives as bullet points (2-4 TLOs/ELOs)
- [ ] Focuses on value delivered, not machinery built
- [ ] Optional: mentions broader applications (1 sentence)
**Prerequisites & Setup** (See style_guide.md Section 2)
- [ ] Lists required knowledge clearly
- [ ] Lists required tools (Python version, API keys)
- [ ] Mentions recommended background if applicable
- [ ] Uses %%capture for pip install to suppress output
- [ ] Uses dotenv.load_dotenv() not os.environ
- [ ] Defines MODEL constant at top
- [ ] Groups related installs in single command
**Structure & Organization**
- [ ] Has logical section progression
- [ ] Each section teaches through demonstration
- [ ] Code blocks have explanatory text before them
- [ ] Includes what we learned after code blocks
- [ ] Uses headers to break up sections
**Conclusion** (See style_guide.md Section 4)
- [ ] Maps back to learning objectives
- [ ] Summarizes what was accomplished
- [ ] Suggests ways to apply
<!-- truncated -->