learn

# /learn — Behavioral Correction

When a user corrects a mistake, `/learn` diagnoses which behavioral surface caused it and applies a minimal, targeted fix.

## When to Use
- User corrects agent behavior ("no, don't do that", "you should always...", "stop doing X")
- Agent made a mistake that should never recur
- User explicitly invokes `/learn`
- A pattern of repeated errors suggests a missing behavioral rule

## How It Works

This is an **interactive skill**. The user invokes `/learn` directly, and the agent runs in the foreground, conversing with the user throughout.

## Flow

1. **Analyze the mistake:** What went wrong? Read the conversation context, recent changes, and relevant code to understand the error.
2. **Determine root cause:** Why did the agent behave this way? Missing rule? Stale convention? Wrong default?
3. **Diagnose the surface:** Which behavioral surface needs to change? (See Writable Surfaces below.)
4. **Propose minimal fix:** Enter native plan mode. Show exactly which file will change, what content will be added/modified, and why. One change per learning — never batch.
5. **Apply with approval:** User must approve before any write. Apply the change. Confirm what was learned.
6. **Save to memory:** Write the learning as a feedback memory in `.claude/memory/` so Claude native memory retains it across sessions.

## Writable Surfaces

The learn agent diagnoses which surface needs the fix:

| Surface | Path | What It Controls |
|---------|------|-----------------|
| Project conventions | `CLAUDE.md` | Commands, gotchas, project rules, coding style |
| Agent identity | `AGENTS.md` | Agent role, preferences, team behavior |
| Agent personality | `SOUL.md` / `IDENTITY.md` | Tone, communication style |
| Global rules | `~/.claude/rules/*.md` | Cross-project behavioral rules |
| Claude native memory | `.claude/memory/` | Feedback, user prefs, project context |
| Project memory | `memory/` | Project-scoped knowledge files |
| Hooks | `.claude/settings.json` | Event-driven automation, permission gates |
| Any config file | varies | Any file that shapes agent behavior |

## Never-Touch Surfaces

- `plugins/genie/skills/` — framework skills (maintained by framework developers)
- `plugins/genie/agents/` — framework agents (maintained by framework developers)
- Other projects' files — scope is the current project only
- Source code — learn updates behavior configuration, not implementation

## Claude Native Memory Connection

When a learning is applied, also save it as a feedback memory:

1. Write a memory file to `.claude/memory/` with frontmatter:
   ```markdown
   ---
   name: <concise-name>
   description: <one-line description for relevance matching>
   type: feedback
   ---

   <The rule itself>
   **Why:** <reason the user gave or the incident that caused it>
   **How to apply:** <when/where this guidance kicks in>
   ```
2. Update `.claude/memory/MEMORY.md` index with a pointer to the new file.

This ensures the learning persists across conversations via Claude's native memory system.

## Rules
- **Plan mode is mandatory** — never write without user approval via native plan mode.
- **One learning at a time** — diagnose one surface, propose one fix.
- **Never assume** — verify with the user before recording any learning.
- **Never modify framework files** — `plugins/genie/skills/` and `plugins/genie/agents/` are off limits.
- **Never write source code** — behavioral configuration only.
- **Minimal changes** — add the smallest rule that prevents the mistake from recurring.
- **Always save to memory** — every learning gets a feedback memory for cross-session persistence.