TinyTorch/docs/development/module-creation-checklist.md

📋 Module Creation Checklist

Comprehensive step-by-step guide for creating high-quality TinyTorch modules.

🎯 Planning Phase

Module Design

• Choose real dataset (CIFAR-10, ImageNet, etc. - no synthetic data)
• Define learning objectives (what will students build and understand?)
• Identify production connections (how does this relate to real ML systems?)
• Plan visual feedback (how will students see their code working?)
• Design progression (easy → medium → hard with clear indicators)

Educational Approach

• Choose learning pattern: Build → Use → [Reflect/Analyze/Optimize]
• Plan immediate feedback (students see results quickly)
• Design real-world connections (production ML relevance)
• Structure progressive complexity (build understanding step by step)

🛠️ Implementation Phase

Core Development

• Create module directory: modules/{module}/
• Create main file: {module}_dev.py with Jupytext header
• Add NBDev directives: #| default_exp core.{module} at top
• Implement complete working version first (get it working)
• Add educational structure (markdown explanations, TODO guidance)
• Include visual feedback (development only, not exported)
• Add progress indicators for long operations

File Structure

modules/{module}/
├── {module}_dev.py          # Main development file
├── module.yaml              # Simple metadata
├── tests/
│   └── test_{module}.py     # Comprehensive tests
└── README.md                # Module overview

Educational Content

• Clear conceptual explanations before implementation
• Comprehensive TODO guidance with approach, examples, hints
• Real-world context and production connections
• Visual confirmation of working code (development only)
• Progressive difficulty with clear indicators

🧪 Testing Phase

Test Creation

• Create test file: tests/test_{module}.py
• Use real data throughout (no mock/synthetic data)
• Test realistic scales (performance at real data sizes)
• Include edge cases (empty input, wrong shapes, etc.)
• Add performance tests (reasonable execution time)

Test Verification

• All tests pass: tito module test --module {module}
• Tests use real data (production datasets, realistic parameters)
• Performance acceptable (reasonable execution time)
• Edge cases covered (error handling, boundary conditions)

📦 Integration Phase

Package Export

• Export to package: tito package sync --module {module}
• Verify exports: Check tinytorch/core/{module}.py exists
• Test imports: from tinytorch.core.{module} import ClassName
• No circular dependencies or import issues

CLI Integration

• Status shows correctly: tito module status
• Tests run via CLI: tito module test --module {module}
• Notebooks convert: tito module notebooks --module {module}

📚 Documentation Phase

Module Documentation

• Create README.md with overview and usage examples
• Document learning objectives and key concepts
• Include usage examples (both Python and notebook)
• Add troubleshooting common issues

Metadata

• Create module.yaml with basic info (name, title, description)
• Set dependencies (prerequisites, builds_on, enables)
• Define exports_to (tinytorch package location)

✅ Quality Assurance

Code Quality

• Real data throughout (no synthetic/mock data)
• Progress feedback for long operations
• Visual confirmation of working code
• Performance optimized for student experience
• Clean exports (development richness separate from package)

Educational Quality

• Clear learning progression (Build → Use → [Pattern])
• Immediate feedback and validation
• Real-world relevance and connections
• Comprehensive guidance (approach, examples, hints)
• Appropriate difficulty progression

Systems Quality

• Error handling and graceful failures
• Memory efficiency for large datasets
• Caching for repeated operations
• User experience considerations
• Production-ready patterns

🔄 Conversion & Export

Notebook Generation

• Convert to notebook: tito module notebooks --module {module}
• Verify notebook structure (cells, markdown, code)
• Test in Jupyter: Open and run the generated notebook

Package Integration

• Export to package: tito package sync --module {module}
• Verify package structure: Check tinytorch/core/
• Test imports: Import from package works correctly
• Run integration tests: All modules still work together

🎯 Final Verification

Student Experience

• Clear learning objectives achieved
• Immediate feedback throughout
• Real-world connections obvious
• Smooth difficulty progression
• Comprehensive guidance without being prescriptive

Technical Excellence

• All tests pass with real data
• Performance acceptable at realistic scales
• Clean code structure and organization
• Proper error handling and edge cases
• Integration works with existing modules

Production Readiness

• Real datasets used throughout
• Production patterns demonstrated
• Systems thinking integrated
• Performance considerations addressed
• User experience optimized

🚀 Release Checklist

Final Steps

• All tests pass: tito module test --module {module}
• Package exports: tito package sync --module {module}
• Documentation complete: README, docstrings, examples
• Integration verified: Works with other modules
• Student path tested: Follow your own guidance

Commit and Deploy

• Commit changes: Git commit with descriptive message
• Update main status: tito module status shows complete
• Verify CLI integration: All commands work correctly
• Test end-to-end: Full student workflow functions

---

💡 Remember: This is ML systems engineering education. Every module should reflect real-world practices while maintaining educational excellence. Students are building production-quality skills, not just academic exercises.