Unified learning-and-memory system: confidence-scored instincts (observe-hypothesize-confirm, stored in .claude/instincts.md), user corrections captured as permanent rules in MEMORY.md, and organic discoveries logged to .claude/learning-log.md. Includes status, export, and import modes. Load this sk

Instinct System One learning system, three tiers. Every signal Claude receives during work — an observed pattern, a user correction, a surprising discovery — routes to exactly one store. Core Principles 1. Three tiers, one routing decision — Instincts are unconfirmed hypotheses ( .claude/instincts.md ). Corrections are user confirmed rules ( MEMORY.md ). Discoveries are insights that explain the world ( .claude/learning log.md ). Rules prescribe behavior; insights describe it; instincts are rules in waiting. Never mix the tiers — a hypothesis in MEMORY.md pollutes permanent knowledge, and a confirmed rule left as an instinct gets forgotten. 2. Instincts are hypotheses, not rules — An instinct starts as a guess from a single observation and has no authority until confirmed. "One handler uses sealed " is an instinct at 0.3; "all 12 handlers use sealed " is a rule at 0.9. Confidence (0.3–0.9) drives behavior: note at 0.3, mention at 0.5, follow at 0.7, promote at 0.9. 3. A user correction is a confirmed instinct at full confidence — When the user corrects you, skip the confirmation cycle entirely. Generalize the lesson, capture it immediately in MEMORY.md with the "why", and confirm what was captured. A correction costs the user 30 seconds today and saves hours across all future sessions — losing one is the most expensive mistake this system can make. 4. Project scoped, never global — What holds in one codebase may be wrong in another. Instincts live per project; transfers between projects go through export/import with confidence decay, never at full confidence. 5. Review at session start, prune periodically — Read MEMORY.md and load instincts at 0.7+ before writing any code; scan recent log entries for the working area. Knowledge captured but never reviewed is wasted effort. Audit all three stores when they bloat — stale instincts, duplicate rules, and unreviewed logs defeat the purpose. Patterns Tier Routing Signal Destination Lifespan Pattern observed, not yet confirmed ("I think they always...") .claude/instincts.md at 0.3 Until promoted or discarded User correction ("no, use X", "don't do that again", "remember this") MEMORY.md immediately, generalized Permanent until proven wrong Instinct reaching 0.9 confidence Promote to MEMORY.md , remove from instincts Permanent Non obvious discovery (bug root cause, gotcha, workaround, perf finding) .claude/learning log.md 3–6 months, then archive or promote Same gotcha logged 3+ times Promote to MEMORY.md as a preventive rule Permanent Session state (done/pending) Handoff via wrap up — not this system Until next session Instinct Lifecycle (Observe Hypothesize Confirm) Instinct Storage Format .claude/instincts.md , grouped by category with structured metadata: Category header [0.7] = average confidence. Standard categories: Code Style, Architecture, Naming, Testing, Data Access, API Design, Configuration, Performance, Tooling. Confidence Adjustment Rules No ad hoc scoring. Follow this track precisely: Acting on Instincts by Confidence Never silently apply an instinct below 0.7. Correction Capture Flow (Tier 2) When the user corrects your output ("no, use X instead", "we don't do it that way", "always/never do X", "remember this"): MEMORY.md format — same categories as instincts, one actionable rule per line: Discovery Logging (Tier 3) Log organic findings to .claude/learning log.md the moment they occur — a 2 line entry written immediately beats a paragraph reconstructed later. Entry format: Log when (and only when) you hit one of these triggers: Those six trigger names are also the category vocabulary — use them verbatim in entries. Routine changes with nothing surprising do not get logged. Session Start Loading Modes Three operations on the instinct store, invoked by name or trigger phrase. Status ("show instincts", "what have you learned", "list instincts") 1. Read .claude/instincts.md ; parse each entry's metadata. 2. Sort by confidence descending, group by category, render as a table: instinct confidence category status (new / stable / reinforced / decaying / promotion candidate). 3. Summarize health: total count, average confidence, recently reinforced vs decaying entries, any conflicting instincts. Export ("export instincts", "share instincts") 1. Read .claude/instincts.md ; filter to confidence 0.7 (threshold configurable). 2. Strip project specific context (file paths, line numbers) while preserving the pattern itself. 3. Write to .claude/instincts export.md with portable metadata. 4. Report what was exported and what was skipped (below threshold), with the output path. Import ("import instincts", "load instincts from") 1. Read the export file (user provided path or .claude/instincts export.md ) and the current .claude/instincts.md . 2. Merge each imported instinct: No local match — add with confidence decayed by 0.2 (0.9 → 0.7); never import above 0.7. Mark source: imported from [project] . Matching instinct exists — keep the higher confidence, mark reinforced. Conflicting instinct exists — present both to the user for resolution; do not auto overwrite local evidence. 3. Write the merged result and report imported / merged / conflicts. Every project must confirm imported patterns locally. Anti patterns Over Eager Pattern Recognition Fixing Without Capturing Logging Everything Write Only Stores Decision Guide Scenario Action First time seeing a pattern Instinct at 0.3, check 2 3 related files Pattern seen 3+ times, no contradictions Raise to 0.7, follow by default Pattern contradicted Halve confidence, note the exception User says "we always do X" Instinct at 0.8 (user confirmation) User corrects your code Generalize → MEMORY.md immediately; drop any matching instinct User says "remember this" / "always/never" Capture in MEMORY.md as stated, generalized Same correction given twice High priority — the rule wasn't captured or reviewed Correction about a one time task Don't store — only reusable patterns User asks to forget a rule Remove from MEMORY.md immediately Non obvious bug, gotcha, workaround, perf surprise Log to learning log with category + files Same gotcha logged 3+ times Promote to MEMORY.md as a preventive rule Instinct at 0.9 Present evidence, offer promotion to MEMORY.md User partially confirms ("only for commands") Narrow scope, reset to 0.5, re confirm Sharing patterns with another project Export at 0.7+, import with 0.2 decay Conflict during import Present both to the user; never auto overwrite Any store bloats (50+ entries/rules) Audit: prune dead, merge duplicates, promote mature Starting a session Load MEMORY.md, instincts 0.7+, recent log entries Related convention learner — detects codebase conventions in bulk; feed its findings in as instincts wrap up — end of session ritual; routes session learnings into the correct tier of this system

instinct-system