Add comprehensive ergonomics overhaul plan for fugue-evo

[alexnodeland]

Summary

This PR adds a detailed planning document outlining a comprehensive ergonomics overhaul for the fugue-evo library. The plan addresses critical developer experience (DX) issues that currently limit adoption, including complex builder APIs, unclear entry points, and excessive boilerplate.

Key Changes

• Tiered API Design: Proposes three-level API hierarchy from simple quick-start (fugue_evo::quick) to advanced control (fugue_evo::algorithms)
• Quick API Module (Phase 1): New simplified interface for common optimization tasks with sensible defaults, enabling single-line optimization for basic use cases
• Builder Simplification (Phase 2): Reduces SimpleGABuilder from 7 type parameters to 1 by using boxed traits and runtime validation instead of typestate pattern
• Sensible Defaults (Phase 3): Adds recommended() constructors to operators and with_defaults() to builders, plus heuristic helpers for parameter selection
• Iterator & Callback APIs (Phase 4): Introduces .steps() iterator for step-by-step evolution control and callback trait for event-driven programming
• Trait Decoupling (Phase 5): Splits EvolutionaryGenome into Genome (core), TracedGenome (Fugue integration), and marker traits to eliminate unnecessary dependencies
• Unified Parallel Traits (Phase 6): Consolidates parallel/non-parallel trait definitions to prevent silent breakage from feature flags
• Improved Error Messages (Phase 7): Enhances error types with actionable help text and context-specific guidance

Implementation Details

The plan includes:

• Concrete code examples for each phase showing before/after API usage
• Detailed acceptance criteria for validating each phase
• Testing strategy covering unit, integration, and documentation tests
• Migration guide for existing users
• Success metrics focused on reducing boilerplate and improving discoverability

The document is structured as a phased rollout plan with clear priorities (P0-P2), estimated scope, and file locations for implementation.

https://claude.ai/code/session_01MmK7YZeUdf6tPGVnDswCux