recommend-evolution

Recommend Evolution

Overview

Recommend ecosystem evolution when repeated evidence indicates missing capability, and record the recommendation in a standard machine-readable format.

When to Use

Reflection identifies recurring delivery failures with the same root cause

Router/analysis signals no suitable agent or skill for recurring requests

Repeated integration gaps imply missing artifact type or policy

User explicitly requests a new capability path

Iron Laws

NEVER

spawn evolution-orchestrator directly from this skill — this skill records recommendations only; execution decisions belong to the orchestrator and approval pipeline.

ALWAYS

validate trigger type against defined thresholds before recording a recommendation — vague observations are not triggers; require concrete failure counts or routing misses.

NEVER

create a new evolution request when artifact-integrator or skill-updater would address the gap — reserve evolution for net-new capabilities, not integration or update gaps.

ALWAYS

append the recommendation to the JSONL queue AND include the required report block in the current output — dual recording ensures the recommendation is discoverable at both runtime and review time.

NEVER

proceed with a recommendation without evidence — single failures are noise; trigger thresholds exist for a reason.

Trigger Taxonomy Note

recommend-evolution

uses a

cause-oriented trigger taxonomy

(

repeated_error

,

no_agent

,

integration_gap

,

user_request

,

rubric_regression

,

stale_skill

,

other

).

This intentionally differs from

skill-updater

, which uses a

caller-oriented trigger taxonomy

(

reflection

,

evolve

,

manual

,

stale_skill

) to describe who/what initiated the update path.

Step 0: Validate Trigger Type

Use these thresholds:

repeated_error

same class of failure in 5+ tasks

rubric_regression

repeated score drop below threshold for same class of task

no_agent

recurring need with no valid routing match

integration_gap

existing artifact integration missing (prefer artifact-integrator)

user_request

explicit request for capability not available

stale_skill

audit pipeline reports verified artifact older than 6 months or invalid lastVerifiedAt Step 1: Decide Recommendation Path If gap is integration of existing artifact, prefer: Skill({ skill: 'artifact-integrator' }) If gap is stale/underperforming existing skill, prefer: Skill({ skill: 'skill-updater' }) If gap requires net-new capability/artifact, continue with evolution recommendation If no artifact change needed, update memory only and exit Step 2: Create Standard Recommendation Payload Build one JSON object with required fields: { "timestamp" : "2026-02-14T00:00:00.000Z" , "source" : "reflection-agent" , "trigger" : "repeated_error" , "evidence" : "Same routing failure observed in 6 tasks over 2 days." , "suggestedArtifactType" : "skill" , "summary" : "Create a new routing-context skill for reflection-time grounding." , "status" : "proposed" } Schema reference: .claude/schemas/evolution-request.schema.json Step 3: Record Recommendation Append JSON line to: .claude/context/runtime/evolution-requests.jsonl Add required report block:

Evolution Recommendation

Trigger: < trigger

- Evidence: < evidence

- Suggested Artifact Type: < type|null

- Summary: <1-2 sentences> - Queue Record: .claude/context/runtime/evolution-requests.jsonl Step 3: Output Return recommendation summary and what was recorded. // Repeated failure pattern -> recommend skill creation Skill ( { skill : 'recommend-evolution' , args : '--trigger repeated_error --suggestedArtifactType skill' , } ) ; // Routing miss -> recommend new agent/workflow discussion Skill ( { skill : 'recommend-evolution' , args : '--trigger no_agent --suggestedArtifactType agent' } ) ; Anti-Patterns Anti-Pattern Why It Fails Correct Approach Spawning evolution-orchestrator directly from this skill Violates single-responsibility; bypasses approval and resource gates Record recommendation to JSONL queue only; let the orchestrator decide on execution Recording an evolution request for an integration gap that already has artifacts Creates unnecessary new artifacts when an integration fix would suffice Check artifact-integrator path first; escalate only if gap requires net-new capability Submitting a recommendation without trigger evidence Uninformed evolution wastes resources and pollutes the queue with noise Require concrete evidence: failure counts, routing miss logs, or explicit user request Routing stale-skill triggers through this skill instead of skill-updater Wrong escalation path; creates evolution requests for work that belongs in an update cycle Route stale_skill triggers directly to skill-updater; only escalate if the skill cannot be updated Triggering evolution after a single failure instance Single failures are noise; premature evolution wastes build capacity Apply defined thresholds: 5+ repeated errors, consistent routing misses across sessions Memory Protocol (MANDATORY) Before starting: Read .claude/context/memory/learnings.md using Read or Node fs.readFileSync (cross-platform). After completing: Recommendation pattern -> .claude/context/memory/learnings.md Ambiguous trigger logic -> .claude/context/memory/issues.md Evolution policy decision -> .claude/context/memory/decisions.md ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.