---
name: learn
keep-coding-instructions: true
---

# Skill: learn

**Trigger:** `/learn` or "extract patterns" or "learn from this session"

**Description:** Extracts reusable patterns, lessons, and decisions from the current session and saves them to memory files. Run before End Session or before /compact to capture what was learned.

**Allowed Tools:** Read, Edit, Write, Glob, Grep

---

## Steps

1. **Check `tasks/corrections_queue.md`** — if it has entries, read each one. These are prompts where you were corrected mid-session (auto-captured by hook). Convert each into a lesson entry using the format in step 3, then clear the file back to its header only (keep the two comment lines, delete the `## date` entries).

2. **Review the current conversation for:**
   - Bugs fixed and their root causes
   - Patterns that worked well
   - Mistakes made and how they were corrected
   - Architectural decisions made
   - Stack-specific gotchas discovered

3. **Conflict check before saving:**
   For each new lesson or decision, run:
   ```
   python tools/memory.py --search "[key term from lesson]" --top 3
   ```
   Scan the results for contradictions — existing memory that says the opposite. If found:
   - Show both the old and new entry side by side
   - Ask: "This conflicts with an existing memory. Replace it? (yes / keep both / skip)"
   - If replacing: use `/forget` to invalidate the old entry, then save the new one
   - If keeping both: add a note `(supersedes [old filename])` to the new entry

4. **Categorize findings:**
   - Bugs/errors → append to `.claude/memory/lessons.md` (create if missing)
   - Architectural decisions → append to `.claude/memory/decisions.md` (create if missing)
   - Rejected approaches → append to `tasks/regret.md` (format: `| Date | Approach | Why Rejected |`)
   - Repeated patterns (3+ times) → flag as skill candidate

5. **Format each entry as:**
   ```
   ## [YYYY-MM-DD] - [short title]
   **Context:** what you were doing
   **Problem:** what went wrong or what was learned
   **Solution/Pattern:** what works
   **Apply when:** trigger conditions
   ```

6. **Global lessons check:** For each lesson, ask: "Does this apply beyond this project?" If yes, also append to `~/.claude/global-lessons.md`:
   ```
   ## [YYYY-MM-DD] - [title]
   **Source:** [project name]
   **Pattern:** [what works]
   **Apply when:** [trigger]
   ```

7. **Skill scoring (interactive — ask, don't assume):**

   For each skill that fired this session, ask the user:

   > "Did **[skill name]** work correctly this session, or did it need a correction?"

   If it worked: log a single N row silently — no further questions needed.
   ```
   | [date] | [skill] | all | [what it was used for] | N | minor | - | - | - |
   ```

   If it needed a correction: ask two follow-up questions:
   > "Which step went wrong — and what did it produce vs what you needed?"
   > "How bad was it? (minor = small fix / major = wrong approach / silent = not caught until later)"

   Take their natural-language answer and translate it into the structured row:
   ```
   | [date] | [skill] | step [N] | [used for] | Y | [severity] | Step [N]: produced [X], needed [Y]. Fixed by: [Z]. | manual | - |
   ```

   **Translation rules:**
   - Extract a step number from their description (or infer from the skill's step list)
   - "Produced X" = what Claude actually did or output
   - "Needed Y" = what should have happened
   - "Fixed by Z" = the correction given (brief)
   - `Code Fixed` = `manual` (code was corrected in the session) or `-` (no code change needed)
   - `Skill Patched` = always `-` when first logged; /evolve fills this in when it patches the skill

   If the user's answer is too vague to extract step + produced + needed, ask one more time:
   > "What specifically did it produce vs what you wanted?"

   Only write `INSUFFICIENT DATA` as a last resort — never skip scoring entirely.

   **Severity guide:** `minor` = small correction, close output | `major` = wrong approach or significant rework | `silent` = failure not caught until later, discovered downstream

8. **Velocity log:** If this session had an estimated task, append to `tasks/velocity.md`:
   `| [date] | [task] | [estimated] | [actual] | [complexity 1-5] | [notes] |`

9. **After writing:**
   - Report: "Extracted N lessons: [list titles]"
   - If any pattern appeared 3+ times: "Suggest creating skill: [name] — run /evolve to cluster"

---

## Notes

- Never delete existing entries — only append
- Keep entries concise — one lesson per entry
- Run before End Session to preserve session knowledge
- Run before `/compact` to avoid losing insights
- If a pattern recurs across sessions, it belongs in a skill not just lessons.md
