[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip.

Quick Summary

Goal: Teach Claude lessons that persist across sessions by saving to the most relevant reference doc.

Workflow:

1. Capture -- Identify the lesson from user instruction or experience
2. Route -- Analyze lesson content and select the best target file (see routing table)
3. Save -- Append lesson to the selected file
4. Confirm -- Acknowledge what was saved and where

Key Rules:

• Triggers on "remember this", "always do X", "never do Y"
• Smart-route to the most relevant file, NOT always docs/project-reference/lessons.md
• Check for existing entries before creating duplicates
• Confirm target file with user before writing

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Lesson Learning Skill

Teach Claude lessons that persist across sessions. Lessons are smart-routed to the most relevant reference doc and automatically injected into prompts and before file edits.

Usage

Add a lesson

/learn always use the validation framework fluent API instead of throwing ValidationException
/learn never call external APIs in command handlers - use Entity Event Handlers
/learn prefer async/await over .then() chains

List lessons

/learn list

Remove a lesson

/learn remove 3

Clear all lessons

/learn clear

Smart File Routing (CRITICAL)

When saving a lesson, analyze its content and route to the most relevant file:

If lesson is about...	Route to	Section hint
Code review rules, anti-patterns, review checklists, YAGNI/KISS/DRY, naming conventions, review process	docs/project-reference/code-review-rules.md	Add to most relevant section (anti-patterns, rules, checklists)
Backend C# patterns: CQRS, repositories, entities, validation, message bus, background jobs, migrations, EF Core, MongoDB	docs/project-reference/backend-patterns-reference.md	Add to relevant section or Anti-Patterns section
Frontend Angular/TS patterns: components, stores, forms, API services, BEM, RxJS, directives, pipes	docs/project-reference/frontend-patterns-reference.md	Add to relevant section or Anti-Patterns section
Integration tests: test base classes, fixtures, test helpers, test patterns, assertions	docs/project-reference/integration-test-reference.md	Add to relevant section
General lessons, workflow tips, tooling, AI behavior, project conventions, anything not matching above	docs/project-reference/lessons.md	Append as dated list entry

Prevention Depth Assessment (MANDATORY before saving)

Before saving any lesson, critically evaluate whether a doc update alone is sufficient or a deeper prevention mechanism is needed:

Prevention Layer	When to use	Example
Doc update only	One-off awareness, rare edge case, team convention	"Always use fluent validation API" → docs/project-reference/backend-patterns-reference.md
Prompt rule (development-rules.md)	Rule that ALL agents must follow on every task	"Grep after bulk edits" → .claude/workflows/development-rules.md
System Lesson (prompt-injections.cjs)	Universal AI mistake, high recurrence, silent failure, any project	"Re-read files after context compaction" → .claude/hooks/lib/prompt-injections.cjs
Hook (.claude/hooks/)	Automated enforcement, must never be forgotten	"Dedup markers must match" → lib/dedup-constants.cjs + consistency test
Test (.claude/hooks/tests/)	Regression prevention, verifiable invariant	"All hooks import from shared module" → test in test-all-hooks.cjs
Skill update (.claude/skills/)	Workflow step that should always include this check	"Review changes must check doc staleness" → skill SKILL.md update

Decision flow:

1. Capture the lesson
2. Ask: "Could this mistake recur if the AI forgets this lesson?" If yes → needs more than a doc update
3. Ask: "Can this be caught automatically by a test or hook?" If yes → recommend hook/test
4. Evaluate System Lesson promotion (see below)
5. Present options to user with AskUserQuestion:
   • "Doc update only" — save to the best-fit reference file (default for most lessons)
   • "Doc + prompt rule" — also add to development-rules.md so all agents see it
   • "Doc + System Lesson" — also add to prompt-injections.cjs System Lessons (see criteria below)
   • "Full prevention" — plan a hook, test, or shared module to enforce it automatically
6. Execute the chosen option. For "Full prevention", create a plan via /plan instead of just saving.

System Lesson Promotion (MANDATORY evaluation)

After generalizing a lesson, evaluate whether it qualifies as a System Lesson in .claude/hooks/lib/prompt-injections.cjs. System Lessons are injected into EVERY prompt — they are the highest-visibility prevention layer.

Qualification criteria (ALL must be true):

1. Universal — Applies to ANY AI coding project, not just this codebase
2. High recurrence — AI agents make this mistake repeatedly across sessions without the reminder
3. Silent failure — The mistake produces no error/warning; it silently degrades output quality
4. Not already covered — No existing System Lesson addresses the same root cause

Current System Lessons (read .claude/hooks/lib/prompt-injections.cjs → injectLessonReminder() → "Common AI Mistake Prevention" section to check for duplicates).

If qualified: Recommend "Doc + System Lesson" option. On user approval, append the lesson as a new bullet to the System Lessons array in prompt-injections.cjs following the existing format: `- **Bold title.** Explanation sentence.`

If NOT qualified: Explain why (e.g., "Too project-specific", "Already covered by existing System Lesson about X", "Low recurrence — only happens in rare edge cases"). Proceed with doc-only or prompt-rule option.

Lesson Quality Gate (MANDATORY before saving)

Every lesson MUST be generic and reusable across any project. Before saving:

1. Analyze root cause — Why did this mistake happen? What is the underlying pattern?
2. Generalize — Strip project-specific names, file paths, and tool names. Express the lesson as a universal principle.
3. Verify universality — Would this lesson help an AI working on a completely different codebase? If no → rewrite until yes.

Anti-pattern examples:

• BAD: "Always check lib/dedup-constants.cjs for marker strings" → project-specific path
• GOOD: "When consolidating modules, ensure shared constants are imported from a single source of truth — never define inline duplicates."
• BAD: "Update .claude/docs/hooks/README.md after deleting hooks" → project-specific file
• GOOD: "Deleting components causes documentation staleness cascades — map all referencing docs before removal."

Routing Decision Process

1. Read the lesson text — identify keywords and domain
2. Apply Lesson Quality Gate — analyze root cause, generalize, verify universality
3. Run Prevention Depth Assessment — determine if doc-only or deeper prevention needed
4. Match against routing table — pick the best-fit file
5. Tell the user: "This lesson fits best in docs/{file}. Confirm? [Y/n]"
6. On confirm — read target file, find the right section, append the lesson
7. On reject — ask user which file to use instead

Format by Target File

For docs/project-reference/lessons.md (general lessons):

- [YYYY-MM-DD] <lesson text>

For pattern/rules files (code-review-rules, backend-patterns, frontend-patterns, integration-test):

• Find the most relevant existing section in the file
• Append the lesson as a rule, anti-pattern entry, or code example
• Use the file's existing format (tables, code blocks, bullet lists)
• If no section fits, append to the Anti-Patterns or general rules section

Budget Enforcement (MANDATORY for docs/project-reference/lessons.md)

docs/project-reference/lessons.md is injected into EVERY prompt and EVERY file edit. Token budget must be controlled.

Hard limit: 3000 characters (~1000 tokens). Check BEFORE saving any new lesson.

Workflow when adding to docs/project-reference/lessons.md:

1. Read file, count characters (wc -c docs/project-reference/lessons.md)
2. If current + new lesson > 3000 chars → trigger Budget Trim before saving
3. If under budget → save normally

Budget Trim process:

1. Display all current lessons with char count each
2. Evaluate each lesson on two axes:
   • Universality — How often does this apply? (every session vs rare edge case)
   • Recurrence risk — How likely is the AI to repeat this mistake without the reminder?
3. Score each: HIGH (keep as-is), MEDIUM (candidate to condense), LOW (candidate to remove)
4. Present to user with AskUserQuestion: "Budget exceeded. Recommend removing/condensing these LOW/MEDIUM items: [list]. Approve?"
5. On approval: condense MEDIUM items (shorten wording), remove LOW items, then save new lesson
6. On rejection: ask user which to remove/condense

Condensing rules:

• Remove examples, keep the rule: "Patterns like X break Y syntax" → just state the rule
• Merge related lessons into one if they share the same root cause
• Target: each lesson ≤ 250 chars (one concise sentence + bold title)

Does NOT apply to: Other routing targets (backend-patterns-reference.md, code-review-rules.md, etc.) — those files have their own size and are injected contextually, not on every prompt.

Behavior

1. /learn <text> — Route and append lesson to the best-fit file (check budget if target is lessons.md)
2. /learn list — Read and display lessons from ALL 5 target files (show file grouping + char count for lessons.md)
3. /learn remove <N> — Remove lesson from docs/project-reference/lessons.md by line number
4. /learn clear — Clear all lessons from docs/project-reference/lessons.md only (confirm first)
5. /learn trim — Manually trigger Budget Trim on docs/project-reference/lessons.md
6. File creation — If target file doesn't exist, create with header only

Auto-Inferred Activation

When Claude detects correction phrases in conversation (e.g., "always use X", "remember this", "never do Y", "from now on"), this skill auto-activates. When auto-inferred (not explicit /learn), confirm with the user before saving: "Save this as a lesson? [Y/n]"

Storage

Lessons are distributed across 5 files:

File	Content type
docs/project-reference/code-review-rules.md	Review rules, anti-patterns, conventions
docs/project-reference/backend-patterns-reference.md	Backend C# patterns and rules
docs/project-reference/frontend-patterns-reference.md	Frontend Angular/TS patterns and rules
docs/project-reference/integration-test-reference.md	Test patterns and rules
docs/project-reference/lessons.md	General lessons (fallback)

Injection

Lessons are injected by lessons-injector.cjs hook on:

• UserPromptSubmit — docs/project-reference/lessons.md content (with dedup)
• PreToolUse(Edit|Write|MultiEdit) — docs/project-reference/lessons.md content (always)
• Pattern reference files are injected by their respective hooks (code-patterns-injector.cjs, code-review-rules-injector.cjs, etc.)