cookbook-audit

Files (4)

• .gitignore
• SKILL.md
• style_guide.md
• validate_notebook.py

SKILL.md (first lines)

# 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
- [ ] No hardcoded API keys (automatically checked by detect-secrets)
- [ ] Meaningful variable names
- [ ] Comments explain "why" not "what"
- [ ] Follows language best practices
- [ ] Model name defined as constant at top of notebook

**Output Management**
- [ ] pip install logs suppressed with %%capture
- [ ] No verbose debug output
- [ ] Shows relevant API responses
- [ ] Stack traces only when demonstrating error handling

**Content Quality**
- [ ] Explains why approaches work
- [ ] Discusses when to use this approach
- [ ] Mentions limitations/considerations
- [ ] Provides transferable knowledge
- [ ] Appropriate model selection

**Technical Requirements**
- [ ] Executable without modification (except API keys)

From mattmre/EVOKORE-MCP-PUBLIC, MIT.

More from mattmre/EVOKORE-MCP-PUBLIC