iterative-code-evolution

# 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.

```json
{
  "baseline": {
    "description": "Initial implementation before evolution began",
    "score": 0.0,
    "timestamp": "2025-01-15T10:00:00Z"
  },
  "variants": {
    "v001": {
      "parent": "baseline",
      "description": "...

# Iterative Code Evolution

A Claude Code skill that replaces ad-hoc "try and fix" coding with structured improvement cycles. Adapted from the [ALMA](https://yimingxiong.me/alma) (Automated meta-Learning of Memory designs for Agentic systems) research framework.

## Installation

### OpenClaw

Search for **Iterative Code Evolution** on [OpenClaw](https://clawhub.ai) and click **Install**, or run:

```bash
openclaw install iterative-code-evolution
```

### Claude Code (CLI)

Copy `SKILL.md` into your Claude Code skills directory:

```bash
# Global (available in all projects)
cp SKILL.md ~/.claude/skills/iterative-code-evolution.md

# Per-project (available only in that project)
mkdir -p your-project/.claude/skills
cp SKILL.md your-project/.claude/skills/iterative-code-evolution.md
```

### Claude Desktop / Claude.ai

1. Copy the contents of `SKILL.md`
2. Open **Claude Desktop** or **Claude.ai**
3. Navigate to **Settings** > **Custom Instructions**
4. Paste the contents into the custom instructions field
5. Save

## What It Does

When activated, Claude follows a disciplined loop instead of making random fixes:

```
ANALYZE → PLAN → MUTATE → VERIFY → SCORE → ARCHIVE → repeat
```

Each cycle:

1. **Analyze** — Reviews past attempts, labels each component (Working / Fragile / Broken / Redundant / Missing), checks for cross-cutting issues
2. **Plan** — Picks 1-3 evidence-based changes (no speculative fixes allowed)
3. **Mutate** — Implements only the planned changes
4. **Verify** — Runs the code; up to 3 retries on crashes, then reverts
5. **Score** — Measures improvement against the parent variant, not just the baseline
6. **Archive** — Logs everything to `.evolution/log.json`, including failures and lessons learned

## When to Use It

- Code that isn't working well enough after initial attempts
- Performance or correctness optimization across multiple rounds
- Persistent bugs where simple fixes keep failing
- Evolving a design through structured experimentation
- Any si...