learn

[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 against Reference Doc Catalog, select best target file
3. Save -- Append lesson to the selected file
4. Confirm -- Acknowledge what was saved and where
5. Enhance -- Run /prompt-enhance on modified file(s) to optimize AI attention anchoring

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%).

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

Reference Doc Catalog (READ before routing)

Each docs/project-reference/ file is auto-initialized by session-init-docs.cjs hook and populated by /scan-* skills. Understanding their roles is critical for correct routing.

Key insight: Files injected automatically by hooks have higher visibility — lessons placed there are enforced during edits. Files injected on-demand are only seen when skills explicitly read them. Prefer auto-injected files for high-recurrence lessons.

Smart File Routing (CRITICAL)

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

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:

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

System Lessons — Universal AI mistake prevention rules injected into EVERY prompt. Stored in injectLessonReminder() → "Common AI Mistake Prevention" array. Each must be universal, high-recurrence, and silent-failure. READ .claude/hooks/lib/prompt-injections.cjs to check for duplicates before adding.

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 12 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 all docs/project-reference/ files (12 targets):

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.)

Prompt Enhancement (MANDATORY final step)

After saving a lesson to any target file, run /prompt-enhance on the modified file(s) to optimize AI attention anchoring and token quality.

When to run:

• After EVERY successful lesson save (regardless of target file)
• Pass the specific file path(s) that were modified

What it does:

• Ensures the new lesson integrates with existing top/bottom summary anchoring
• Optimizes token usage — tightens prose, merges redundant content
• Verifies no content loss from the save operation

How to invoke:

/prompt-enhance docs/project-reference/<modified-file>.md

Skip conditions (do NOT run prompt-enhance if):

• The save was to lessons.md AND the file is under 1500 chars (too small to benefit)
• The user explicitly requests "save only, no enhance"

Closing Reminders

• MUST check Reference Doc Catalog to find the best target file — NOT always lessons.md
• MUST run /prompt-enhance on modified file(s) after saving (unless skip conditions met)
• MUST break work into small todo tasks using TaskCreate BEFORE starting
• MUST search codebase for 3+ similar patterns before creating new code
• MUST cite file:line evidence for every claim (confidence >80% to act)
• MUST prefer auto-injected files for high-recurrence lessons (higher visibility)