cookbook-audit

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)