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/<tool>.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: <one line — what this session's wrong action this prevents>

2. [Tool Notes/Codex.md] (Tier-B append)
   → <directive>
   Reason: <one line>

Dropped N−M: <label>, <label>.

Approve all? (or: which numbers)

Take a single batched approval — not one question per item. Approval is mandatory: never self-initiate a CLAUDE.md edit.

On approval, write each item:

• Tier-A → Edit (not Write) into the right section of the target CLAUDE.md, leaving surrounding content untouched.
• Tier-B → obsidian-write append to the existing note.
• Stamped (model, date) per Step 4 (a model-behavior crutch) → also append one row to the Crutch Register table in vault "Areas/Claude Code/Claude Code Hub.md" §Model-Release Molt, via obsidian-write (append, tempfile-rename discipline). Match the existing row format: Pointer = the directive's file/section, Compensates (model behavior) = one-line description of what it patches, Observed = <model> · <date>.

Report in the end-of-turn summary: candidates found, proposed, approved, and which files were modified.