evolution-engine

---

name: evolution-engine description: Auto-triggers on session init, or manually triggered when the user says "check if there are any rules to upgrade" or "check evolution suggestions". Called by the evolution-runner sub-agent. version: 1.0.0 updated: 2026-05-26 requires: []

[Task] Scan the accumulated data in ../../feedback/ and identify three types of evolution signals: 1. Rule graduation: feedback repeats 3+ times -> propose upgrading to an official rule 2. Skill optimization: feedback scores for a particular Skill are consistently low -> propose adjusting the Skill 3. New Skill proposal: an operation pattern keeps recurring but no Skill covers it -> propose creating a new Skill

Signals found -> Generate proposals and return to the main Agent; execute after user confirmation.
No signals -> Return "no evolution suggestions".

[Not For] - Recording individual feedback entries -> use /feedback-writer instead - Creating new Skills -> use /skill-builder instead - Fixing bugs or code issues -> use /bug-fixer or /code-review instead

[Dependency Check] Automatically executed as the first step when the Skill starts.

Required:
- ../../feedback/FEEDBACK-INDEX.md → If missing, no feedback data exists; return "no evolution suggestions"
- At least one feedback file with occurrences >= 1 → If no feedback files exist, there is nothing to evolve
- .forge/editable-surface.json — Must exist and be readable. Defines directories/files the evolution engine is allowed to modify. If missing, create one with sensible defaults before proceeding.

Editable surface check (mandatory, before any proposal generation):
- Read .forge/editable-surface.json
- Verify that any proposed edit targets only paths listed under `editable.directories` or `editable.files`
- If a proposal would modify a path in `readonly`, reject it with reason: "path is outside editable surface"
- The editable-surface.json itself is in `readonly` — evolution engine cannot modify its own boundary definition

Optional:
- memory/ files → cross-reference task-history.md to validate whether pattern is real or coincidence

[First Principles] Data-Driven Evolution: No change without data. A single feedback entry is an anecdote, not a signal. Wait for the 3-occurrence threshold before proposing rule graduation. Let the data speak, not your intuition. Generator/Optimizer Recursion: The evolution engine is itself subject to evolution. The feedback-observer generates data (α), the evolution-engine optimizes rules (Ω). This cycle should recursively improve itself — the engine that proposes rule changes should also be evaluable and improvable through the same feedback loop. Minimum Lift: Prefer rule graduation (changing existing rules) over creating new Skills. A 3-line rule addition to an existing SKILL.md is faster to deploy and easier to maintain than a new Skill directory. Only propose new Skills when the pattern genuinely doesn't fit existing ones. Web-First: When proposing a new Skill or rule, WebSearch for existing best practices and community patterns. Don't invent from scratch what already has a well-known solution. Skill TDD Gate: Every proposal MUST include RED observation (what the Agent did without the rule), GREEN change (exact target file/section), Predicted effect, and Verify by. Proposals missing RED or Verify by are incomplete — do not present them to the user.

[Model Staleness Detection] When a feedback entry contains a model_version field that differs from the version used when the target Skill was written:

- Prioritize "rule outdated (model no longer needs this guidance)" over "rule needs strengthening"
- Check: is the same failure pattern still reproducible with the newer model? If not → propose rule retirement rather than rule graduation
- Record the model version delta in the proposal metadata