Self-Evolving

## When to Use

User wants the agent to improve a repeated workflow without blind self-rewrites. The skill handles local experiment logs, promotion of proven patterns, and explicit value gates before a new behavior becomes stable.

## Architecture

Memory lives in `~/self-evolving/`. If `~/self-evolving/` does not exist, run `setup.md`. See `memory-template.md`, `memory.md`, `experiments.md`, `evolution-loop.md`, and `boundaries.md` for the operating model.

```text
~/self-evolving/
├── memory.md        # HOT: stable rules, guardrails, activation cues
├── experiments.md   # WARM: tentative mutations and outcomes
└── archive/         # COLD: retired patterns and old experiments
```

## Quick Reference

| Topic | File |
|-------|------|
| Setup guide | `setup.md` |
| Memory template | `memory-template.md` |
| Hot memory baseline | `memory.md` |
| Experiment log format | `experiments.md` |
| Evolution cycle | `evolution-loop.md` |
| Safety boundaries | `boundaries.md` |

## Requirements

- No credentials required
- No extra binaries required
- No network access required

## Core Rules

### 1. Start From Real Friction
- Evolve only after a failed attempt, repeated correction, or measurable bottleneck.
- Do not invent mutations just because a task feels interesting.

### 2. Change One Lever at a Time
- Test one prompt pattern, decision rule, retrieval step, or file habit per experiment.
- Small mutations make the winning variable obvious.

### 3. Gate by Value, Not Novelty
- Promote a pattern only when it improves speed, quality, or reliability across at least three comparable uses.
- Unproven ideas stay tentative in `experiments.md`.

### 4. Keep Local Evidence
- Record the trigger, mutation, outcome, and next action for every experiment.
- Tell the user before the first persistent write that this skill keeps concise local notes for repeat improvement.
- Promote durable rules into `memory.md` only after evidence repeats.

### 5. Prefer Promotion Over Rewrite
- Convert winners into short rules, checklists, or retrieval triggers.
- Stable systems compound by accumulation, not by starting over.

### 6. Respect Hard Boundaries
- Follow `boundaries.md` before storing data or changing behavior.
- Never modify the installed skill files, exfiltrate unrelated data, or run hidden experiments on the user.

## Common Traps

| Trap | Why It Fails | Better Move |
|------|--------------|-------------|
| Rewriting the whole workflow after one mistake | You cannot isolate what actually helped | Test one mutation and compare against the previous baseline |
| Promoting an idea after one good run | Lucky wins become noisy defaults | Wait for three comparable wins before promotion |
| Logging vague lessons like "be smarter" | Future retrieval becomes useless | Write the exact trigger, decision, and expected outcome |
| Optimizing for novelty instead of value | The system churns without compounding | Keep only behaviors that measurably save time or reduce errors |
| Learning from silence | Lack of complaint is not proof | Require explicit feedback or repeated success evidence |

## Security & Privacy

**Data that leaves your machine:**
- None by default

**Data that stays local:**
- Stable rules, guardrails, and activation notes in `~/self-evolving/memory.md`
- Tentative experiments and outcomes in `~/self-evolving/experiments.md`
- First-time local storage should be announced before the first write

**This skill does NOT:**
- Call external APIs
- Read or store credentials
- Modify its own installed instructions
- Read unrelated files outside the active task plus `~/self-evolving/`

## Related Skills
Install with `clawhub install <slug>` if user confirms:
- `self-improving` — learn from corrections and compound execution quality over time
- `memory` — keep durable long-term context and retrieval patterns
- `decide` — compare options and commit to a clear next move
- `learning` — structure deliberate practice and feedback loops
- `proactivity` — follow through on next steps once a better pattern is chosen

## Feedback

- If useful: `clawhub star self-evolving`
- Stay updated: `clawhub sync`