Instinct System

Core Principles

1. Instincts are hypotheses, not rules — An instinct starts as a guess based on a single observation. It has no authority until confirmed across multiple instances. Never treat a first observation as a project convention. "I saw one handler use sealed " is an instinct at 0.3; "all 12 handlers use sealed" is a rule at 0.9.

2. Confidence scoring drives behavior (0.3-0.9) — Each instinct carries a numeric confidence that determines how Claude acts on it. At 0.3, merely note it. At 0.5, mention it when relevant. At 0.7, follow it by default. At 0.9, promote it to a permanent rule. Never apply a low-confidence instinct without flagging the uncertainty.

3. Project-scoped, never global — Instincts are stored per-project in .claude/instincts.md. What holds true in one codebase may be wrong in another. A project using internal sealed class everywhere says nothing about a different project that uses public class with interface testing. Instincts do not transfer at full confidence.

4. Observe-Hypothesize-Confirm cycle — The lifecycle is disciplined: see a pattern, form a hypothesis, actively seek confirming or disconfirming evidence, adjust confidence accordingly. Passive observation is not enough. When you form an instinct, look for it in the next 2-3 related files.

5. Evolution path to permanence — Instincts are temporary by design. At 0.9 confidence, they graduate to MEMORY.md as permanent rules or trigger updates to relevant skills. An instinct that never reaches 0.7 after 5+ observations should be discarded, not left to rot.

Patterns

Instinct Lifecycle

The full lifecycle from first observation to permanent rule: