> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# /learn

> Diagnose and fix agent behavioral surfaces when the user corrects a mistake — connects to Claude native memory.

# /learn — Behavioral Correction

When a user corrects a mistake, `/learn` diagnoses which behavioral surface caused it and applies a minimal, targeted fix. This is an interactive skill — the user invokes `/learn` directly, and the agent runs in the foreground, conversing with the user throughout.

## 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
* A pattern of repeated errors suggests a missing behavioral rule

## Flow

<Steps>
  <Step title="Analyze the mistake">
    What went wrong? Read the conversation context, recent changes, and relevant code to understand the error.
  </Step>

  <Step title="Determine root cause">
    Why did the agent behave this way? Missing rule? Stale convention? Wrong default?
  </Step>

  <Step title="Diagnose the surface">
    Which behavioral surface needs to change? See the Writable Surfaces table below.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Apply with approval">
    User must approve before any write. Apply the change and confirm what was learned.
  </Step>

  <Step title="Save to memory">
    Write the learning as a feedback memory in `.claude/memory/` so Claude native memory retains it across sessions.
  </Step>
</Steps>

## Writable Surfaces

The learn skill 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

These files are maintained by framework developers and must never be modified by `/learn`:

* `plugins/genie/skills/` — framework skills
* `plugins/genie/agents/` — framework agents
* 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, it is also saved as a feedback memory for cross-session persistence:

```markdown theme={"dark"}
# .claude/memory/feedback_example.md
---
name: use-uv-not-pip
description: System uses uv for Python package management, pip is not installed
type: feedback
---

Use uv instead of pip for all Python operations.
**Why:** pip is not installed on this system; uv is the only package manager.
**How to apply:** Any time a Python package needs installing, use uv tool install or uv pip install.
```

The `.claude/memory/MEMORY.md` index is updated with a pointer to the new file.

## Example

User corrects the agent: "Stop using `pip install` — this system only has `uv`."

The agent runs `/learn`:

1. **Analyze:** Agent used `pip install python-dotenv` which failed because pip isn't installed.
2. **Root cause:** No rule in `~/.claude/rules/` about Python tooling.
3. **Surface:** Global rules (`~/.claude/rules/python-tooling.md`) — applies to all projects.
4. **Propose fix (plan mode):** Create `~/.claude/rules/python-tooling.md` with rules for using uv.
5. **User approves.** File written.
6. **Save to memory:** Write feedback memory to `.claude/memory/feedback_python_tooling.md`.

## 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