evolution-engine - SKILL.md Agent Skill

name: evolution-engine description: > Autonomous learning and verification system. Triggers on: - Session start (runs verification sweep) - User corrections ("no", "wrong", "I told you", "we don't do that") - Task completion (session scoring) - Discoveries during work (hypothesis verification) - User explicit ("remember this", "add this as a rule") allowed-tools: Read, Write, Edit, Grep, Glob, Bash

Evolution Engine

You are not a journal. You are an immune system. You verify, enforce, and learn autonomously.

SECTION 1: VERIFICATION SWEEP (run at session start)

Before starting any complex task, run every rule's verification check. Do this silently. Only surface failures.

How It Works

Read .claude/memory/learned-rules.md. Every rule that has a verify: line gets executed as a grep/glob/check. Rules without verify: lines are technical debt — add one.

Example rule format in learned-rules.md:

- Never use {headers: merged, ...options} in fetchJSON. Always destructure first.
  verify: Grep("\.\.\.options", path="frontend/src/api/client.js") → 0 matches expected
  [source: corrected 2x, 2026-03-28]

Verification Protocol

Read learned-rules.md. For each rule with a verify: line:

Run the check (Grep, Glob, or Read).
PASS: Silent. Move on.

FAIL: Log to .claude/memory/violations.jsonl:

{"timestamp": "[now]", "rule": "[rule text]", "check": "[what was run]", "result": "[what was found]", "file": "[where]", "auto_fixed": false}

Surface violations to the user as a block:

RULE VIOLATIONS DETECTED:
- [rule]: found [violation] in [file:line]
  → fix: [specific fix]

If ALL checks pass, say nothing. The best immune system is invisible.

Track pass rates in .claude/memory/sessions.jsonl:

{"date": "[today]", "rules_checked": 8, "rules_passed": 8, "rules_failed": 0, "violations": []}

Rules Without Verification

If a rule in learned-rules.md has no verify: line, add one. Every rule must be machine-checkable. If you can't write a check for it, the rule is too vague — rewrite it until you can.

Verification patterns:

Code pattern banned: Grep("[pattern]", path="[scope]") → 0 matches
Code pattern required: Grep("[pattern]", path="[scope]") → 1+ matches
File must exist: Glob("[pattern]") → 1+ matches
File must not exist: Glob("[pattern]") → 0 matches
Function length: Read [file], count lines in [function] → max N

SECTION 2: HYPOTHESIS-DRIVEN OBSERVATIONS

Never log a guess. Verify it immediately or don't log it.

Protocol

When you notice a pattern during work:

Formulate as testable claim. Not "I think store methods use this.set()" but "All state updates in store.js go through this.set()."
Test it immediately.
- Grep for counter-examples.
- Read the relevant files.
- Count occurrences vs. exceptions.

Record with evidence.

// .claude/memory/observations.jsonl
{
  "timestamp": "[now]",
  "type": "convention",
  "hypothesis": "All state updates in store.js use this.set()",
  "evidence": "Grep found 23 this.set() calls, 0 direct property assignments",
  "counter_examples": 0,
  "confidence": "confirmed",
  "file_context": "frontend/src/api/store.js",
  "verify": "Grep('this\\.[a-z]+ =(?!=)', path='frontend/src/api/store.js') → 0 matches"
}

Auto-promote confirmed observations.
- confirmed + 0 counter-examples → add directly to learned-rules.md WITH a verify line.
- Tell the user: "Verified and added as rule: [rule]. Check: [verify pattern]."
- No need to wait for /project:evolve.
Low-confidence observations still get logged, but flagged for future verification:
```
{"confidence": "low", "recheck_after": "3 sessions", ...}
```

SECTION 3: CORRECTION CAPTURE (same as before, but with auto-verification)

When the user corrects you:

Acknowledge naturally.

Log to .claude/memory/corrections.jsonl:

{"timestamp": "[now]", "correction": "[what]", "context": "[what you were doing]", "category": "[category]", "times_corrected": 1, "verify": "[auto-generated check if possible]"}

Generate a verify pattern immediately. If the correction is "don't do X", the check is Grep("[X pattern]") → 0 matches. If you can't generate a check, note "verify": "manual" — this is debt to resolve during /project:evolve.
Same promotion rules:
- 1st time: Log.
- 2nd time (same pattern): Auto-promote to learned-rules.md WITH verify line.
- Already in learned-rules: Check if verification exists. If not, add it now.
Apply the correction immediately.

SECTION 4: SESSION SCORING (run at session end or before commit)

When the user is wrapping up, or before a commit, write a session scorecard:

// .claude/memory/sessions.jsonl
{
  "date": "[today]",
  "session_number": "[increment from last entry]",
  "corrections_received": 2,
  "rules_checked": 8,
  "rules_passed": 7,
  "rules_failed": 1,
  "violations_found": ["fetchJSON-headers in new endpoint"],
  "violations_fixed": ["fetchJSON-headers in new endpoint"],
  "observations_made": 1,
  "observations_verified": 1,
  "rules_added": 0,
  "rules_promoted": 0
}

Trend Detection

If sessions.jsonl has 5+ entries, check:

Corrections decreasing? System is working.
Corrections flat or increasing? Rules aren't being consulted or are too vague. Flag for /project:evolve.
Same violation recurring? The verify check exists but the fix isn't sticking. Escalate: this needs to move from learned-rules to CLAUDE.md or become a linter rule.
Rules growing past 40? Warn that graduation is needed soon.

Surface the trend in one line: "Session 12: 0 corrections (down from 3 avg). 8/8 rules passing."

SECTION 5: EXPLICIT "REMEMBER THIS"

When the user asks you to remember something:

Rewrite it as a testable rule.
Generate a verify pattern.

Add to learned-rules.md in the format:

- [Rule text]
  verify: [check]
  [source: user-explicit, DATE]

Confirm: "Added rule: [rule]. Verification: [check]. Will auto-enforce from now on."

If you can't make it machine-checkable, say so: "Added as a manual rule. I'll follow it but can't auto-verify — consider rephrasing so I can write a grep check."

CAPACITY MANAGEMENT

Before adding to learned-rules.md:

Count lines. Max 50.
If approaching 50, check which rules have passed 10+ consecutive sessions → candidates for graduation to CLAUDE.md or rules/.
Check which rules have verify: manual → candidates for rewriting or pruning.
Suggest /project:evolve if at capacity.

THE PRINCIPLE

A rule without a verification check is a wish. A rule with a verification check is a guardrail. Only guardrails survive.