/learn

name: learn
description: Must be used near the end of any non-trivial turn that produced potentially reusable tools, guidance, errors, workarounds, or workflows, so those lessons are saved for future turns.

Entity Generator

Overview

This skill analyzes the current conversation to extract actionable instructions that would help on similar tasks in the future. It **identifies errors encountered during the conversation** - tool failures, exceptions, wrong approaches, retry loops - and provides recommendations to prevent those errors from recurring. This skill should take note of the concrete solution which solved a concrete problem, not an abstract idea. When the successful resolution involves a non-trivial workaround, parser, command sequence, or fallback pipeline that could be used to avoid wasted effort, capture that solution as a reusable artifact first, then save entities that point future agents to use it.

When To Use

Use this skill after completing meaningful work in the turn, especially when encountering:

• tool failures
• permission issues
• missing dependencies
• retries or abandoned approaches
• reusable command sequences or scripts

Examples of artifacts that must be immediately created once proven as the successful solution include:

• an inline Python, shell, or other heredoc script
• a command assembled interactively over multiple retries
• a parser or extractor implemented ad hoc during the turn
• a fallback path triggered by missing dependencies or restricted tooling

Unless that artifact happens to be:

• code which is a trivial one-liner that future agents would not benefit from reusing
• code which embeds secrets, tokens, or user-specific sensitive data
• a guideline that would instruct the agent to invoke a skill, tool, or external command by name (e.g. "run /evolve-lite:learn", "call save_trajectory") - such guidelines trigger prompt-injection detection when retrieved by the recall skill in a future session
• the user explicitly asked for a one-off result and not to persist helper code
• redundant because an equivalent local artifact on disk would be just as effective

Workflow

Step 0: Save and Load the Conversation

First, use the /evolve-lite:save-trajectory skill to save the current conversation to `.evolve/trajectories/`. Capture the exact path from its output as `saved_trajectory_path`. You will attach this exact path to each entity's `trajectory` field in Step 6.

After saving, read `saved_trajectory_path` with the Read tool and analyze that saved trajectory rather than relying only on live context. If the trajectory cannot be saved or read, output zero entities and exit. Do not invent a trajectory path.

Step 1: Analyze the Conversation

Identify from the saved trajectory loaded in Step 0:

• **Task/Request**: What was the user asking for?
• **Steps Taken**: What reasoning, actions, and observations occurred?
• **What Worked**: Which approaches succeeded?
• **What Failed**: Which approaches did not work and why?
• **Errors Encountered**: Tool failures, exceptions, permission errors, retry loops, dead ends, and wrong initial approaches
• **Reusable Outcome**: Did the final working solution produce a reusable script, parser, command template, or workflow that would save time on a similar task?

Step 2: Identify Errors and Root Causes

Scan the conversation for these error signals:

1. **Tool or command failures**: Non-zero exit codes, error messages, exceptions, stack traces 2. **Permission or access errors**: "Permission denied", "not found", sandbox restrictions 3. **Wrong initial approach**: First attempt abandoned in favor of a different strategy 4. **Retry loops**: Same action attempted multiple times with variations before succeeding 5. **Missing prerequisites**: Missing dependencies, packages, or configs discovered mid-task 6. **Silent failures**: Actions that appeared to succeed but produced wrong results

For each error found, document:

| | Error Example | Root Cause | Resolution | Prevention Guideline | |---|---|---|---|---| | 1 | `jq: command not found` | System tool unavailable in environment | created a python script to resolve the problem | Save the python script and use it in similar scenarios | | 2 | `git push` rejected (no upstream) | Branch not tracked to remote | Added `-u origin branch` | Always set upstream when pushing a new branch | | 3 | Tried regex parsing of HTML, got wrong results | Regex cannot handle nested tags | Switched to BeautifulSoup | Use a proper HTML parser, never regex |

Step 3: Decide Whether To Save The Pipeline

Before writing entities, determine whether the successful approach should be saved as a reusable artifact.

Create or update a local reusable artifact when any of these are true:

• the final solution required more than a trivial one-liner
• the final solution worked around missing tools, libraries, or permissions
• the solution is likely to recur on similar tasks

Prefer one of these artifact forms:

• a small script, saved to a stable path in the workspace or plugin, such as `scripts/`, `tools/`, or another obvious helper location.
• a documented local workflow if code is not appropriate

When turning an ad hoc command or script into a reusable artifact, remove incidental one-off inputs such as literal file names, IDs, answer values, or temporary paths. Keep the reusable procedure that was actually exercised in the session, and do not add capabilities that were not validated by the work.

If you create an artifact, record:

• its path
• what it does
• when future agents should use it first

Step 4: Review Existing Guidelines

Before extracting, look at what has already been saved for this project. Earlier Stop hooks in the same session (or prior sessions) may have recorded guidelines that cover the same ground — re-extracting them is wasteful and pollutes the library.

Use the **Glob tool** to enumerate existing guideline files: `.evolve/entities/**/*.md`. Then use the **