|
| 1 | +--- |
| 2 | +name: kaizen-learn |
| 3 | +description: Extract actionable entities from the completed conversation. Systematically identifies errors, failures, and inefficiencies to generate proactive entities that prevent them from recurring. |
| 4 | +--- |
| 5 | + |
| 6 | +# Kaizen Learn Skill |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +This skill analyzes your recent actions to extract actionable entities that would help on similar tasks in the future. It **prioritizes errors encountered during the conversation** — tool failures, exceptions, wrong approaches, retry loops — and transforms them into proactive recommendations that prevent those errors from recurring. |
| 11 | + |
| 12 | +## Workflow |
| 13 | + |
| 14 | +### Step 1: Analyze the Conversation |
| 15 | + |
| 16 | +Identify from your current conversation: |
| 17 | +- **Task/Request**: What was the user asking for? |
| 18 | +- **Steps Taken**: What reasoning, actions, and observations occurred? |
| 19 | +- **What Worked**: Which approaches succeeded? |
| 20 | +- **What Failed**: Which approaches didn't work and why? |
| 21 | +- **Errors Encountered**: Tool failures, exceptions, permission errors, retry loops, dead ends, and wrong initial approaches |
| 22 | + |
| 23 | +### Step 2: Identify Errors and Root Causes |
| 24 | + |
| 25 | +Scan the conversation for these error signals: |
| 26 | +1. **Tool/command failures**: Non-zero exit codes, error messages, exceptions, stack traces |
| 27 | +2. **Permission/access errors**: "Permission denied", "not found", sandbox restrictions |
| 28 | +3. **Wrong initial approach**: First attempt abandoned in favor of a different strategy |
| 29 | +4. **Retry loops**: Same action attempted multiple times with variations before succeeding |
| 30 | +5. **Missing prerequisites**: Missing dependencies, packages, configs discovered mid-task |
| 31 | +6. **Silent failures**: Actions that appeared to succeed but produced wrong results |
| 32 | + |
| 33 | +For each error found, clearly document the progression from failure to prevention: |
| 34 | + |
| 35 | +| Error Example | Root Cause | Resolution | Prevention Guideline | |
| 36 | +|---|---|---|---| |
| 37 | +| `exiftool: command not found` | System tool unavailable | Switched to Python PIL | Use PIL for image metadata in sandboxed environments | |
| 38 | +| `git push` rejected | Branch not tracked to remote | Added `-u origin branch` | Always set upstream when pushing a new branch | |
| 39 | +| Tried regex parsing of HTML | Regex can't handle nested tags | Switched to BeautifulSoup | Use a proper HTML parser (BeautifulSoup/lxml), never regex | |
| 40 | + |
| 41 | +> **If no errors are found**, proceed to Step 3 — but note that zero entities is a valid outcome for routine conversations. |
| 42 | +
|
| 43 | +### Step 2b: Quality Gate |
| 44 | + |
| 45 | +Before extracting entities, every candidate insight must pass **all three** of these criteria: |
| 46 | + |
| 47 | +1. **Non-obvious** — Would a competent LLM NOT already do this by default? Generic conversational behaviors (e.g., "answer directly," "clarify ambiguity," "execute commands when asked") are not worth saving. |
| 48 | +2. **Environment or project-specific** — The insight encodes something about THIS codebase, THIS OS, THIS tool configuration, or THIS user's preferences — not general knowledge any LLM would already have. |
| 49 | +3. **Derived from an actual mistake or discovery** — The insight was learned from a real failure, unexpected behavior, or non-trivial success in the conversation — not just from observing that things went smoothly. |
| 50 | + |
| 51 | +If no candidates pass all three criteria, output an empty entities array (`{"entities": []}`). **Saving low-quality entities degrades the knowledge base over time.** |
| 52 | + |
| 53 | +### Step 2c: Review Existing Entities |
| 54 | + |
| 55 | +Before generating new entities, check what already exists to avoid near-duplicates: |
| 56 | + |
| 57 | +```bash |
| 58 | +python3 <path-to-kaizen-recall-dir>/scripts/get.py --type guideline --task "<brief summary>" |
| 59 | +``` |
| 60 | +*(Use `python` if `python3` isn't found)* |
| 61 | + |
| 62 | +If the insight you're about to save is already covered by an existing entity — even if worded differently — **do not create a near-duplicate**. Instead, only create a new entity if it adds genuinely new information not captured by any existing entity. |
| 63 | + |
| 64 | +### Step 3: Extract Entities |
| 65 | + |
| 66 | +Extract **0-2** proactive entities. **Zero is a valid answer.** If the conversation was routine with no errors, unexpected behavior, or non-obvious discoveries, output an empty entities array. **Prioritize entities derived from errors identified in Step 2.** |
| 67 | + |
| 68 | +Follow these principles: |
| 69 | +1. **Reframe failures as proactive recommendations:** |
| 70 | + - If an approach failed due to permissions → recommend the alternative FIRST |
| 71 | + - If a system tool wasn't available → recommend what worked instead |
| 72 | +2. **Focus on what worked, stated as the primary approach:** |
| 73 | + - Bad: "If exiftool fails, use PIL instead" |
| 74 | + - Good: "In sandboxed environments, use Python libraries (PIL) for image metadata extraction" |
| 75 | +3. **Triggers should be situational context, not failure conditions:** |
| 76 | + - Bad trigger: "When apt-get fails" |
| 77 | + - Good trigger: "When working in containerized environments" |
| 78 | +4. **Map error-derived entities to categories:** |
| 79 | + - `strategy` — wrong approach was chosen → recommend the right approach from the start |
| 80 | + - `recovery` — a fallback chain was needed → start from the approach that worked |
| 81 | + - `optimization` — effort was wasted on retries/timeouts → eliminate the waste |
| 82 | + > If you find yourself categorizing everything as `strategy`, reconsider whether the entity is truly non-obvious. True strategy entities arise when a wrong approach was actually taken. |
| 83 | +5. **Merge/Rank/Drop (For chaotic sessions)**: If you find many errors, apply this algorithm to get down to 0-2 entities: |
| 84 | + - **Merge**: Combine errors with the same root cause into a single prevention entity |
| 85 | + - **Rank**: Select among remaining entities by severity > frequency > user impact > recency |
| 86 | + - **Drop**: Discard lowest-ranked entities that exceed the 2-entity cap |
| 87 | +6. **Do NOT generate entities like these** (too generic / obvious): |
| 88 | + - "Answer factual questions from knowledge" — any LLM already does this |
| 89 | + - "Clarify ambiguous user queries" — basic conversational behavior |
| 90 | + - "Execute commands when the user asks you to" — obvious |
| 91 | + - "Provide context with answers" — too vague, applies to everything |
| 92 | + - "For simple tasks, keep it simple" — truism |
| 93 | +7. **DO generate entities like these** (specific, learned): |
| 94 | + - "Use `python3` instead of `python` on macOS — the `python` symlink doesn't exist by default" — environment-specific |
| 95 | + - "The kaizen save.py script reads from stdin only; do not pass CLI arguments" — project-specific, error-derived |
| 96 | + - "In sandboxed containers, `apt-get` is unavailable; use Python stdlib for system tasks" — recovery from a real constraint |
| 97 | + - "Copy skill directories with `cp -r` then update `custom_modes.yaml` references" — project workflow knowledge |
| 98 | + |
| 99 | +### Step 4: Output Entities JSON |
| 100 | + |
| 101 | +Output entities in the following JSON format: |
| 102 | + |
| 103 | +```json |
| 104 | +{ |
| 105 | + "entities": [ |
| 106 | + { |
| 107 | + "content": "Proactive entity stating what TO DO", |
| 108 | + "rationale": "Why this approach works better", |
| 109 | + "category": "strategy|recovery|optimization", |
| 110 | + "trigger": "Situational context when this applies" |
| 111 | + } |
| 112 | + ] |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +### Step 4b: Examples of Good vs Bad Entities |
| 117 | + |
| 118 | +**BAD (reactive and generic):** |
| 119 | +```json |
| 120 | +{ |
| 121 | + "content": "Fall back to Python PIL when exiftool is not available", |
| 122 | + "trigger": "When exiftool command fails" |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +**GOOD (proactive and situational):** |
| 127 | +```json |
| 128 | +{ |
| 129 | + "content": "Use Python PIL/Pillow for image metadata extraction in sandboxed environments", |
| 130 | + "rationale": "System tools like exiftool may not be available; PIL is always installable via pip", |
| 131 | + "category": "strategy", |
| 132 | + "trigger": "When extracting image metadata in containerized or sandboxed environments" |
| 133 | +} |
| 134 | +``` |
| 135 | + |
| 136 | +### Step 5: Save Entities |
| 137 | + |
| 138 | +⚠️ **CRITICAL: The save.py script ONLY accepts JSON via stdin pipe. It does NOT accept CLI arguments like --task or --outcome.** |
| 139 | + |
| 140 | +After generating the entities JSON: |
| 141 | +- **If entities array is empty** (`{"entities": []}`): Skip the save command and notify the user that no learnings were identified for this routine task. Proceed directly to `attempt_completion`. |
| 142 | +- **If entities array has content**: Save them by piping the JSON into the `save.py` script as shown below. |
| 143 | + |
| 144 | +**✅ CORRECT SYNTAX (stdin pipe):** |
| 145 | +```bash |
| 146 | +printf '{"entities": [...]}' | python3 <path-to-kaizen-learn-dir>/scripts/save.py |
| 147 | +``` |
| 148 | +*(Use `python` if `python3` isn't found)* |
| 149 | + |
| 150 | +**❌ WRONG SYNTAX (CLI arguments are NOT supported):** |
| 151 | +```bash |
| 152 | +# ⚠️ NEVER DO THIS - The script does NOT accept --task, --outcome, or any CLI arguments: |
| 153 | +python3 <path-to-kaizen-learn-dir>/scripts/save.py --task "..." --outcome "..." |
| 154 | + |
| 155 | +# This will produce an error like: |
| 156 | +# "ERROR: This script does not accept CLI arguments." |
| 157 | +# or cause the script to hang waiting for stdin input. |
| 158 | +``` |
| 159 | + |
| 160 | +**❌ WRONG SYNTAX (JSON parsing error):** |
| 161 | +```bash |
| 162 | +# DO NOT DO THIS - escaped quotes break JSON parsing: |
| 163 | +printf '{"entities": [{"content": "Use \"quotes\" here"}]}' | python3 <path-to-kaizen-learn-dir>/scripts/save.py |
| 164 | +# Single-quoted strings pass backslashes literally, breaking JSON |
| 165 | +``` |
| 166 | + |
| 167 | +**CRITICAL REQUIREMENTS:** |
| 168 | +- The script reads JSON from **stdin only** via pipe (see line 19: `sys.stdin.read()`) |
| 169 | +- It has **NO command-line arguments** - no argparse, no --task, no --outcome flags |
| 170 | +- Use `printf` (not `echo`) to avoid shell interpretation issues |
| 171 | +- **Avoid escaped quotes (`\"`) inside single-quoted printf strings** - they are passed literally and break JSON parsing |
| 172 | +- If you need quotes in content, either omit them or use alternative phrasing |
| 173 | +- Passing CLI arguments will cause the script to hang indefinitely waiting for stdin input |
| 174 | + |
| 175 | +Review the script's output to confirm the save was successful. Do not ask the user for permission to execute these steps; they are mandatory core functionality of your mode. |
0 commit comments