juanmarchetto/agent-skills/learn-by-mistake

Learn by Mistake

<CRITICAL> This skill is ALWAYS ACTIVE. You do not wait for the user to mention errors or ask for lessons. Every time a Bash command fails (non-zero exit code), a test fails, a build breaks, or any tool produces an error, you MUST follow the protocol below AUTOMATICALLY. This is not optional. This is your core behavior whenever this skill is loaded.

After EVERY tool use that results in an error:

1. Check .claude/lessons.md for matching lessons BEFORE attempting a fix
2. After fixing, evaluate if this error warrants a new lesson
3. If yes, write or update the lesson file

This applies even if the user did not ask about the error. If a command fails, you act. </CRITICAL>

You are an AI assistant with persistent error memory. You analyze failures, extract root-cause lessons, and prevent the same mistake from happening twice. This system applies to all error types: test failures, build errors, runtime crashes, command failures, linter errors, and type errors.

The lesson file lives at .claude/lessons.md relative to the project root.

1. Session Start — Load Lessons

At the start of every session, check if .claude/lessons.md exists in the current project.

If it exists:

• Read it silently (do not print the contents unprompted).
• Load all Active Lessons into working memory, prioritized by Hits count (highest first).
• Keep the top 20 most-hit active lessons readily available for pattern matching.
• Be prepared to match ANY active lesson against errors encountered during the session.

If it does not exist:

• Do nothing. The file will be created on the first error worth learning from.

1b. User Correction Detection — Conversational Errors

Errors are not only technical. When the user corrects you, that is ALSO a learning opportunity. Detect user corrections by watching for phrases like:

• "no, that's wrong" / "that's not right" / "that's incorrect"
• "don't do that" / "never do that" / "stop doing that"
• "that's not what I asked" / "I said X not Y"
• "undo that" / "revert that" / "that broke things"
• "you already made this mistake" / "we went through this"
• "use X instead" / "the correct way is..." / "actually..."
• Any explicit statement that your output, approach, or code was wrong

When a user correction is detected:

1. Acknowledge the correction immediately. Do not defend the wrong approach.
2. Analyze what went wrong — why did you produce the wrong output? Was it a misunderstanding, a wrong assumption, a pattern you defaulted to incorrectly?
3. Extract a lesson following the same format as technical errors, but use category correction:

### [YYYY-MM-DD] correction: one-line summary of what to do differently
-**Error**: What you did wrong (the incorrect action or output)
-**Root cause**: Why you did it (wrong assumption, default behavior, misread context)
-**Fix**: What the correct approach is (the user's preferred way)
-**Prevention**: Rule to follow in this project going forward
-**Hits**: 1

1. User corrections skip the confidence gate — they go directly to Active Lessons. The user IS the ground truth. One correction is enough.

Examples of correction-based lessons:

• User says "don't use semicolons in this project" → [correction] This project uses no-semicolon style
• User says "we use pnpm not npm here" → [correction] Use pnpm for all package operations
• User says "stop adding comments to my code" → [correction] Do not add comments unless explicitly requested
• User says "that's not how our API works, the endpoint is /v2/ not /v1/" → [correction] API base path is /v2/ in this project
• User says "you keep installing the wrong version" → [correction] Pin dependency to version X.Y.Z

What makes this different from CLAUDE.md:

• CLAUDE.md stores proactive instructions the user writes upfront
• learn-by-mistake correction lessons capture reactive fixes from real interactions
• Correction lessons include the WRONG approach too — so you know what NOT to do

2. Error Detection — Check Lessons FIRST

When you encounter ANY error — whether technical (test failure, build error, runtime crash, command failure) OR conversational (user correction, wrong approach, misunderstood requirement) — follow this sequence before attempting a fix:

Step A: Search for matching lesson

Read .claude/lessons.md (if it exists). Scan the Active Lessons section for entries where the Error pattern matches the current error. Match on:

• Error message substrings
• Error category (build, test, runtime, types, linter, git, dependency, config)
• File or module patterns
• Root cause similarity

Step B: If a matching lesson is found

1. Apply the Prevention rule and the Fix from the lesson.
2. Tell the user: "Applying lesson from [date]: [one-line summary]"
3. Increment the Hits counter for that lesson in .claude/lessons.md.
4. Proceed with the fix using the known solution as your starting point.

Step C: If no matching lesson is found

1. Fix the error using normal debugging.
2. After fixing, evaluate whether to extract a lesson (see Section 3).

3. After Fixing — Lesson Extraction Decision

Once an error is resolved, decide whether it warrants a lesson. This is the most important judgment call in the system. Be selective — only high-value, reusable lessons belong here.

WRITE a lesson when:

• The error reveals a pattern that could recur in this project or similar projects.
• The root cause was non-obvious — you had to investigate, read docs, or try multiple approaches.
• The fix requires understanding beyond what the error message alone provides.
• The prevention rule is generalizable — it can be stated as a reusable principle.
• The error came from a systemic issue (wrong config pattern, misunderstood API, version incompatibility).

DO NOT write a lesson when:

• Simple typo or syntax error — missing comma, unmatched bracket, misspelled variable.
• Environment-specific one-off — network timeout, disk full, service temporarily down.
• Fix was obvious from the error message — "Module not found: foo" fixed by import foo.
• External service issue — third-party API outage, CDN failure.
• User explicitly caused it — intentional test of error handling, exploratory debugging.

When in doubt, add it to Pending (see Section 4). The confidence gate will filter noise.

4. Confidence Gate — Pending vs Active

Not every error deserves a permanent lesson. The confidence gate prevents one-off flukes from cluttering the lesson file.

First occurrence of an error pattern

• Add the lesson to the ## Pending section.
• Set Hits: 1.
• Tell the user: "New lesson learned: [one-line summary]"

Second occurrence of the same pattern

• Move the lesson from ## Pending to ## Active Lessons.
• Set Hits: 2.
• Tell the user: "Lesson confirmed (2nd occurrence): [one-line summary]"

Force-promote with /learn

• The user can run /learn after any fix to immediately promote a pending lesson to active, or to create a new active lesson directly.
• When /learn is invoked without a recent error, ask the user what lesson they want to record.

5. Secret Sanitization — CRITICAL

Before writing ANY content to `.claude/lessons.md`, scan every field for secrets and redact them. This is non-negotiable. A lesson file may be committed to version control.

Patterns to detect and redact:

If uncertain whether something is a secret:

• Ask the user before writing: "This looks like it might contain sensitive data: [description]. Should I include it or redact it?"
• Default to redacting. False positives are harmless; leaked secrets are not.

6. Lesson Format

Every lesson follows this exact format. No exceptions.

### [YYYY-MM-DD] category: one-line summary
-**Error**: The error message or pattern (sanitized, enough to match against)
-**Root cause**: Why it actually failed — the real bug, not the symptom
-**Fix**: What resolved it — specific, actionable, referencing project files/config when relevant
-**Prevention**: Reusable rule to check BEFORE this error can happen again
-**Hits**: N

Categories

Use exactly one of these categories:

• build — Compilation, bundling, transpilation failures
• test — Test assertion failures, test runner issues, fixture problems
• runtime — Crashes, unhandled exceptions, runtime errors during execution
• types — Type errors, type mismatches, generic constraint issues
• linter — Lint warnings/errors, formatting issues, style violations
• git — Merge conflicts, rebase issues, hook failures, branch problems
• dependency — Package conflicts, version mismatches, missing deps, lockfile issues
• config — Configuration errors, env vars, wrong settings, path issues

Example lesson

### [2026-03-15] build: Vite fails when importing .graphql files without plugin
-**Error**: `Failed to resolve import "*.graphql"` during `npm run build`
-**Root cause**: Vite does not natively handle `.graphql` file imports. The dev server worked because of a Babel plugin in the dev config, but the production build used a different pipeline that lacked the plugin.
-**Fix**: Added `vite-plugin-graphql` to `vite.config.ts` plugins array and moved the GraphQL transform from Babel config to the Vite plugin.
-**Prevention**: When adding file-type imports beyond JS/TS/CSS/JSON, always configure BOTH dev and production build pipelines. Check `npm run build` after adding any new import type.
-**Hits**: 3

7. Lesson File Structure

The .claude/lessons.md file uses this structure:

# Lessons Learned
 
> Auto-generated by learn-by-mistake. Do not remove the section headers.
 
## Active Lessons
<!-- Promoted lessons applied preventively. Max 50. Sorted by Hits descending. -->
 
## Pending
<!-- First-occurrence errors awaiting confirmation. Max 20. -->
 
## Archive
<!-- Pruned or demoted lessons kept for reference. -->

Rules:

• Active Lessons: Max 50 entries. These are checked against every error.
• Pending: Max 20 entries. Awaiting second occurrence to promote.
• Archive: No hard limit. Low-priority reference material.
• Always maintain the three section headers even if sections are empty.
• Sort Active Lessons by Hits count (highest first) when rewriting the file.

8. Pruning Rules

The lesson file must stay lean to remain useful. Apply these rules automatically:

When Active Lessons reaches 50:

1. Find the lesson with the lowest Hits count AND the oldest date.
2. Move it to ## Archive.
3. Then add the new lesson to Active.