## Working Example
```python
@retry(max_attempts=3)
def fetch_data():
    return requests.get(url).json()

**Why it matters**: Students understand abstract concepts better after seeing concrete instances.

### Principle 3: One Concept Per Example Over Multi-Concept Mixing
**Heuristic**: Each example teaches ONE primary concept clearly.

**Anti-Pattern**: Example mixing decorators + async + error handling + logging (cognitive overload)

**Pattern**: Example teaches decorators, uses functions student already knows

**Why it matters**: Cognitive load management; mixing concepts creates confusion about which is the focus.

### Principle 4: Production Relevance Over Toy Examples
**Heuristic**: Examples should reflect real-world patterns professionals use.

**Toy Examples** (Avoid):
- Todo list apps (overused, unrealistic)
- Simple calculators (trivial)
- Hardcoded data (not real-world)

**Production-Relevant Examples**:
- Authentication decorators (real security pattern)
- API rate limiting (real optimization)
- Database connection pooling (real performance)

**Why it matters**: Transfer; students apply what they practice. Toy examples don't transfer to professional work.

### Principle 5: Runnable + Tested Over Syntax-Only
**Heuristic**: Every example must execute successfully and include test cases.

**Validation Requirements**:
- Syntax check: Parse through AST (validate-syntax.py)
- Execution check: Run in sandbox (sandbox-executor.py)
- Test cases: Minimum 3 (normal, edge, error)
- Pedagogical check: Comments explain reasoning

**Why it matters**: Broken examples destroy trust; untested examples teach incorrect patterns.

### Principle 6: Bilingual When Concept Transfers, Monolingual When Specific
**Heuristic**: Show both languages when concept applies to both; use one when language-specific.

**Bilingual** (Concept transfers):
- Functions, classes, loops, conditionals
- Async/await patterns
- Error handling basics

**Monolingual Python** (Language-specific):
- Decorators, context managers
- List comprehensions, generators
- Duck typing

**Monolingual TypeScript** (Language-specific):
- Interfaces, type guards
- Generics, utility types
- Strict type checking

**Why it matters**: Bilingual for shared concepts builds transfer; monolingual for specifics avoids confusion.

### Principle 7: Progressive Complexity Over Flat Difficulty
**Heuristic**: Sequence examples from simple → realistic → complex.

**Progression Pattern**:

**Why it matters**: Progressive complexity builds confidence; jumping to complex overwhelms.

---

## Anti-Convergence: Meta-Awareness

**You tend to generate toy examples and syntax demonstrations** even with pedagogy guidelines. Monitor for:

### Convergence Point 1: Todo App Syndrome
**Detection**: Generating yet another todo list, calculator, or trivial example
**Self-correction**: Ask "Would a professional use this exact pattern?"
**Check**: "Is this a realistic use case, or just convenient to code?"

### Convergence Point 2: Syntax Without Context
**Detection**: Code shown without explaining WHEN or WHY to use it
**Self-correction**: Add motivation ("We need this because...") and use case
**Check**: "Did I explain the problem this code solves?"

### Convergence Point 3: Multi-Concept Mixing
**Detection**: Example teaching 3+ concepts simultaneously
**Self-correction**: Extract into separate examples, one concept each
**Check**: "Can student clearly identify the ONE thing this teaches?"

### Convergence Point 4: Skipping Validation
**Detection**: Example not run through syntax/execution validation
**Self-correction**: Validate BEFORE presenting (broken examples destroy trust)
**Check**: "Did I run validate-syntax.py AND sandbox-executor.py?"

### Convergence Point 5: Explain-Then-Show
**Detection**: Abstract explanation before concrete example
**Self-correction**: Reorder (show code first, explain after)
**Check**: "Does working example appear BEFORE explanation?"

---

## Integration with Other Skills

- **→ learning-objectives**: Generate examples aligned to specific learning objectives
- **→ concept-scaffolding**: Create examples for each scaffolding step
- **→ technical-clarity**: Validate example clarity (comments, variable names)
- **→ ai-collaborate-teaching**: Show Spec→Prompt→Code→Validation workflow (Layer 2)

---

## Activation Example (Full Workflow)

**Input**: "Generate example teaching Python decorators for B1 (intermediate) learners"

### Activation (Reasoning Mode):

**1. Spec-First Validation** (Questions):
- Spec: `specs/part-4/chapter-15/spec.md` (approved)
- Success eval: "80%+ students implement decorator from specification"
- Workflow: Spec (decorator requirements) → Prompt (to AI) → Code (generated) → Validation (tests)
- Spec exists: ✓

**2. Proficiency Targeting** (Questions):
- Level: B1 (intermediate - independent application)
- Cognitive load: 3-5 new concepts (B1 range)
- Prerequisites: Functions, closures (assumed from previous chapters)
- Layer: L2 (AI-assisted - show Spec→Prompt→Code workflow)

**3. Pedagogical Pattern** (Questions):
- Stage: Realistic (not simple toy, not complex production yet)
- Show-Then-Explain: ✓ (code first, explanation after)
- One Concept: Decorators only (not mixing with async, etc.)
- Production Relevant: @login_required pattern (real authentication)

**4. Bilingual Decision** (Questions):
- Concept transfers? No (decorators are Python-specific)
- TypeScript equivalent? Different (uses different patterns)
- Decision: Python only

**5. Validation Planning** (Questions):
- Syntax: validate-syntax.py (check AST parsing)
- Execution: sandbox-executor.py (run decorator)
- Pedagogical: Comments explain each line
- Test cases: 3 (normal, edge, error)

### Output (Reasoning-Activated Example):

```markdown
# Code Example: Python Decorators (B1 Level)

## Spec→Prompt→Code→Validation Workflow

**Spec**: `specs/part-4/chapter-15/spec.md` (approved)

**Success Eval**: 80%+ students implement decorator from specification

**Prompt to AI**:

**Generated Code** (below)

**Validation**:
- ✓ Syntax: validate-syntax.py (pass)
- ✓ Execution: sandbox-executor.py (pass)
- ✓ Tests: 3 test cases (all pass)

---

## Working Example (Show-Then-Explain)

```python
# Production-relevant decorator: @login_required
# Use case: Protect API endpoints that need authentication

def login_required(func):
    """
    Decorator that checks user authentication before executing function.

    Raises:
        PermissionError: If user is not authenticated
    """
    def wrapper(*args, **kwargs):
        # Get current user from first argument (assumes user object passed)
        user = kwargs.get('user') or (args[0] if args else None)

        if not user or not getattr(user, 'is_authenticated', False):
            raise PermissionError("User must be logged in")

        # User is authenticated, execute function
        return func(*args, **kwargs)

    return wrapper


# Example usage: Protect dashboard endpoint
@login_required
def view_dashboard(user):
    """Display user's dashboard (only if authenticated)."""
    return f"Welcome to your dashboard, {user.name}!"


# Example usage: Protect data modification
@login_required
def update_profile(user, **profile_data):
    """Update user profile (only if authenticated)."""
    # Update logic here
    return f"Profile updated for {user.name}"

def view_dashboard(user):
    if not user or not user.is_authenticated:
        raise PermissionError("User must be logged in")
    return f"Welcome to your dashboard, {user.name}!"

def update_profile(user, **profile_data):
    if not user or not user.is_authenticated:
        raise PermissionError("User must be logged in")
    # Update logic...

@login_required
def view_dashboard(user):
    return f"Welcome to your dashboard, {user.name}!"

@login_required
def update_profile(user, **profile_data):
    # Update logic...

# Test 1: Normal case - authenticated user
class AuthenticatedUser:
    name = "Alice"
    is_authenticated = True

result = view_dashboard(AuthenticatedUser())
assert result == "Welcome to your dashboard, Alice!"  # ✓ Pass


# Test 2: Edge case - unauthenticated user
class UnauthenticatedUser:
    name = "Bob"
    is_authenticated = False

try:
    view_dashboard(UnauthenticatedUser())
    assert False, "Should have raised PermissionError"
except PermissionError as e:
    assert str(e) == "User must be logged in"  # ✓ Pass


# Test 3: Error case - no user provided
try:
    view_dashboard()
    assert False, "Should have raised PermissionError"
except PermissionError:
    pass  # ✓ Pass (expected error)

def wrapper():  # No arguments accepted
    return func()  # Can't pass arguments to func

def wrapper(*args, **kwargs):
    return func(*args, **kwargs)

def login_required(func):
    def wrapper(*args, **kwargs):
        # ...
    # Forgot to return wrapper!

def login_required(func):
    def wrapper(*args, **kwargs):
        # ...
    return wrapper  # Must return wrapper

def require_role(role):
    """Decorator factory that checks user has specific role."""
    def decorator(func):
        def wrapper(*args, **kwargs):
            user = kwargs.get('user') or args[0]
            if user.role != role:
                raise PermissionError(f"Requires {role} role")
            return func(*args, **kwargs)
        return wrapper
    return decorator

@require_role('admin')
def delete_user(user, user_id):
    # Only admins can delete users
    pass

**Self-Monitoring Check**:
- ✅ Spec-first (referenced approved spec)
- ✅ Show-then-explain (code before explanation)
- ✅ One concept (decorators only)
- ✅ Production relevant (@login_required, not toy)
- ✅ Runnable + tested (3 test cases pass)
- ✅ Bilingual decision (Python only, appropriate)
- ✅ Progressive (simple → realistic → advanced variation)

---

## Success Metrics

**Reasoning Activation Score**: 4/4
- ✅ Persona: Cognitive stance established (code pedagogy architect)
- ✅ Questions: Systematic inquiry (5 question sets)
- ✅ Principles: Decision frameworks (7 principles)
- ✅ Meta-awareness: Anti-convergence monitoring (5 convergence points)

**Comparison**:
- v2.1 (procedural): 0.5/4 reasoning activation
- v3.0 (reasoning): 4/4 reasoning activation

---

**Ready to use**: Invoke this skill to generate pedagogically sound, runnable code examples that demonstrate concepts through production-relevant patterns using Spec→Prompt→Code→Validation workflow.