oimiragieo 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+ tasksrubric_regression: repeated score drop below threshold for same class of taskno_agent: recurring need with no valid routing matchintegration_gap: existing artifact integration missing (prefer artifact-integrator)user_request: explicit request for capability not availablestale_skill: audit pipeline reports verified artifact older than 6 months or invalidlastVerifiedAt
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.