Create unified module template preserving educational depth

- Recognized that original module structure is MORE comprehensive than 5 C's
- Created UNIFIED_MODULE_TEMPLATE.md showing how to combine both approaches
- 5 C's becomes optional checkpoint, not mandatory duplication
- Preserves unique elements: 'Where This Code Lives', Build→Use→Understand
- Updated Module Developer agent to reflect this nuanced approach

Key insight: Don't sacrifice educational depth for structural consistency.
The original verbose explanations are valuable and should be preserved.
This commit is contained in:
Vijay Janapa Reddi
2025-09-15 19:15:58 -04:00
parent 7b0cfd2bb9
commit b733c468fc
2 changed files with 220 additions and 6 deletions

View File

@@ -74,12 +74,15 @@ After EVERY implementation:
3. Use pattern: `test_unit_[function_name]()`
4. Run test at cell bottom
### The 5 C's Before Every Code Block
1. **Context**: Why are we doing this?
2. **Concept**: What is this technically?
3. **Connection**: How does this relate to what they know?
4. **Concrete**: Specific example with real values
5. **Confidence**: What success looks like
### The 5 C's as Optional Checkpoint
The 5 C's can be used as a quick implementation checkpoint, but should NOT duplicate existing content:
1. **Context**: Why are we doing this? (if not already covered)
2. **Concept**: What is this technically? (if needs clarification)
3. **Connection**: How does this relate to what they know? (if adds value)
4. **Concrete**: Specific example with real values (if helpful)
5. **Confidence**: What success looks like (if not obvious)
**IMPORTANT**: If these topics are already covered in the module's educational sections, don't repeat them. The 5 C's is a tool, not a requirement.
## Responsibilities

211
UNIFIED_MODULE_TEMPLATE.md Normal file
View File

@@ -0,0 +1,211 @@
# Unified Module Template for TinyTorch
## Philosophy
We combine deep educational content with consistent structure. The 5 C's framework is used as an optional quick reference, not as a replacement for comprehensive explanations.
## The Module Stencil
```python
# ---
# jupyter:
# jupytext:
# text_representation:
# extension: .py
# format_name: percent
# format_version: '1.3'
# jupytext_version: 1.17.1
# ---
# %% [markdown]
"""
# Module XX: [Name] - [One-line Description]
[Welcome message and module overview]
## Learning Goals
- [Specific learning objective 1]
- [Specific learning objective 2]
- [Specific learning objective 3]
## Build → Use → Understand
1. **Build**: [What we're building]
2. **Use**: [How we'll use it]
3. **Understand**: [What we'll understand]
"""
# %% nbgrader={"grade": false, "locked": false, "schema_version": 3, "solution": false}
# Imports and setup
# %% [markdown]
"""
## 📦 Where This Code Lives in the Final Package
**Learning Side:** You work in `modules/source/XX_name/name_dev.py`
**Building Side:** Code exports to `tinytorch.core.name`
```python
# Final package structure example
from tinytorch.core.name import MainClass
```
**Why this matters:**
- **Learning:** [Educational benefit]
- **Production:** [How it relates to real systems]
- **Consistency:** [Package organization]
- **Foundation:** [How other modules depend on this]
"""
# %% [markdown]
"""
## Part 1: Understanding [Concept Name]
### [Theoretical/Mathematical Foundation]
[Deep dive into the theory - as detailed as needed]
### Why This Matters in ML/Neural Networks
[Connection to practical ML applications]
### Real-World Examples
[Domain-specific examples: Computer Vision, NLP, etc.]
"""
# %% [markdown]
"""
## Part 2: Design & Architecture
### Why Not Just Use [Alternative Library]?
[Justification for building from scratch]
### Design Requirements
[What our implementation needs to handle]
### Performance Considerations
[Memory, speed, optimization notes]
### Implementation Strategy
[How we'll approach building this]
"""
# %% [markdown]
"""
## Part 3: Implementation
### Implementation Checkpoint (Optional Quick Reference)
If helpful as a summary before coding:
- **What**: [Core concept in one line]
- **How**: [Code structure overview]
- **Like**: [Similar to PyTorch's X, TensorFlow's Y]
- **Must**: [Key constraints to remember]
- **Why**: [Impact on ML systems]
"""
# %% nbgrader={"grade": false, "locked": false, "schema_version": 3, "solution": true}
# Core Implementation with:
# - TODO: Clear task description
# - APPROACH: Step-by-step guide
# - EXAMPLE: Concrete example
# - HINTS: Implementation tips
# - BEGIN SOLUTION / END SOLUTION blocks
# %% [markdown]
"""
## Part 4: Testing Your Implementation
### [Test Category 1]
[Explanation of what we're testing and why]
"""
# %% nbgrader={"grade": true, "locked": true, "points": N, "schema_version": 3}
# Test implementation
# %% [markdown]
"""
## Module Summary
### ✅ What You've Built
[Summary of implementations]
### ✅ Key Learning Outcomes
[What students learned]
### ✅ Real-World Connection
[How this relates to production systems]
### 🚀 What's Next
[Preview of next module]
"""
```
## Key Principles
### 1. Educational Depth First
- Don't sacrifice explanation for structure
- It's okay to be verbose if it aids understanding
- Real-world examples are crucial
### 2. Avoid Duplication
- If content fits naturally in existing sections, don't repeat it
- The 5 C's is optional - use only if it adds value as a checkpoint
- Map concepts to where they naturally belong
### 3. Consistent Flow
```
Theory/Understanding → Design/Architecture → Implementation → Testing → Summary
```
### 4. Unique TinyTorch Elements to Preserve
- **"Where This Code Lives"**: Shows the learning-to-production path
- **Build → Use → Understand**: Our pedagogical framework
- **Real-world connections**: Links to PyTorch, TensorFlow, etc.
- **Performance considerations**: Systems thinking
### 5. When to Use the 5 C's
Use the condensed 5 C's checkpoint when:
- Starting a complex implementation
- Students need a quick reference
- It provides a helpful summary without duplication
Skip it when:
- The content is already covered in detail above
- It would be redundant
- The implementation is straightforward
## Module Categories
### Foundation Modules (01-05)
- More mathematical foundation
- Detailed explanations of core concepts
- Extensive "Why not just use X?" sections
### System Modules (06-10)
- Focus on architecture and design patterns
- Performance becomes more critical
- Integration between components
### Advanced Modules (11-14)
- Real-world optimizations
- Production considerations
- Industry best practices
## Flexibility Within Consistency
While maintaining this structure, each module can:
- Expand sections that are most relevant
- Add module-specific sections as needed
- Adjust depth based on complexity
- Include additional examples for difficult concepts
## The Goal
Create modules that:
1. Teach deeply, not just functionally
2. Connect theory to practice
3. Build systematic understanding
4. Prepare students for real ML engineering
5. Maintain consistent structure without sacrificing content
## Remember
**We're not trying to make modules shorter or more streamlined at the cost of education.**
We're organizing rich educational content in a consistent, learnable structure. If a module needs 1000 lines to properly teach a concept, that's perfectly fine. The structure helps students navigate, not limit content.