EasyPlatform 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 ATTENTION ask user whether to skip.

Final task is ALWAYS: "Run

/prompt-enhance <modified-file>

to optimize lesson content for AI attention anchoring." Do NOT mark the skill complete until this runs.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

AI Mistake Prevention — Failure modes to avoid on every task:

• Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal.
• Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing.
• Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain.
• Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path.
• When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site.
• Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code.
• Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks.
• Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis.
• Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly.
• Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path.

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"
• Triage first: pass Recurrence gate + Auto-fix gate BEFORE routing or saving
• 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/

session-init-docs.cjs

/scan-*

project-structure-reference.md

subagent-init-*.cjs

/scan-project-structure

backend-patterns-reference.md

code-patterns-injector.cjs

backend-context.cjs

/scan-backend-patterns

frontend-patterns-reference.md

code-patterns-injector.cjs

frontend-context.cjs

/scan-frontend-patterns

integration-test-reference.md

/scan-integration-tests

feature-docs-reference.md

/scan-feature-docs

code-review-rules.md

code-review-rules-injector.cjs

/scan-code-review-rules

lessons.md

prompt-injections.cjs

/learn

scss-styling-guide.md

design-system-context.cjs

/scan-scss-styling

design-system/README.md

design-system-context.cjs

/scan-design-system

e2e-test-reference.md

code-patterns-injector.cjs

/scan-e2e-tests

domain-entities-reference.md

backend-context.cjs

frontend-context.cjs

/scan-domain-entities

docs-index-reference.md

/scan-docs-index

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)

Lesson Triage Gate (MANDATORY — run FIRST, before routing or saving)

/learn

/code-review

/simplify

/security

/lint

/learn

Both gates must pass. A lesson review skills already catch adds noise without value. A one-off situational mistake won't be prevented by a persisted rule.

Routing Table

Route to the most relevant file based on lesson content:

docs/project-reference/code-review-rules.md

docs/project-reference/backend-patterns-reference.md

docs/project-reference/frontend-patterns-reference.md

docs/project-reference/integration-test-reference.md

docs/project-reference/e2e-test-reference.md

docs/project-reference/domain-entities-reference.md

docs/project-reference/project-structure-reference.md

docs/project-reference/scss-styling-guide.md

docs/project-reference/design-system/README.md

docs/project-reference/feature-docs-reference.md

docs/project-reference/docs-index-reference.md

docs/project-reference/lessons.md

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:

docs/project-reference/backend-patterns-reference.md

development-rules.md

.claude/docs/development-rules.md

prompt-injections.cjs

.claude/hooks/lib/prompt-injections.cjs

.claude/hooks/

lib/dedup-constants.cjs

.claude/hooks/tests/

test-all-hooks.cjs

.claude/skills/

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

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

injectAiMistakePrevention()

→ "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

`- **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 root-cause level and generic across any codebase. Apply this 3-step extraction before saving:

Step 1 — Name the FAILURE MODE, not the symptom:

The failure mode is the reasoning or assumption that broke — not what the output looked like.

Step 2 — Verify generality:

Does this failure mode apply to ≥3 different contexts or codebases? If only one file or one specific case → go up one abstraction level. A good lesson prevents an entire class of mistakes.

Step 3 — Write as a universal rule:

• Strip ALL project-specific names, file paths, class names, and tool names
• Must be useful on any codebase, any language, any task type
• If multiple mistakes share the same failure mode → consolidate to ONE lesson, not many
• Test: "Would an AI working in Java, Go, or Python on a different project benefit from this?" If yes → good. If no → rewrite.

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."
• BAD: "Read GlobalUsings.cs before adding usings in *.IntegrationTests" → project-specific file
• GOOD: "Before generating code that uses project conventions (imports, namespaces, annotations), read the project's bootstrap/configuration files for that layer — convention files override framework defaults silently."

Routing Decision Process

1. Run Triage Gate — recurrence + auto-fix filters; stop here if either fails
2. Read the lesson text — identify keywords and domain
3. Apply Lesson Quality Gate — analyze root cause, generalize, verify universality
4. Run Prevention Depth Assessment — determine if doc-only or deeper prevention needed
5. Match against Routing Table — pick the best-fit file
6. Tell the user: "This lesson fits best in

   docs/{file}

   . Confirm? [Y/n]"
7. On confirm — read target file, find the right section, append the lesson
8. On reject — ask user which file to use instead

Format by Target File

For

docs/project-reference/lessons.md

- [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

Hard limit: 10000 characters (~3333 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 > 10000 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

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

Injection

Lessons are injected by

lessons-injector.cjs

• 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

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

• IMPORTANT MUST ATTENTION run Triage Gate FIRST — if recurrence is low OR review skills can catch it, skip

  /learn

  entirely
• IMPORTANT MUST ATTENTION check Reference Doc Catalog to find the best target file — NOT always

  lessons.md

• IMPORTANT MUST ATTENTION final task is ALWAYS: run

  /prompt-enhance <modified-file>

  — do NOT mark complete until this runs
• IMPORTANT MUST ATTENTION break work into small todo tasks using

  TaskCreate

  BEFORE starting
• IMPORTANT MUST ATTENTION prefer auto-injected files for high-recurrence lessons (higher visibility) <!-- SYNC:critical-thinking-mindset:reminder -->
• MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact. <!-- /SYNC:critical-thinking-mindset:reminder --> <!-- SYNC:ai-mistake-prevention:reminder -->
• MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction. <!-- /SYNC:ai-mistake-prevention:reminder -->