201-no-version-bloat

No Version Bloat Rule

• Purpose: Maintain clean architecture by preventing creation of duplicate "enhanced", "v2", or "_new" versions of existing files. Empirical Impact: Projects with version bloat show 45% higher maintenance costs and 3x longer onboarding time.

• Principle: Integrate improvements into existing files rather than creating parallel versions.

• Requirements:

  1. Before Creating New Files: Check if functionality belongs in existing file
  2. Naming Convention: Never use suffixes like "_enhanced", "_v2", "_new", "_improved"
  3. Consolidation First: If prototyping created temporary versions, consolidate immediately
  4. Git Strategy: Use branches for experimental features, not duplicate files
  5. Directory Organization: Enforce logical grouping to prevent file scatter:

     /project/
     ├── core_files.py          # Main functionality
     ├── /tests/                # All testing files
     ├── /scripts/              # Deployment & utilities  
     ├── /utils/                # Helper functions
     ├── /services/             # Business logic
     ├── /schemas/              # Data definitions
     └── /docs/                 # Documentation
     

  6. Stigmergic Version Tracking: Leave evolution markers in files:

     # EVOLUTION_TRAIL: basic_impl.v1 -> optimized.v2 -> current
     # DEPRECATED_FEATURES: old_method (removed 2025-01-02)
     # ENHANCEMENT_MARKER: Added caching support - 30% faster
     

  7. Version Decay Pattern: Temporary files auto-expire after 7 days:

     # TEMPORARY_FILE: expires 2025-01-09
     # PURPOSE: Testing new algorithm approach
     # MERGE_TARGET: main_module.py
     

  8. Duplicate Detection: Regularly scan for similar files:

     find . -name "*webhook*" | sort  # Find potential duplicates
     wc -l file1.py file2.py          # Compare file sizes
     

• Debugging Scenario Protocol (NEW):

  1. Temporary File Naming: Use debug_*, temp_*, or test_* prefixes for debugging files
  2. Immediate Cleanup Strategy: Set cleanup reminder when creating debugging files
  3. Consolidation Timeline: Consolidate within 24 hours of debugging completion
  4. Purpose-Specific Naming: test_official_spec.py > test_v2.py
  5. Test File Organization:

     /tests/
     ├── test_component_name.py     # Main component tests
     ├── test_integration.py        # Integration tests
     ├── test_debug_specific.py     # Specific debugging (temporary)
     └── conftest.py               # Shared fixtures
     

• Cleanup Protocol:

  1. Identify Duplicates: Use file size comparison and naming patterns
  2. Determine Primary: Choose most recent, feature-complete version
  3. Move Supporting Files: Organize tests, utils, scripts to proper directories
  4. Remove Obsolete: Delete older versions after verification
  5. Update Documentation: Reflect new organization in README/docs
  6. Test Consolidation: Merge related test files into comprehensive suites

• Validation:

  • Check: Are there any duplicate versions of core files?
  • Check: Do new features extend existing infrastructure?
  • Check: Is the codebase free of abandoned prototype files?
  • Check: Are files organized in logical directories?
  • Check: Do similar-named files serve distinct purposes?
  • Check: Are debugging/test files consolidated after completion?

• Examples:

  • ❌ BAD: Creating safir_enhanced.py alongside safir.py
  • ✅ GOOD: Adding enhanced methods to existing safir.py
  • ❌ BAD: llm_service_v2.py for new features
  • ✅ GOOD: Extending llm_service.py with new capabilities
  • ❌ BAD: webhooks/webhook_handler.py + webhook_handler.py (duplicates)
  • ✅ GOOD: Single webhook_handler.py with all functionality
  • ❌ BAD: test_webhook.py, test_webhook_v2.py, webhook_test_focused.py
  • ✅ GOOD: test_official_specification.py, test_production_integration.py (distinct purposes)