Iterative Code Evolution

A structured methodology for improving code through disciplined reflect → mutate → verify → score cycles, adapted from the ALMA research framework for meta-learning code designs.

When to Use This Skill

• Iterating on code that isn't working well enough (performance, correctness, design)
• Optimizing an implementation across multiple rounds of changes
• Debugging persistent or recurring issues where simple fixes keep failing
• Evolving a system design through structured experimentation
• Any task where you've already tried 2+ approaches and need discipline about what to try next
• Building or improving prompts, pipelines, agents, or any "program" that benefits from iterative refinement

When NOT to Use This Skill

• Simple one-shot code generation (just write it)
• Mechanical tasks with clear solutions (refactoring, formatting, migrations)
• When the user has already specified exactly what to change

Core Concepts

The Evolution Loop

Every improvement cycle follows this sequence:

┌─────────────────────────────────────────────────────┐
│  1. ANALYZE  — structured diagnosis of current code │
│  2. PLAN     — prioritized, concrete changes        │
│  3. MUTATE   — implement the changes                │
│  4. VERIFY   — run it, check for errors             │
│  5. SCORE    — measure improvement vs. baseline     │
│  6. ARCHIVE  — log what was tried and what happened │
│                                                     │
│  Loop back to 1 with new knowledge                  │
└─────────────────────────────────────────────────────┘

The Evolution Log

Track all iterations in .evolution/log.json at the project root. This is the memory that makes each cycle smarter than the last.

{
  "baseline": {
    "description": "Initial implementation before evolution began",
    "score": 0.0,
    "timestamp": "2025-01-15T10:00:00Z"
  },
  "variants": {
    "v001": {
      "parent": "baseline",
      "description": "Added input validation and error handling",
      "changes_made": [
        {
          "what": "Added type checks on all public methods",
          "why": "Runtime crashes from malformed input in 3/10 test cases",
          "priority": "High"
        }
      ],
      "score": 0.6,
      "delta": "+0.6 vs parent",
      "timestamp": "2025-01-15T10:30:00Z",
      "learned": "Input validation was the primary failure mode — most other logic was sound"
    },
    "v002": {
      "parent": "v001",
      "description": "Refactored parsing logic to handle edge cases",
      "changes_made": [
        {
          "what": "Rewrote parse_input() to use state machine instead of regex",
          "why": "Regex approach failed on nested structures (seen in test cases 7,8)",
          "priority": "High"
        }
      ],
      "score": 0.85,
      "delta": "+0.25 vs parent",
      "timestamp": "2025-01-15T11:00:00Z",
      "learned": "State machine approach generalizes better than regex for this gra...