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:

1. Read the style guide: First review style_guide.md to understand current best practices
2. Identify the notebook: Ask user for path if not provided
3. 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
4. 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
5. Manual review: Read through the markdown version evaluating against style guide and rubric
6. Score each dimension: Apply scoring guidelines objectively
7. Generate report: Follow the audit report format below
8. 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 lessons to user's context
• Points to next steps or related resources

Code Quality

• All code blocks have explanatory text before them

…