---
description: "Evolution engine. Analyzes session observation logs to detect failure patterns and weak tools, then auto-generates targeted skills in $HARNESS_DIR/evolved/. Sub-commands: /evolve (run now), /evolve status (dashboard), /evolve history (trend + skill attribution), /evolve cross-project, /evolve rollback, /evolve reset."
---

# /evolve — Manual Evolution Trigger

You are the **Evolution Engine** — analyze past sessions to improve skills.

**CRITICAL**: All data lives under the harness data directory. You MUST run `epic-harness path` first and use its output as the base path. NEVER use `.harness/` in the project directory — that is wrong.

## Sub-commands

### `/evolve` (default) — Run evolution now
1. Run `HARNESS_DIR=$(epic-harness path)` first, then use `$HARNESS_DIR/obs/` etc.
2. Read observation logs from `$HARNESS_DIR/obs/`
2. Analyze failure patterns across all sessions
3. Identify weak areas (error types, recurring failures)
4. Generate or improve evolved skills in `$HARNESS_DIR/evolved/`
5. Gate: validate new skills (format, dedup, cap of 10)
6. Report what changed

### `/evolve status` — Show evolution dashboard

Read `$HARNESS_DIR/metrics.json` and `$HARNESS_DIR/evolution.jsonl`, then display:

```
## Evolution Dashboard

### Overview
- Sessions analyzed: {total_sessions}
- Average success rate: {avg_success_rate}%
- Best score: {best_score} (session: {best_session})
- Trend: {trend} ({score_history.length} data points)
- Stagnation count: {stagnation_count} / 3 (rollback at 3)

### Score History (last 5 sessions)
| Session | Success Rate | Avg Score | Observations | Tool Success | Output Quality |
|---------|-------------|-----------|--------------|-------------|---------------|
(read score_history array, show dimension_averages for each)

### Evolved Skills
(list $HARNESS_DIR/evolved/*/SKILL.md with name and description from frontmatter)

### Last Session Analysis
(read last entry from evolution.jsonl)
- Error patterns: {error_patterns}
- Failure patterns: {failure_patterns[].pattern_type}
- Skills seeded: {skills_seeded}
- Skills rolled back: {skills_rolled_back}
- Analysis: {analysis_summary}
```

### `/evolve history` — Long-term analysis (#5)

Read `$HARNESS_DIR/evolution.jsonl` (full history, no 50-session cap), then display:

```
## Evolution History

### Trend Over Time
(Plot success_rate over all sessions — use text sparkline or table)

| Session # | Date | Success Rate | Avg Score | Skills | Patterns |
|-----------|------|-------------|-----------|--------|----------|
(each row = one evolution.jsonl entry)

### Cumulative Pattern Frequency
(Aggregate all failure_patterns across all sessions)
| Pattern | Total Count | First Seen | Last Seen |
|---------|-------------|------------|-----------|

### Skill Effectiveness (#6)
Read `$HARNESS_DIR/metrics.json` → `skill_attribution`, then display:
| Skill | Sessions Active | Avg Score With | Avg Score Without | Delta |
|-------|----------------|----------------|-------------------|-------|
(highlight positive delta = effective, negative = consider removing)

### Dispatch Analysis (#7)
Read `$HARNESS_DIR/dispatch/dispatch_*.jsonl`, then display:
| Skill | Times Invoked | Top Trigger Signals |
|-------|--------------|---------------------|
```

### `/evolve cross-project` — Cross-project patterns (#2)

Read `~/.harness-global/patterns.jsonl`, then display:
```
## Cross-Project Patterns

### Weak Tools Across Projects
| Tool | Projects Affected | Frequency |
|------|-------------------|-----------|

### Common Error Patterns
| Error Type | Projects | Total Occurrences |
|------------|----------|-------------------|
```

To opt-in: create `$HARNESS_DIR/.cross-project-enabled` file.
To opt-out: remove it.

### `/evolve rollback` — Undo last evolution
1. If `$HARNESS_DIR/evolved_backup/` exists, restore it to `$HARNESS_DIR/evolved/`
2. Otherwise, read `$HARNESS_DIR/evolution.jsonl` for last entry, remove skills seeded in that entry
3. Append a rollback record to evolution.jsonl
4. Report what was rolled back

### `/evolve reset` — Clear all evolution data
1. Remove `$HARNESS_DIR/evolved/`, `$HARNESS_DIR/evolved_backup/`
2. Clear `metrics.json` and `evolution.jsonl`
3. Confirm with user first

## How Evolution Works

The evolution loop runs automatically at session end (via `reflect` hook).
This command lets you trigger it manually or inspect the state.

```
Observe (PostToolUse — multi-dimensional scoring)
    ↓ $HARNESS_DIR/obs/session_YYYYMMDD.jsonl
Analyze (SessionEnd or /evolve)
    ↓ SessionAnalysis: per-tool, per-ext, score distribution
    ↓ Pattern detection: repeated_same_error, fix_then_break, long_debug_loop, thrashing
Seed (auto-generate targeted skills)
    ↓ 4 seeding paths: pattern / weak tool / weak file type / high-freq error
Gate (validate: format, dedup, cap of 10)
    ↓ Stagnation check: 3 sessions no improvement → rollback to best checkpoint
Reload (next session resume.ts reports metrics + loads evolved skills)
```

## Scoring System
- **Composite**: `0.5 × tool_success + 0.3 × output_quality + 0.2 × execution_cost`
- **Failure classification**: 9 categories (type_error, syntax_error, test_fail, lint_fail, build_fail, permission_denied, timeout, not_found, runtime_error)
- **Pattern detection**: 4 types (repeated_same_error, fix_then_break, long_debug_loop, thrashing)

## Red Flags
- Evolving after only 1-2 observations (not enough data)
- Keeping evolved skills that never trigger
- Not reviewing evolved skills periodically
- Ignoring stagnation warnings
