TinyTorch/.cursorrules

# NBDev Educational Pattern for TinyTorch Modules

When working with module development files (`*_dev.py`), follow this educational structure:

## File Format
Use Jupytext percent format with NBDev directives:

```python
# ---
# jupyter:
#   jupytext:
#     text_representation:
#       extension: .py
#       format_name: percent
#       format_version: '1.3'
#       jupytext_version: 1.17.1
# ---

# %% [markdown]
"""
# Module X: Title - Brief Description

Educational introduction and learning goals...
"""

# %%
#| default_exp core.component_name

# Setup and imports
import required_libraries

# %% [markdown]
"""
## Step 1: Concept Explanation
Educational content explaining the concept...
"""

# %%
#| export
class ComponentName:
    """
    Component description.
    
    TODO: Student implementation instructions.
    """
    def method(self):
        raise NotImplementedError("Student implementation required")

# %%
#| hide
#| export  
class ComponentName:
    """Complete implementation (hidden from students)."""
    def method(self):
        # Actual implementation
        pass
```

## Key NBDev Directives

- `#| default_exp core.module` - Sets export destination in tinytorch package
- `#| export` - Marks code for export to package
- `#| hide` - Hides cell from students (instructor solution)
- `# %% [markdown]` - Markdown cells for explanations
- `# %%` - Code cells

## Educational Structure

### 1. **Conceptual Foundation** (REQUIRED)
Each module must start with clear conceptual explanations:

```markdown
## Step 1: What is [Concept]?

**Definition**: Clear, simple definition with examples
**Why it matters**: Real-world motivation and ML context
**How it works**: Intuitive explanation before math
**Visual examples**: Concrete examples, diagrams, analogies
**Connection**: How it builds on previous modules
```

### 2. **Guided Implementation** (REQUIRED)
Instead of just `raise NotImplementedError`, provide:

```python
def method(self):
    """
    TODO: Step-by-step implementation guide
    
    HINTS:
    1. First, think about what this method should return
    2. Consider the data types and shapes involved
    3. Start with a simple case, then generalize
    
    EXAMPLE:
    Input: [describe input]
    Expected output: [describe expected output]
    """
    # Step 1: [specific guidance]
    # Step 2: [specific guidance] 
    # Step 3: [specific guidance]
    raise NotImplementedError("Student implementation required")
```

### 3. **Standalone Learning** (REQUIRED)
Each module should be self-contained:
- Brief concept review (even if covered in textbook)
- Clear motivation for why this matters
- Concrete examples before abstract implementation
- Connection to previous modules and next steps

### 4. **Educational Flow** (REQUIRED)
Follow this structure for every module:

1. **Concept → Motivation → Intuition → Implementation → Testing**
2. **Visual examples** (shapes, transformations, operations)
3. **Real-world analogies** (containers, functions, pattern matching)
4. **Scaffolded complexity** (start simple, build up)

### 5. **Implementation Guidance** (REQUIRED)
For each TODO section, include:

```python
"""
TODO: [Clear task description]

APPROACH:
1. [First step with specific guidance]
2. [Second step with specific guidance]
3. [Third step with specific guidance]

EXAMPLE:
Input: [concrete example]
Expected: [concrete expected output]
Your code should: [specific behavior description]

HINTS:
- [specific hint 1]
- [specific hint 2]
- [specific hint 3]
"""
```

### 6. **Testing and Feedback** (REQUIRED)
Include immediate testing cells:
- Simple test cases with expected outputs
- Clear error messages for debugging
- Progressive complexity (simple → complex)
- Visual verification where possible

## Naming Convention

Module files should be named `{module_name}_dev.py` to indicate development notebooks, following the established pattern from [modules/setup/setup_dev.py](mdc:modules/setup/setup_dev.py) and [modules/tensor/tensor_dev.py](mdc:modules/tensor/tensor_dev.py).

## Educational Principles

1. **Build → Use → Understand → Repeat**: Each module should follow this cycle
2. **Immediate Feedback**: Students should see results quickly
3. **Concrete Before Abstract**: Start with examples, then generalize
4. **Scaffolded Learning**: Provide hints and guidance, not just empty functions
5. **Standalone Modules**: Each module should be understandable independently
6. **Visual Learning**: Include diagrams, examples, and visualizations
7. **Real-world Context**: Connect to practical ML applications