After fixing a bug or receiving a correction, capture the lesson\nto prevent future mistakes.
\n/phx:learn-from-fix Fixed N+1 query in user listing - was missing preload\n/phx:learn-from-fix String vs atom key mismatch in params handling\n/phx:learn-from-fix LiveView assign_async needs render_async in tests\n/phx:learn-from-fix --library ical --scope personal ICal.to_ics output needs CRLF line endings\n/phx:learn-from-fix --library ical --scope project Use method: \"PUBLISH\" for calendar feeds\nPersist only one of:
\nStop without writing if neither condition is met.\nDo not save a hypothesis, unverified workaround, investigation narrative, or\nunsolved error. Use /phx:compound for a detailed completed investigation.\nCapture the root cause as a concise actionable rule, not the symptom.
When both --library <package> and --scope personal|project are present,\nuse the Library Route. Require both flags; do not guess scope.\nFor the skill directory only, trim surrounding whitespace and lowercase the\npackage name. Preserve underscores when forming directory names\n(phoenix_live_view becomes hex-phoenix_live_view).\nValidate the normalized name against ^[a-z][a-z0-9_]+$. If it does not match,\nask for a valid Hex package identifier instead of replacing characters or\ninventing a name. Use the trimmed original identifier, not the normalized\ndirectory name, to look up mix.lock.
Without --library, use the General Correction Route.
Check if already documented:
\n~/.claude/CLAUDE.md for the pattern keyword~/.claude/skills/hex-<package>/SKILL.md and\n.claude/skills/hex-<package>/SKILL.md${CLAUDE_SKILL_DIR}/references/common-mistakes.md (read-only plugin\nreference)Do not duplicate the same lesson across CLAUDE.md, memory, and a package skill.\nIf the same rule exists, merge wording or report it as already captured.
\nPlugin files are read-only: files under ~/.claude/plugins/ are cached\nand get overwritten on updates. Package skills are user-owned files, never\nplugin cache files.
--scope | \nCanonical destination | \n
|---|---|
personal | \n~/.claude/skills/hex-<package>/SKILL.md | \n
project | \n.claude/skills/hex-<package>/SKILL.md | \n
Personal skills override same-named project skills. If a personal\nhex-<package> skill exists, never unknowingly create or update a shadowed\nproject skill: explain the conflict and ask whether to update personal scope or\nkeep distinct project-only knowledge. If project scope already exists before a\npersonal write, warn that the new skill will shadow it and offer to merge or\nmove it. Maintain one canonical skill per package unless the user explicitly\nneeds distinct scope-specific rules; never create one skill per lesson.
Inspect mix.lock for the package. Record the exact locked version when found.\nIf it is absent, say the lesson is not tied to a locally locked version and do\nnot invent one. Qualify version-sensitive rules. When two verified rules\nconflict across versions, preserve both with explicit version ranges instead of\nreplacing either.
For a new package skill, create:
\n---\nname: hex-<package>\ndescription: <Package/module/API/task trigger terms for this knowledge>\nuser-invocable: false\n---\n\n# <Package> Knowledge\n\n## Verified Rules\n\n- **<Rule>** (verified with <package> <version>): <actionable guidance>\nMake the description precise: include the Hex package, Elixir module names,\nimportant APIs/file formats, and tasks that should trigger this knowledge.\nActivation is model-selected from this description; package presence in\nmix.lock does not guarantee activation.
Before updating an existing skill, read all of it. Preserve unrelated and\nhand-authored sections. Merge semantically identical rules. If safe merging is\nunclear, show the conflict and ask instead of overwriting content.
\nDo not add paths: to a personal package skill by default: it is a file-path\nactivation gate, not a dependency predicate. Add paths: only to project scope\nwhen explicitly appropriate and meaningful package-specific paths exist.
Choose the narrowest non-library destination:
\n| Scope | \nWrite to | \nExample | \n
|---|---|---|
| This project | \nProject CLAUDE.md | \n\"Never use raw SQL in this app\" | \n
| This project across sessions | \nProject-keyed auto-memory | \n\"jsonb uses string keys\" | \n
| All your projects | \n~/.claude/CLAUDE.md personal instructions | \n\"Prefer explicit error tuples\" | \n
| Detailed completed fix | \n.claude/solutions/ via /phx:compound | \nDebugging narrative | \n
For project or personal instructions, preserve existing content and append\n**RULE NAME** — Do NOT [bad]. Instead [good] under the relevant category. Use\npersonal instructions only for rules that should load in every project. For\nauto-memory, append to the project-keyed\n~/.claude/projects/{project-hash}/memory/MEMORY.md:
### Lesson: [Title]\n- **Pattern**: Do NOT [bad] — instead [good]\n- **Why**: [root cause explanation]\nIf the lesson is universal to the plugin rather than one project or package,\nsuggest a plugin contribution; never write it into cached plugin files.
\nAfter capturing, confirm:
\nLesson captured in [location]\n\nPattern: Do NOT [bad pattern] — instead [good pattern]\nCategory: [Ecto/LiveView/OTP/Testing/etc]\nVersion: [locked package version, not found, or not applicable]\nFor package skills, also state that description-based activation is\nmodel-selected, not guaranteed by mix.lock.
${CLAUDE_SKILL_DIR}/references/common-mistakes.md — Common Elixir mistakes\nreference. Consult when checking for duplicates.