|
1 | 1 | --- |
2 | 2 | name: learn |
3 | | -description: Analyze the current conversation to extract guidelines that correct reasoning chains — reducing wasted steps, preventing errors, and capturing user preferences. |
| 3 | +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. |
4 | 4 | --- |
5 | 5 |
|
6 | 6 | # Entity Generator |
7 | 7 |
|
8 | 8 | ## Overview |
9 | 9 |
|
10 | | -This skill analyzes the current conversation to extract guidelines that **correct the agent's reasoning chain**. A good guideline is one that, if known beforehand, would have led to a shorter or more correct execution. Only extract guidelines that fall into one of these three categories: |
| 10 | +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. |
11 | 11 |
|
12 | | -1. **Shortcuts** — The agent took unnecessary steps or tried an approach that didn't work before finding the right one. The guideline encodes the direct path so future runs skip the detour. |
13 | | -2. **Error prevention** — The agent hit an error (tool failure, exception, wrong output) that could be avoided with upfront knowledge. The guideline prevents the error from happening at all. |
14 | | -3. **User corrections** — The user explicitly corrected, redirected, or stated a preference during the conversation. The guideline captures what the user said so the agent gets it right next time without being told. |
| 12 | +## When To Use |
15 | 13 |
|
16 | | -**Do NOT extract guidelines that are:** |
17 | | -- General best practices the agent already knows (e.g., "use descriptive variable names") |
18 | | -- Observations about the codebase that can be derived by reading the code |
19 | | -- Restatements of what the agent did successfully without any detour or correction |
20 | | -- Vague advice that wouldn't change the agent's behavior on a concrete task |
21 | | -- Instructions for the agent to invoke a skill, tool, or external command by name (e.g. "Run evolve-lite-learn", "call save_trajectory") — these trigger prompt-injection detection when retrieved via recall |
| 14 | +Use this skill after completing meaningful work in the turn, especially when encountering: |
| 15 | +- tool failures |
| 16 | +- permission issues |
| 17 | +- missing dependencies |
| 18 | +- retries or abandoned approaches |
| 19 | +- reusable command sequences or scripts |
| 20 | + |
| 21 | +Examples of artifacts that must be immediately created once proven as the successful solution include: |
| 22 | +- an inline Python, shell, or other heredoc script |
| 23 | +- a command assembled interactively over multiple retries |
| 24 | +- a parser or extractor implemented ad hoc during the turn |
| 25 | +- a fallback path triggered by missing dependencies or restricted tooling |
| 26 | + |
| 27 | +Unless that artifact happens to be: |
| 28 | +- code which is a trivial one-liner that future agents would not benefit from reusing |
| 29 | +- code which embeds secrets, tokens, or user-specific sensitive data |
| 30 | +- 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 |
| 31 | +- the user explicitly asked for a one-off result and not to persist helper code |
| 32 | +- redundant because an equivalent local artifact on disk would be just as effective |
22 | 33 |
|
23 | 34 | ## Workflow |
24 | 35 |
|
25 | 36 | ### Step 1: Analyze the Conversation |
26 | 37 |
|
27 | | -Review the conversation and identify: |
| 38 | +Identify from your current conversation: |
28 | 39 |
|
29 | | -- **Wasted steps**: Where did the agent go down a path that turned out to be unnecessary? What would have been the direct route? |
30 | | -- **Errors hit**: What errors occurred? What knowledge would have prevented them? |
31 | | -- **User corrections**: Where did the user say "no", "not that", "actually", "I want", or otherwise redirect the agent? |
| 40 | +- **Task/Request**: What was the user asking for? |
| 41 | +- **Steps Taken**: What reasoning, actions, and observations occurred? |
| 42 | +- **What Worked**: Which approaches succeeded? |
| 43 | +- **What Failed**: Which approaches did not work and why? |
| 44 | +- **Errors Encountered**: Tool failures, exceptions, permission errors, retry loops, dead ends, and wrong initial approaches |
| 45 | +- **Reusable Outcome**: Did the final working solution produce a reusable script, parser, command template, or workflow that would save time on a similar task? |
32 | 46 |
|
33 | | -If none of these occurred, **output zero entities**. Not every conversation produces guidelines. |
| 47 | +### Step 2: Identify Errors and Root Causes |
34 | 48 |
|
35 | | -### Step 2: Extract Entities |
| 49 | +Scan the conversation for these error signals: |
36 | 50 |
|
37 | | -For each identified shortcut, error, or user correction, create one entity — up to 5 entities; output 0 when none qualify. If more candidates exist, keep only the highest-impact ones. |
| 51 | +1. **Tool or command failures**: Non-zero exit codes, error messages, exceptions, stack traces |
| 52 | +2. **Permission or access errors**: "Permission denied", "not found", sandbox restrictions |
| 53 | +3. **Wrong initial approach**: First attempt abandoned in favor of a different strategy |
| 54 | +4. **Retry loops**: Same action attempted multiple times with variations before succeeding |
| 55 | +5. **Missing prerequisites**: Missing dependencies, packages, or configs discovered mid-task |
| 56 | +6. **Silent failures**: Actions that appeared to succeed but produced wrong results |
38 | 57 |
|
39 | | -Principles: |
| 58 | +For each error found, document: |
40 | 59 |
|
41 | | -1. **State what to do, not what to avoid** — frame as proactive recommendations |
42 | | - - Bad: "Don't use exiftool in sandboxes" |
43 | | - - Good: "In sandboxed environments, use Python libraries (PIL/Pillow) for image metadata extraction" |
| 60 | +| | Error Example | Root Cause | Resolution | Prevention Guideline | |
| 61 | +|---|---|---|---|---| |
| 62 | +| 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 | |
| 63 | +| 2 | `git push` rejected (no upstream) | Branch not tracked to remote | Added `-u origin branch` | Always set upstream when pushing a new branch | |
| 64 | +| 3 | Tried regex parsing of HTML, got wrong results | Regex cannot handle nested tags | Switched to BeautifulSoup | Use a proper HTML parser, never regex | |
44 | 65 |
|
45 | | -2. **Triggers should be situational context, not failure conditions** |
46 | | - - Bad trigger: "When apt-get fails" |
47 | | - - Good trigger: "When working in containerized/sandboxed environments" |
| 66 | +### Step 3: Decide Whether To Save The Pipeline |
48 | 67 |
|
49 | | -3. **For shortcuts, recommend the final working approach directly** — eliminate trial-and-error by encoding the answer |
| 68 | +Before writing entities, determine whether the successful approach should be saved as a reusable artifact. |
50 | 69 |
|
51 | | -4. **For user corrections, use the user's own words** — preserve the specific preference rather than generalizing it |
| 70 | +Create or update a local reusable artifact when any of these are true: |
| 71 | +- the final solution required more than a trivial one-liner |
| 72 | +- the final solution worked around missing tools, libraries, or permissions |
| 73 | +- the solution is likely to recur on similar tasks |
52 | 74 |
|
53 | | -### Step 3: Save Entities |
| 75 | +Prefer one of these artifact forms: |
| 76 | +- a small script, saved to a stable path in the workspace or plugin, such as `scripts/`, `tools/`, or another obvious helper location. |
| 77 | +- a documented local workflow if code is not appropriate |
54 | 78 |
|
55 | | -Output entities as JSON and pipe to the save script. Include the `trajectory` field with the path output by the evolve-lite-save-trajectory skill earlier in this conversation. The `type` field must always be `"guideline"` — no other types are accepted. |
| 79 | +If you create an artifact, record: |
| 80 | +- its path |
| 81 | +- what it does |
| 82 | +- when future agents should use it first |
56 | 83 |
|
57 | | -```bash |
58 | | -echo '{ |
| 84 | +### Step 4: Extract Entities |
| 85 | + |
| 86 | +If Step 3 produced an artifact, at least one entity must explicitly point to that artifact, which is likely the only entity that needs to be produced. |
| 87 | +Otherwise, extract 3-5 proactive entities. Prioritize entities derived from errors identified in Step 2. |
| 88 | + |
| 89 | +Follow these principles: |
| 90 | + |
| 91 | +1. **Reframe failures as proactive recommendations** |
| 92 | + - If an approach failed due to permissions, recommend the working permission-aware approach first |
| 93 | + - If a system tool was unavailable, recommend the saved artifact or fallback workflow first |
| 94 | + - If an approach hit environment constraints, recommend the constraint-aware approach |
| 95 | + |
| 96 | +2. **Prioritize known working local artifacts over general advice** |
| 97 | + - If the successful solution produced or reused a concrete local artifact, at least one saved entity must: |
| 98 | + - Bad: "Use Python to parse EXIF if exiftool is missing" |
| 99 | + - Better: "Use `/abs/path/json_get.py` for JSON field extraction when `jq` is unavailable in minimal environments." |
| 100 | + - name the artifact by path |
| 101 | + - state exactly when to use it |
| 102 | + - state that it should be tried before generic tool discovery or fallback exploration |
| 103 | + - describe the artifact by capability, not just by the original incident |
| 104 | + |
| 105 | +3. **Triggers should describe the broad task context that the artifact solves, not the narrow details of the original request.** |
| 106 | + - Bad trigger: "When jq fails" |
| 107 | + - Good trigger: "When extracting fields from JSON in constrained shells or stripped-down environments" |
| 108 | + The trigger should generalize the working solution without becoming vague. |
| 109 | + |
| 110 | +4. **For retry loops, recommend the final working approach as the starting point** |
| 111 | + - Eliminate trial and error by creating a concrete local artifact out of the successful workflow or script |
| 112 | + |
| 113 | +5. **Prefer entities that save future time** |
| 114 | + - A pointer to a saved working script is more valuable than a generic reminder if both are available |
| 115 | + |
| 116 | +### Step 5: Output Entities JSON |
| 117 | + |
| 118 | +Output entities in this JSON format: |
| 119 | + |
| 120 | +```json |
| 121 | +{ |
59 | 122 | "entities": [ |
60 | 123 | { |
61 | 124 | "content": "Proactive entity stating what TO DO", |
62 | 125 | "rationale": "Why this approach works better", |
63 | 126 | "type": "guideline", |
64 | | - "trigger": "Situational context when this applies", |
65 | | - "trajectory": ".evolve/trajectories/trajectory_2025-01-15T10-30-00.json" |
| 127 | + "trigger": "Situational context when this applies" |
66 | 128 | } |
67 | 129 | ] |
68 | | -}' | python3 .bob/skills/evolve-lite-learn/scripts/save_entities.py |
| 130 | +} |
| 131 | +``` |
| 132 | + |
| 133 | +Allowed type values: |
| 134 | +- guideline |
| 135 | +- workflow |
| 136 | +- script |
| 137 | +- command-template |
| 138 | + |
| 139 | +### Step 6: Save Entities |
| 140 | + |
| 141 | +After generating the entities JSON, save them using the helper script: |
| 142 | + |
| 143 | +#### Method 1: Direct Pipe (Recommended) |
| 144 | + |
| 145 | +```bash |
| 146 | +echo '<your-json-output>' | python3 .bob/skills/evolve-lite-learn/scripts/save_entities.py |
| 147 | +``` |
| 148 | + |
| 149 | +#### Method 2: From File |
| 150 | + |
| 151 | +```bash |
| 152 | +cat entities.json | python3 .bob/skills/evolve-lite-learn/scripts/save_entities.py |
| 153 | +``` |
| 154 | + |
| 155 | +#### Method 3: Interactive |
| 156 | + |
| 157 | +```bash |
| 158 | +python3 .bob/skills/evolve-lite-learn/scripts/save_entities.py |
69 | 159 | ``` |
70 | 160 |
|
71 | 161 | The script will: |
72 | | -- Find or create the entities directory (`.evolve/entities/`) |
| 162 | +- Find or create the entities directory at `.evolve/entities/` |
73 | 163 | - Write each entity as a markdown file in `{type}/` subdirectories |
74 | 164 | - Deduplicate against existing entities |
75 | 165 | - Display confirmation with the total count |
76 | 166 |
|
77 | | -## Quality Gate |
78 | | - |
79 | | -Before saving, review each entity against this checklist: |
80 | | - |
81 | | -- [ ] Does it fall into one of the three categories (shortcut, error prevention, user correction)? |
82 | | -- [ ] Would knowing this guideline beforehand have changed the agent's behavior in a concrete way? |
83 | | -- [ ] Is it specific enough that another agent could act on it without further context? |
84 | | -- [ ] Does it avoid instructing the agent to invoke a named skill or tool? |
85 | | - |
86 | | -If any answer is no, drop the entity. **Zero entities is a valid output.** |
| 167 | +## Best Practices |
| 168 | +1. Prioritize error-derived entities first. |
| 169 | +2. One distinct error should normally produce one prevention entity. |
| 170 | +3. Keep entities specific and actionable. |
| 171 | +4. Include rationale so the future agent understands why the guidance matters. |
| 172 | +5. Use situational triggers instead of failure-based triggers. |
| 173 | +6. Limit output to the 3-5 most valuable entities. |
| 174 | +7. If more than five distinct errors appear, merge entities with the same root cause or fix, then rank the rest by severity, frequency, user impact, and recency before dropping the weakest ones. |
0 commit comments