# Learn From Mistakes > Run at the end of a session to extract wrong-mental-model failures (not inefficiencies) and propose surgical, cost-justified CLAUDE.md additions that prevent the same wrong action in future sessions. User-invocable only (via /learn-from-mistakes); does not auto-trigger. Distinct from /session-handoff (which captures work state) — this skill captures behavioral corrections. - Skill: `ozlar34/learn-from-mistakes` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add ozlar34/learn-from-mistakes` - Raw SKILL.md: https://api.skillmd.com/api/skills/ozlar34/learn-from-mistakes/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ozlar34 (https://skillmd.com/u/ozlar34) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/ozlar34/learn-from-mistakes --- # Learn From Mistakes Scan this session for a **single class** of failure: moments where Claude acted on a *wrong mental model* of how the user's systems, tools, or conventions actually work. Translate only the ones that clear a high cost bar into one-line imperative directives. Propose them as a single batched approval. **The default outcome is "nothing cleared the bar this session."** Most sessions produce no rule. That is success, not failure. Every line added to an always-loaded CLAUDE.md is taxed on every future session in every project, forever — so the bar to add one is deliberately high. Proposing a marginal rule just to have something to show is the exact failure this skill must avoid. ## Step 1 — Find wrong-model mistakes only Scan the conversation for moments where Claude **believed something false about how things work and acted on it** — then had to be corrected or course-correct. Signals: - The user negated or redirected an assertion/action: "no, actually…", "that's not how it works here", "you assumed…", "that's wrong because…". - Claude operated on a wrong assumption about a path, file location, tool behavior, convention, or system structure, and the action had to be redone. **Loops, repeated greps, and "took more steps than needed" are NOT findings.** They are *clues*. When you see one, ask: *was there a wrong belief underneath it?* - If yes → the **belief** is the candidate (not the loop). - If no → it was a one-off bad day. Drop it. Do not turn it into a rule. A generic "don't loop" or "search more efficiently" rule is bloat by definition. Never propose one. ## Step 2 — Two-gate filter Each candidate must pass **both** gates to earn an always-loaded slot. If it fails either, it is dropped or demoted to Tier-B (Step 3). 1. **Wrong-action gate.** Would *not* having this rule cause Claude to take a substantively *wrong action* in a future session — not merely be slower or take an extra step? Efficiency misses fail here. 2. **Cost gate.** Is the lesson a durable fact about *how the user's systems or conventions work* (broad blast radius), rather than syntax/API trivia that tooling already catches or that's hit-once-and-fixed-in-seconds? Trivia fails here. Also drop if: - It's already covered by an existing rule in any CLAUDE.md (read the relevant CLAUDE.md to check — don't guess). - It arose from genuinely one-off context (a since-deleted file, a confused prompt that got clarified). - You're not confident it generalizes — **err on the side of dropping.** **Final gate.** For each survivor, ask: *if this exact sentence had been in CLAUDE.md at the start of this session, would it have prevented the wrong action?* Anything short of a clear yes → rewrite or drop. ## Step 3 — Route each survivor - **Tier-A — always-loaded CLAUDE.md.** Passed both gates. Decide scope: - `~/.claude/CLAUDE.md` — universal: a wrong assumption about how Claude Code itself works, or a cross-project convention. - `[project]/CLAUDE.md` — specific to this project's structure, conventions, or tools. - When in doubt between global and project, choose **project** — narrower scope is safer. - **Tier-B — existing pointer-loaded note.** A *real, recurring, narrow* fact/quirk that failed the cost gate (e.g. a genuine tool gotcha) but has an **obvious existing home**: that tool's `_System/Tool Notes/.md`, or the relevant project subtree note. Append there via `obsidian-write` (Step 5). **No obvious existing home → drop. Never create a new "gotchas" note** — that just relocates the bloat. - **Drop** — everything else, including all inefficiency patterns with no wrong-model root. ## Step 4 — Write the directive One short imperative directive per survivor, in the style of existing CLAUDE.md rules: - Format: `Before [action], [check/verify X]` or `When [situation], [do this instead]`. - One sentence, ~15 words. Imperative and behavioral — what to DO, not what to know. - No observations ("Claude sometimes assumes X") — only directives ("Before assuming X, check Y"). Right style: - `Before assuming a path resolves against cwd, check vault-paths.json first.` - `Before modifying a function, grep all callers.` **Model-behavior vs. world-fact.** Ask what the correction compensates. If it patches *model behavior* (the model fabricates, over-defaults to optional, emits an AI tell, degrades at a task on a cheaper tier) rather than a durable *world-fact* (how a path, tool, or convention works), stamp the directive `(model, date)` and add a row to the **Crutch Register** (vault [[Claude Code Hub]] §Model-Release Molt) so the next release re-tests it. World-fact corrections are exempt — they don't molt with the model. ## Step 5 — Present once, terse, and write on approval Lead with the verdict in one line. If nothing cleared the bar, that is the whole output: ``` Nothing cleared the bar this session. ``` Otherwise, show only what needs a decision — each proposal as a ready-to-approve diff with a **one-line** reason — then the dropped count as terse labels, in this shape: ``` Found N candidates. Proposing M. 1. [~/.claude/CLAUDE.md · Coding discipline] → Before assuming X, verify Y. Reason: 2. [Tool Notes/Codex.md] (Tier-B append) → Reason: Dropped N−M: