Sinapsis Instincts

Sinapsis Instincts v4.1

> Knowledge base that stores learned behavioral patterns (instincts). > Instincts are the atomic unit of Sinapsis knowledge -- > each one encodes a validated trigger-action pattern that gets > injected automatically when the context matches. > THIS SKILL IS ALWAYS ACTIVE. Apply instincts automatically.

---

What Is an Instinct?

An instinct is a validated behavioral pattern with three properties:

trigger_pattern: regex that matches tool name + input context
inject:          message injected as systemMessage when matched
domain:          category for dedup (one instinct per domain per tool use)
level:           draft | confirmed | permanent

Examples:

• trigger: api.?key|secret|password → inject: "Never hardcode secrets. Use env vars." (domain: security)
• trigger: git commit|commit message → inject: "Use conventional commits." (domain: git)
• trigger: try|catch|error|exception → inject: "Handle errors explicitly. No silent catches." (domain: code-quality)

---

Three Confidence Levels

draft ──── /analyze-session ────> confirmed ──── /promote ────> permanent
(proposed)    (user validates)     (active)    (user promotes)   (priority)

draft

• Source: Generated by _session-learner.sh when it detects error→resolution patterns
• Behavior: NEVER injected automatically. Stored in _instinct-proposals.json
• Action needed: Review with /analyze-session to confirm or discard

confirmed

• Source: User validated via /analyze-session
• Behavior: Injected as systemMessage when trigger_pattern matches current tool context
• Stored in: _instincts-index.json

permanent

• Source: Promoted via /promote or /evolve
• Behavior: Same as confirmed, but wins in domain dedup conflicts
• Priority: permanent > confirmed when two instincts share the same domain

---

Storage Format

Instincts are stored in ~/.claude/skills/_instincts-index.json:

{
  "version": "4.1",
  "instincts": [
    {
      "id": "env-vars-never-hardcode",
      "domain": "security",
      "level": "confirmed",
      "trigger_pattern": "api.?key|secret|password|token|credential|\\.env",
      "inject": "Never hardcode secrets. Use environment variables.",
      "origin": "manual",
      "added": "2026-01-01"
    }
  ]
}

Fields

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier (kebab-case) | | domain | string | Category tag for dedup (security, git, code-quality, tooling, etc.) | | level | string | draft / confirmed / permanent | | trigger_pattern | string | Regex tested against tool_name + tool_input (case-insensitive) | | inject | string | Message injected as systemMessage when matched | | origin | string | How it was created: manual, session-learner, /evolve | | added | string | ISO date when the instinct was added |

---

Domain Dedup

The _instinct-activator.sh hook enforces these rules on every tool use:

1. One instinct per domain — if multiple instincts from the same domain match, only the highest-level one fires
2. Maximum 3 domains — even if 5 domains match, only the top 3 are injected
3. Level priority — permanent > confirmed (drafts are never injected)
4. No contradictions — Claude never receives conflicting instructions from the same domain

Example: 3 instincts match current tool use

  [security]     permanent: "Never hardcode secrets"     ← INJECTED
  [security]     confirmed: "Validate all API inputs"    ← SKIPPED (dedup)
  [git]          confirmed: "Use conventional commits"   ← INJECTED
  [code-quality] confirmed: "Handle errors explicitly"   ← INJECTED

  Result: 3 systemMessages injected, 1 skipped by domain dedup

---

How Injection Works

The _instinct-activator.sh hook runs on every PreToolUse event (sync, 5s timeout):

1. Reads _instincts-index.json
2. Builds context string from tool_name + relevant tool_input fields
3. Tests each instinct's trigger_pattern (regex, case-insensitive) against context
4. Filters out drafts
5. Sorts matches: permanent first, then confirmed
6. Applies domain dedup: one per domain, max 3 total
7. Outputs matched instincts as systemMessage prefixed with [instinct]

---

Creating Instincts

Automatic (via session-learner)

1. Use Claude normally — the observer logs every tool use
2. When you close a session, _session-learner.sh detects error→resolution patterns
3. Detected patterns become draft proposals in _instinct-proposals.json
4. Review with /analyze-session → confirm or discard

Manual (via /evolve)

1. Run /evolve
2. Select [I] to create a new instinct
3. Provide: trigger_pattern, inject message, domain
4. Instinct is added as confirmed to _instincts-index.json

From observation

1. Notice a pattern you want Claude to remember
2. Tell Claude: "Remember: when X, always do Y"
3. Claude can add it to _instincts-index.json directly

---

Commands

/instinct-status

Show all instincts grouped by level and domain.

/analyze-session

Review pending proposals (drafts) and promote to confirmed.

/promote

Promote confirmed instincts to permanent level.

/evolve

Create new instincts manually, or evolve instincts into skills/commands/rules.

---

Integration Points

• _session-learner.sh: Generates draft proposals from error patterns
• _instinct-activator.sh: Injects matching confirmed/permanent instincts
• Skill Router: Uses instinct domains to recommend relevant skills
• Sinapsis Optimizer: Reports instinct count in token budget
• /evolve: Creates instincts manually or evolves them to skills/commands
• Passive Rules: Complementary system — rules fire by regex, instincts fire by domain dedup

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Luispitik
• Source: Luispitik/sinapsis
• License: MIT

Install and usage instructions live in the source repository linked above.