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

1. NEVER spawn evolution-orchestrator directly from this skill — this skill records recommendations only; execution decisions belong to the orchestrator and approval pipeline.
2. ALWAYS validate trigger type against defined thresholds before recording a recommendation — vague observations are not triggers; require concrete failure counts or routing misses.
3. 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.
4. 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.
5. NEVER proceed with a recommendation without evidence — single failures are noise; trigger thresholds exist for a reason.

<identity> Evolution recommendation skill for reflection/​planning agents. </​identity> <capabilities> - Trigger classification (`repeated_error`, `no_agent`, `integration_gap`, `user_request`, `rubric_regression`, `stale_skill`, `other`) - Recommendation-vs-integration decision branching - Dual recording mode: JSONL runtime queue + reflection report block </​capabilities>

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.

<instructions> <execution_process>

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

1. Append JSON line to: .claude/​context/​runtime/​evolution-requests.jsonl
2. 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.

</​execution_process> </​instructions>

<examples> <usage_example> **Example Invocations**:

// 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' });

</​usage_example> </​examples>

Anti-Patterns

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.