Learn

Quick Summary

Goal: Teach Claude lessons that persist across sessions by generalizing each lesson to its failure mode and routing it to the carrier a future session will actually read — the matching skill's project protocol when the lesson is skill-specific, otherwise the best-fit prose reference doc, docs/project-config.json when the lesson is really a machine-readable project fact, or the root CLAUDE.md project-rules section when it is a short, broad, project-specific rule or context note every task benefits from.

Summary: read-this-if-nothing-else digest of the main steps —

• Concise learned guidance — state intent, purpose, and the quality gate directly; retain enough context and owner pointers for AI discovery. Apply the Learned Guidance Quality Gate before saving.
• Generalize before anything else — climb from the incident to the reusable failure mode; a lesson naming this ticket's files/services/tools is not a lesson yet.
• Triage (value + recurrence + auto-fix) BEFORE routing — persist only a project convention or a universal best-practice protocol worth reading on everyday work; a rare AI-agent quirk, a one-off incident or a detail of the current task is noise, and so is a lesson a review skill already catches.
• Skill-specific lessons use the project protocol route: when the lesson is an extra rule for a skill — learned during an active skill invocation, during a task whose route matched a skill, naming a skill, or about the kind of task one skill mainly owns (e.g. "when writing integration tests…" → integration-test) — treat it as a candidate overlay for that skill, compare it against the project-reference docs (docs/project-reference by default) and docs/project-config.json before recommending, ask the Carrier Choice question, and on an overlay pick call /project-skill-protocol with add for a new overlay or update <exact-name> only after exact-name resolution; save to a reference doc or config field only when the user picks that carrier.
• Root-context route (CLAUDE.md): a lesson that is a general project rule/convention or project context info (architecture constraint, naming rule, domain term, tool quirk of THIS project) is a candidate for the hand-owned ## Project Rules & Context section of the root CLAUDE.md — only when ALL of: applies to most tasks, ≤ 3 lines, project-specific (a universal framework rule is never a project note), not better served by a reference doc / overlay / config field, and size headroom exists (root ≤ 32768 bytes). Show the exact line + target section and get the user's confirmation, write only that section, then run sync-codex so AGENTS.md and the mirrors follow. Otherwise keep today's routing. Full gate: Project Root Context Route.
• Ask which carrier, with a recommendation: present the carrier options via ask user question tool — recommended option first, labelled (Recommended) — before any write; never pick the carrier silently.
• Keep ordinary routing for ordinary lessons: when the lesson is not skill-specific or no active/matching skill exists, use the existing FACT/RULE carrier route and confirmation flow.
• Classify the carrier, don't default to prose: a lesson stating a project FACT (path, run-command, module map, convention, tooling choice) belongs in docs/project-config.json, the machine-readable map every skill reads first; a lesson stating a RULE or pattern belongs in the matching docs/project-reference/ doc. Both can apply — write the fact to config AND the rule to prose. To learn what the config holds and its exact field names, read the file or use /project-config (it runs --describe).
• Delegate overlay correctness: /project-skill-protocol retains its mode resolution, target/scope resolution, additive-only constraint, collision/contradiction handling, proposal/user-confirmation gate and two-write contract; Learn must not bypass or replace it.
• Assess prevention depth — doc/config update, prompt rule, static protocol lesson, hook, test, or skill update.
• Confirm target with the user, save, then run the 3 mandatory end tasks — Learn Review → /why-review → carrier-specific final quality pass (Markdown enhancement, or configuration parser/schema validation).

Workflow:

1. Capture -- Identify the lesson from user instruction or experience
2. Route -- Analyze lesson content against any active/matching skill, the Reference Doc Catalog, AND docs/project-config.json; select the project-protocol route for skill-specific lessons, otherwise the best target carrier (prose doc, config field, or both)
3. Save -- After the applicable confirmation gates, delegate a skill-specific lesson the user placed in an overlay to /project-skill-protocol; otherwise append the lesson to the selected file (a CLAUDE.md pick writes only the hand-owned ## Project Rules & Context section, and sync-codex runs after the end tasks)
4. Confirm -- Acknowledge what was saved and where
5. Learn Review -- Run the mandatory 2-step end gate (Learn Review + /why-review)

Key Rules:

• GENERALIZE FIRST (the #1 protocol): Extract the GENERIC lesson that applies to many cases — NEVER save the specific case as-is. The user's words describe one incident; your job is to climb from that incident to the reusable rule. Strip every project/file/tool/domain name. If the saved text only helps on this exact ticket, you failed — abstract it up a level. (Enforced by the Lesson Quality Gate below.)
• Triggers on "remember this", "always do X", "never do Y"
• Triage first: pass the Value gate (project convention or universal best-practice protocol, worth reading on everyday work) + Recurrence gate + Auto-fix gate BEFORE routing or saving
• Smart-route to the most relevant file, NOT always lessons.md in the reference-docs root (default docs/project-reference; a docsRoots.projectReference.path entry in docs/project-config.json overrides the path)
• Consider docs/project-config.json on EVERY routing decision — a lesson that is really a project fact (path, run-command, module map, tooling choice) belongs in the machine-readable map, not in prose; read it or use /project-config to know its schema before deciding
• Use exact config schema field names (node .claude/hooks/lib/project-config-schema.cjs --describe) and prefer an existing field — NEVER invent a key, and route config writes through /project-config
• Check for existing entries before creating duplicates
• Confirm target file with user before writing
• Skill-specific route: When any trigger of the Skill-Specific Project-Protocol Route holds (active skill, matched route, named skill, or a task kind one skill owns), treat the lesson as a candidate extension of that skill's project protocol and compare carriers before asking. On an overlay pick, call /project-skill-protocol add ... for a new overlay, or /project-skill-protocol update <exact-name> ... only after exact-name resolution identifies an existing overlay. Save it only to a reference doc, lessons.md or a config field when the user picks that carrier.
• Protocol authority: Preserve /project-skill-protocol's mode resolution, target/scope resolution, additive-only constraint, target-collision and contradiction handling, proposal/user-confirmation gate, three-write contract, and mirror-sync rule. Learn must not bypass or replace any of them.
• Confirmation remains required: Keep Learn's existing user confirmation and mandatory end-task flow; delegating a skill-specific candidate does not waive the project protocol's own proposal/user-confirmation gate.
• Ordinary-route fallback: When no active/matching skill exists or the lesson is not skill-specific, keep the existing FACT/RULE classification, carrier routing, confirmation, save, and end-task flow.
• CLAUDE.md is a destination, not a default: offer it only when every Root-Context condition holds (broad + ≤ 3 lines + project-specific + no better carrier + headroom); a detailed, lookup-style or niche lesson stays in its reference doc, a one-skill rule in an overlay, a machine-readable fact in config, a universal framework rule in a shared protocol. — why: CLAUDE.md is loaded into every session, so each byte costs every task.
• CLAUDE.md consent + sync: NEVER silently self-edit an instruction file — show the exact proposed line and target section, ask via ask user question tool, write only after confirmation, then run sync-codex (after the end tasks) and report which mirrors changed.

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

Contents

• Quick Summary
• Usage
• Reference Doc Catalog (READ before routing)
• Smart File Routing (CRITICAL)
• Budget Enforcement (MANDATORY for lessons.md)
• Behavior
• Auto-Inferred Activation
• How Lessons Reach the AI
• Prompt Enhancement (MANDATORY final step)
• Closing Reminders

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

Add a skill-specific lesson (routes to a /project-skill-protocol overlay)

/learn when reviewing changes, always check that migration scripts are idempotent
/learn /plan should always include a rollback step

Add a project-wide rule or context note (routes to the root CLAUDE.md when it qualifies)

/learn in this repo every new module needs an entry in the module registry before any other change
/learn the term "tenant" always means the billing account here, never a user group

List lessons

/learn list

Remove a lesson

/learn remove 3

Clear all lessons

/learn clear

Reference Doc Catalog (READ before routing)

Reference docs live in the reference-docs root (default docs/project-reference; a docsRoots.projectReference.path entry in docs/project-config.json overrides the path). The session-init-docs.cjs hook initializes missing selected references and always-on routing inputs as placeholders; their declared /scan --target=<key> owners populate them, while manual guides remain owner-maintained. This catalog lists supported carriers, not mandatory files.

Routing is static: read the doc whose Read Trigger matches your task. Before recommending a target, read the configured Doc Lookup and docs index, preserve an existing authoritative project guide, and compare viable alternatives, explaining any new file or selection needed. Keep one owner per rule and link executable budgets and harness details instead of duplicating them.

Key insight: lessons.md and code-review-rules.md are the highest-recurrence routing targets — read them on every relevant task. Place high-recurrence lessons where the matching Read Trigger guarantees a future session opens them.

Also a routing destination: docs/project-config.json (machine-readable, NOT prose)

The catalog above is prose. docs/project-config.json is the project's machine-readable map — modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns — and it is what CLAUDE.md and the docs/project-reference/** docs are generated from. Every skill is told to read it BEFORE investigating, planning, or coding, so a fact recorded there reaches more sessions than the same fact written into one prose doc.

Read Trigger: every task, ahead of the prose docs. Owned by: /project-config.

Learn its shape before routing anything into it — either read docs/project-config.json directly, or invoke /project-config, which knows the schema and its exact field names:

node .claude/hooks/lib/project-config-schema.cjs --describe   # exact field names + per-field derivation notes

Rules:

• MUST check docs/project-config.json as a candidate on EVERY routing decision — why: a project fact written only as prose is invisible to the tooling that reads the config, and is silently overwritten the next time the generated docs regenerate from it.
• MUST use exact schema field names (--describe, copy verbatim) and prefer an EXISTING field over a new one — why: unknown keys are accepted as warnings (project-config-schema.cjs unknown-key warnings), so an invented key looks like it worked while no consumer ever reads it.
• No existing field fits → do NOT invent a top-level key silently. Route the lesson to prose and surface the gap to the user as a proposed schema addition — why: a schema change is a framework decision, not a side effect of /learn.
• Prefer routing the config write through /project-config (Plan → Review → Execute + validation) over hand-editing the JSON — why: it validates after each phase and knows the field names this skill would otherwise guess.
• Config carries FACTS, never prose lessons — NEVER paste a narrative lesson into a config string field. — why: the config is consumed by tooling and by every skill's prefetch; prose there bloats every session and belongs in a reference doc.

Smart File Routing (CRITICAL)

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

All three gates must pass. Persistent memory is read on every task, so it holds only what makes everyday work better: a project convention or a universal best practice. A rare agent quirk or a detail of this session's task costs every future reader attention and prevents nothing; a lesson review skills already catch adds noise; a one-off situational mistake won't be prevented by a persisted rule.

Skill-Specific Project-Protocol Route (BLOCKING)

A project overlay (owned by /project-skill-protocol) is the carrier that fires exactly when the skill runs — a skill-specific rule saved to lessons.md or a prose doc reaches the skill only by chance. Before applying the generic Routing Table, detect whether ANY trigger holds:

Resolve the owning skill (T3/T4): match the lesson's task kind against skill Use when … descriptions in the skills catalog; cite the matching description. One clear owner → exact target. A family sharing a name pattern (e.g. every *-review skill) → glob target. Two or more owners that share no name pattern → one exact overlay per owner, listed together in the Carrier Choice question. No owner, or the rule applies across unrelated tasks → the lesson is NOT skill-specific; use the generic Routing Table. — why: a guessed owner puts the rule where it never fires.

When any trigger holds:

1. Identify the target skill (or glob family) by its exact name, with the evidence that matched it.

2. Treat the lesson as a candidate extension of that skill's project protocol.

3. Compare carriers before recommending (BLOCKING). The overlay is a candidate, not the default. Check it against the same carriers the generic route uses: the Reference Doc Catalog and Routing Table (resolved under the reference-docs root, default docs/project-reference), and docs/project-config.json (FACT vs RULE). Recommend the reference doc when its Read Trigger already fires for this kind of task and the rule is not about the skill's own steps (a T4 lesson about integration tests usually belongs in integration-test-reference.md); recommend the overlay when the rule changes what the skill itself does. — why: a project-reference doc is read by every agent doing that kind of work, while an overlay reaches only runs of that one skill.

4. Carrier Choice question (BLOCKING). ask user question tool with the recommended option FIRST, labelled (Recommended), each option naming its concrete target path:

   • Skill overlay for <skill> via /project-skill-protocol — an exact overlay applies on every run of that skill; a glob overlay applies unless an exact overlay for the same skill exists, because the most specific tier wins
   • Overlay + reference doc — only when the lesson also carries a project-wide rule beyond the skill; name the doc path
   • Reference doc only — name the path, e.g. integration-test-reference.md or lessons.md under the reference-docs root
   • Project config field — when the lesson is a machine-readable FACT (see FACT vs RULE)
   • Root CLAUDE.md project note + sync-codex — only when the lesson also passes the Project Root Context Route candidate test (C1–C5) despite being skill-related; each question holds 2–4 options, so drop the weakest

   State a one-line reason for the recommendation. When the Prevention Depth Assessment applies, ask it as a SECOND question in the same ask user question tool call (each question holds 2–4 options), so the user answers once. — why: the user owns where a persistent rule lives; a silent carrier choice is the main way lessons land where no future run reads them.

5. MUST ATTENTION On an overlay choice, call /project-skill-protocol add ... for a new overlay or /project-skill-protocol update <exact-name> ... only after exact-name resolution identifies an existing overlay (run its list first when unsure).

6. MUST ATTENTION Let /project-skill-protocol perform its own mode resolution, target/scope resolution, additive-only screen, target-collision and contradiction handling, proposal/user-confirmation gate and two-write contract. Do not write overlay bodies or index rows directly from Learn.

7. On a Reference doc only or Project config field pick, continue with Routing Decision Process steps 9–10 (append to the doc, or route the config value through /project-config). On Overlay + reference doc, do both. Do not save the candidate only to lessons.md or another generic prose carrier unless the user picked that option.

If no trigger holds, continue with the generic Routing Table — the carrier confirmation there still offers the options with a recommendation.

Project Root Context Route (CLAUDE.md) (BLOCKING)

The root CLAUDE.md is loaded into EVERY session automatically, so a line there reaches every task with no read step — and costs tokens in every session. It is the right carrier for a short, broad, project-specific rule or context note, and the wrong one for anything detailed. Evaluate this route for every lesson that passed the Triage Gate, alongside the FACT-vs-RULE classification and (when a T1–T4 trigger holds) the skill-specific route.

Candidate test — ALL five must hold, otherwise use today's routing:

Which destination fits:

Durable home (write ONLY here): a hand-owned ## Project Rules & Context section placed outside every <!-- SECTION:key --> fence and every CK:* managed block. ai-context-refresh --mode update rewrites only fence bodies and keeps everything outside them verbatim (updateMarkedSections in generate-claude-md.cjs), and the Codex projection is a heading whitelist (AGENTS_PROJECTION_HEADINGS in sync-context-workflows.mjs) that includes this heading. A note inside a fence is overwritten by the next regeneration; a note under a heading the whitelist omits never reaches AGENTS.md. If the section is absent, create it (heading + bullets) immediately after the ## Doc Lookup — What to Read When section, so it projects early into AGENTS.md and reads before the generated rules. No CLAUDE.md yet → not a candidate: run /ai-context-refresh first or route elsewhere. A path-scoped rule that the project already renders from contextGroups[].rules belongs in config via /project-config (regenerated by ai-context-refresh --mode update), not in this section.

Procedure when C1–C5 hold:

Read .claude/skills/shared/protocols/context-engineering-principles.md when drafting a root-context entry; apply its Instruction-file audit before the existing confirmation/write gates. This does not waive C1–C5 or consent.

1. Measure — read CLAUDE.md byte size (node -e "console.log(require('fs').statSync('CLAUDE.md').size)", platform-neutral) and the section's current size; C5 fails → say so and fall back.
2. Draft — one generic bullet, ≤ 3 lines, no incident nouns (Lesson Quality Gate; the project-convention exception keeps the convention's own terms). Check the section for an existing entry on the same rule — update it instead of adding a duplicate.
3. Confirm (BLOCKING) — ask user question tool with the recommended option first, labelled (Recommended). Show the exact proposed line, the target section, and size before → after / 32768. Options: Root CLAUDE.md project note (+ sync-codex) · Reference doc (name the path) · lessons.md · Skill overlay / config field when one applies (2–4 options; drop the weakest). A rejected or unanswered question writes nothing.
4. Write — Edit only the hand-owned section; never touch a fence, a CK:* block, or generated text.
5. Sync (after the final CLAUDE.md edit) — when AGENTS.md or .codex/ exists, run node .claude/skills/sync-codex/scripts/run-codex-sync.mjs --skip=claude-md (the same root-source handoff ai-context-refresh uses; Windows/macOS/Linux neutral). If the runner fails, keep the task open, report the failing stage and the recovery command, and do not claim the mirrors are current. No Codex mirrors in the project → record "no mirrors" and skip.
6. Verify, read-only — (a) re-measure CLAUDE.md bytes ≤ 32768; (b) the new line lies outside every <!-- SECTION:… --> fence (fence open/close lines above it balance), which is what guarantees update preserves it; (c) the line appears in AGENTS.md; (d) git status --short AGENTS.md .codex .agents .opencode lists the mirrors that changed — report them, never stage or commit.

Routing Table

Route to the most relevant file based on lesson content. Every bare *.md filename in the Route to column resolves inside the reference-docs root (default docs/project-reference; a docsRoots.projectReference.path entry in docs/project-config.json overrides the path):

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 Static Protocol Lesson promotion (see below)
5. Present options to user with ask user question tool — recommended option first, labelled (Recommended), with a one-line reason; on the skill-specific route, ask them as the second question of the Carrier Choice ask user question tool call instead of asking twice:
   • "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 + Static Protocol Lesson" — also add to shared protocol 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.

Static Protocol Lesson Promotion (MANDATORY evaluation)

After generalizing a lesson, evaluate whether it qualifies as a Static Protocol Lesson in .claude/skills/shared/sync-inline-versions.md. Static protocol lessons live in that canonical file and reach every session through the universal hook (the universal group of protocol-groups.json); the root CLAUDE.md and AGENTS.md carry none of them.

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