/instinct-system

name: instinct-system
description: >
  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 skill when you notice a recurring pattern,
  a user corrects your output, or you discover something non-obvious.
  Triggers: "show instincts", "what have you learned", "list instincts",
  "export instincts", "share instincts", "import instincts",
  "load instincts from", "learn this", "I think they always",
  "notice a pattern", "instinct", "hypothesis", "confidence",
  "learn from mistakes", "remember this", "don't do that again",
  "log this", "document this finding", "gotcha", "what did we learn",
  "learnings", "discoveries", or at session start (to load existing knowledge).

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)

1. OBSERVE     — "This handler is internal sealed class. Convention?"
2. HYPOTHESIZE — Write to .claude/instincts.md at confidence 0.3:
                 - Use `sealed` on handler classes | confidence: 0.3 | seen: 1 | last: 2026-06-12
3. SEEK        — Actively check 2-3 related files (find_symbol, get_public_api).
                 Passive observation is not enough.
4. ADJUST      — Confirmed: raise per the adjustment track.
                 Contradicted: halve confidence, note the exception.
                 Mixed: hold steady, note the split.
5. PROMOTE     — At 0.9, present evidence and offer promotion to MEMORY.md.

Instinct Storage Format

`.claude/instincts.md`, grouped by category with structured metadata:

# Project Instincts

## Code Style [0.7]
- Use `sealed` on all handler classes | confidence: 0.8 | seen: 5 | last: 2026-06-12
- Prefix private fields with underscore | confidence: 0.5 | seen: 2 | last: 2026-06-10

## Architecture [0.7]
- Feature folders use singular names | confidence: 0.7 | seen: 4 | last: 2026-06-12

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:

CONFIRMATION:  1st observation → 0.3 | 2nd → 0.5 | 3rd → 0.7 | 4th → 0.8
               5th+ with zero contradictions → 0.9 (promotion candidate)

CONTRADICTION: Any contradiction → halve current confidence (0.7 → 0.35)
               Two in a row → 0.1 (effectively dead)

USER OVERRIDE: Explicit confirm → 0.8 | Explicit correct → 0.0 (remove,
               capture in MEMORY.md instead) | "Sometimes" → cap at 0.5

STALENESS:     No observations for 10+ sessions → flag for review
               Contradicted, unreconfirmed for 5 sessions → remove

Acting on Instincts by Confidence

0.0–0.2 → IGNORE  — insufficient evidence, do not mention
0.3–0.4 → NOTE    — record internally, do not apply
0.5–0.6 → MENTION — "This project may use [pattern]. Follow it?"
0.7–0.8 → FOLLOW  — apply by default, mention on first use
0.9     → PROMOTE — offer to add to MEMORY.md as a permanent rule

Never sile