# Sinapsis Instincts

> Sinapsis Instincts v4.1

- Skill: `luispitik/sinapsis-instincts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add luispitik/sinapsis-instincts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luispitik/sinapsis-instincts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: luispitik (https://skillmd.com/u/luispitik)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/luispitik/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`:

```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