Instinct System

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

Instinct Lifecycle (Observe-Hypothesize-Confirm)

Copy code
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:

markdownCopy code
# 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:

Copy code
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

Copy code
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 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"):

Copy code
1. DETECT      — Recognize the correction signal.
2. ACKNOWLEDGE — "Got it — HybridCache instead of IMemoryCache."
3. GENERALIZE  — Specific: "Don't use IMemoryCache in the Orders endpoint"
                 General:  "Always use HybridCache over IMemoryCache —
                            stampede protection + L1/L2 out of the box."
                 Ask: is this specific to this file? This layer? What's the
                 underlying principle? Store the broadest correct statement.
4. CHECK       — Scan MEMORY.md for overlap. Update an existing rule rather
                 than adding a near-duplicate.
5. STORE       — Write under the right category, one line, rationale after
                 the dash. If a matching instinct exists, remove it — it
                 just graduated.
6. CONFIRM     — "Added to Memory > Data Access: HybridCache over IMemoryCache."

MEMORY.md format — same categories as instincts, one actionable rule per line:

markdownCopy code
## Data Access
- Always use HybridCache over IMemoryCache — stampede protection + L1/L2
- Never use repository pattern over EF Core — use DbContext directly

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:

markdownCopy code
## 2026-06-12 | Gotcha | MassTransit Consumer Registration Order Matters
Multiple consumers for one message type run in registration order; if the
first throws, the rest are skipped. Caused missed audit events.
**Files:** `src/Shared/Extensions/MassTransitConfig.cs:15-30`
**Resolution:** Independent consumer endpoints or the retry filter.

Log when (and only when) you hit one of these triggers:

Copy code
Bug Root Cause        — the cause was NOT where the error appeared
Architecture Decision — discovered WHY something is built a certain way
Gotcha                — framework/library behaved surprisingly
Performance Discovery — unexpected perf behavior, with the measurement
Pattern Found         — reusable codebase pattern worth remembering
External Service      — third-party API behaves differently than documented

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

Copy code
1. Read MEMORY.md — apply rules proactively, don't wait to be reminded
2. Read .claude/instincts.md — load 0.7+ as defaults, note 0.5–0.6
3. Scan recent learning-log entries for the area you're working in
4. Flag stale instincts (10+ sessions without observation) for review

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

Copy code
# BAD — first observation treated as a rule
*Reads one handler* "This project always uses internal sealed class."
*Generates 5 handlers that contradict 8 of 9 existing ones*

# GOOD — hypothesis at 0.3, then active confirmation
"Noticed internal sealed in CreateOrderHandler. Instinct at 0.3.
 Checking 3 more handlers..." *All public* → "Disconfirmed. Discarding."

Fixing Without Capturing

Copy code
# BAD — correction applied, lesson lost
User: "No, we use HybridCache here"
Claude: "Fixed." *Next session: same mistake*

# GOOD — fix AND capture
Claude: "Fixed. Added to Memory > Data Access:
         Always use HybridCache over IMemoryCache."

Logging Everything

Copy code
# BAD — noise entry
## 2026-06-12 | Pattern Found | Used Primary Constructors

# GOOD — only the non-obvious earns an entry
## 2026-06-12 | Gotcha | Primary Constructor Params Captured as Fields
Declaring an explicit field with the same name warns but compiles —
and the two can silently diverge.

Write-Only Stores

Copy code
# BAD — 40 instincts at 0.3 from 3 months ago; MEMORY.md at 200 lines
  with duplicates; 500-line log nobody reads
# GOOD — periodic audit: remove instincts below 0.2 or stale 10+
  sessions; merge/prune MEMORY.md past 50 rules; every ~20 log entries,
  promote recurring findings and archive the stale. Keep instincts
  under 50 active entries.

Decision Guide

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