---
description: Progressive enhancement approach for iterative feature development
globs: **/*.py, **/*.js, **/*.ts, **/*.html, **/*.css, **/*.md, **/*.sh, **/*.py.jinja
alwaysApply: false
---

# Progressive Enhancement Rule

## Core Principles
- **Start Simple**: Begin with the simplest implementation that delivers value
- **Iterative Improvement**: Add complexity and features in subsequent versions
- **Backward Compatibility**: Maintain compatibility between versions
- **Feature Flagging**: Use configuration and toggles for controlled rollout

## Implementation Patterns

### Version Progression
```python
# ✅ DO: Implement features progressively
# Version 1: Basic functionality
class TranscriptionService_v1:
    """Basic transcription service with core functionality."""
    
    def transcribe(self, audio_file: Path) -> str:
        """Transcribe audio to text using basic model."""
        # Simple implementation with basic accuracy
        return whisper.transcribe(audio_file, model="base")

# Version 2: Enhanced with more features
class TranscriptionService_v2:
    """Enhanced transcription with speaker diarization."""
    
    def transcribe(self, audio_file: Path) -> Dict[str, Any]:
        """Transcribe audio with speaker identification."""
        # Basic transcription (maintaining v1 capability)
        text = whisper.transcribe(audio_file, model="medium")
        
        # Enhanced feature: speaker diarization
        speakers = self._identify_speakers(audio_file)
        
        # Return enhanced result while maintaining compatibility
        return {
            "text": text,  # v1 compatibility
            "speakers": speakers  # v2 enhancement
        }
```

### Feature Flagging
```python
# ✅ DO: Use feature flags for controlled rollout
class TranscriptionService:
    def __init__(self, config: Dict[str, Any]):
        self.config = config
        # Feature flags control which enhancements are enabled
        self.enable_diarization = config.get("enable_diarization", False)
        self.enable_sentiment = config.get("enable_sentiment", False)
        self.model_version = config.get("model_version", "base")
    
    def transcribe(self, audio_file: Path) -> Dict[str, Any]:
        """Transcribe with progressive enhancements based on flags."""
        result = {"text": self._basic_transcribe(audio_file)}
        
        # Progressively add features based on flags
        if self.enable_diarization:
            result["speakers"] = self._identify_speakers(audio_file)
            
        if self.enable_sentiment:
            result["sentiment"] = self._analyze_sentiment(result["text"])
            
        return result
```

### Anti-Patterns
```python
# ❌ DON'T: Build everything at once
class ComplexService:
    """Service that tries to implement all features at once."""
    def __init__(self):
        # Initializing too many complex components at once
        self.transcriber = AdvancedTranscriber()
        self.diarizer = SpeakerDiarizer()
        self.sentiment_analyzer = SentimentAnalyzer()
        self.summarizer = TextSummarizer()
        self.translator = LanguageTranslator()
        # Too much complexity to test and maintain effectively
        
# ❌ DON'T: Make breaking changes between versions
# Version 1
def process(data: Dict[str, Any]) -> str:
    return data["text"]

# Version 2 (breaking change)
def process(data: Dict[str, Any]) -> Dict[str, Any]:  # Changed return type!
    return {"processed": data["text"]}  # Clients expecting string will break
```

When developing new features or systems, always begin with the simplest possible implementation that delivers core value. Gradually introduce additional layers of complexity and enhancements in subsequent iterations. Start with a minimal, functional version (v1), then incrementally add improvements such as performance optimizations, automation, advanced integrations, or other value-adding capabilities (v2, v3, etc.). Ensure that each new version builds upon the previous one without introducing breaking changes, maintaining backward compatibility. Use clear mechanisms—such as configuration flags, versioning, or feature toggles—to manage the rollout and adoption of new capabilities. This approach applies to all types of features, technologies, and domains, not just specific to any one area.