stevengonsalvez/instincts

Instincts — Atomic Behavioral Micro-Learnings

Philosophy

Not every learning needs a full knowledge note. Some are tiny:

• "This project uses tabs, not spaces"
• "Always run pnpm not npm here"
• "The API returns dates as Unix timestamps, not ISO"

These are instincts — atomic rules with confidence that grow stronger through reinforcement and decay through contradiction.

Quick Reference

| Command | Action | |---------|--------| | /instincts | Show active instincts for current project | | /instincts add | Manually add an instinct | | /instincts review | Review and adjust confidence of existing instincts | | /instincts promote | Promote high-confidence instincts to global learnings | | /instincts prune | Remove low-confidence or stale instincts |

Instinct Format

Each instinct is a single YAML entry:

- id: inst-20260310-a1b2c3
  rule: "Use pnpm instead of npm for this project"
  confidence: 0.7
  scope: project          # project | domain | universal
  category: tooling       # tooling | style | api | testing | architecture | convention
  created: 2026-03-10
  last_reinforced: 2026-03-10
  reinforcement_count: 1
  source: "User corrected npm to pnpm"
  tags: [pnpm, npm, package-manager]

Storage

Project-Scoped Instincts

Stored in .agents/instincts.yaml at the project root:

# .agents/instincts.yaml
# Auto-managed by /instincts skill. Edit manually if needed.
version: 1
instincts:
  - id: inst-20260310-a1b2c3
    rule: "Use pnpm instead of npm"
    confidence: 0.7
    scope: project
    category: tooling
    created: 2026-03-10
    last_reinforced: 2026-03-10
    reinforcement_count: 1
    source: "User corrected npm to pnpm"
    tags: [pnpm, npm]

Universal Instincts (Global Knowledge Base)

When an instinct reaches high confidence (>=0.8) and universal scope, promote it to the reflect-kb knowledge base via the reflect CLI:

# Promote instinct to a full learning note
if command -v reflect >/dev/null 2>&1; then
    reflect add docs/solutions/instincts/{instinct-id}.md \
        --entities docs/solutions/instincts/{instinct-id}.entities.yaml
elif [[ -x "$HOME/.local/bin/reflect" ]]; then
    "$HOME/.local/bin/reflect" add docs/solutions/instincts/{instinct-id}.md \
        --entities docs/solutions/instincts/{instinct-id}.entities.yaml
fi

Confidence Scoring

Scale

| Confidence | Meaning | Source | |------------|---------|--------| | 0.3 | Weak signal | Single observation, no explicit confirmation | | 0.5 | Moderate | Confirmed once or observed multiple times | | 0.7 | Strong | Explicitly stated by user or confirmed 3+ times | | 0.9 | Certain | Repeatedly reinforced, never contradicted |

Confidence Dynamics

Reinforcement: confidence = min(0.9, confidence + 0.1)
Contradiction: confidence = max(0.0, confidence - 0.3)
Decay: confidence = max(0.0, confidence - 0.05) per 30 days inactive

Thresholds:

• < 0.3 — Auto-prune (too weak to keep)
• 0.3 - 0.5 — Low confidence, apply cautiously
• 0.5 - 0.7 — Moderate confidence, apply by default
• >= 0.8 — High confidence, candidate for promotion to global

Contradiction Handling

When a new observation contradicts an existing instinct:

1. Reduce confidence of existing instinct by 0.3
2. Create competing instinct with confidence 0.5
3. If existing drops below 0.3, auto-prune it
4. If both survive, flag for user review at next /instincts review

Workflow

Capturing Instincts (During Session)

Instincts are captured from:

1. Explicit corrections: "No, use tabs here" -> instinct about indentation
2. Approved patterns: User accepts a specific approach -> instinct about preference
3. Repeated observations: Same tool/command used 3+ times -> instinct about convention
4. /reflect output: Low-confidence signals from reflect that don't warrant full notes

Step 1: Detect Signal

During conversation, watch for:

• Corrections to assumptions about project conventions
• Explicit preferences ("always", "never", "prefer", "use X not Y")
• Patterns that repeat across the session

Step 2: Check for Existing Instinct

# Check if we already have an instinct for this topic
grep -i "{keyword}" .agents/instincts.yaml 2>/dev/null

• If match found: reinforce (bump confidence by 0.1)
• If contradicts: handle contradiction (see above)
• If new: create with initial confidence

Step 3: Set Initial Confidence

| Signal Source | Initial Confidence | |--------------|-------------------| | Explicit user correction ("always do X") | 0.7 | | User approval of approach | 0.5 | | Repeated observation (3+ times) | 0.5 | | Single observation | 0.3 | | From /reflect low-confidence signal | 0.3 |

Step 4: Write Instinct

Append to .agents/instincts.yaml. Create the file if it doesn't exist.

Step 5: Apply Instincts (Session Start)

At session start, load active instincts:

1. Read .agents/instincts.yaml
2. Filter to confidence >= 0.3
3. Apply as soft rules (not hard requirements)
4. Higher confidence = stronger adherence

Promotion to Global Learnings

When running /instincts promote:

1. Filter instincts with confidence >= 0.8 and scope = universal
2. For each candidate: a. Generate a learning note (using reflect learning_template.md format) b. Generate entity sidecar (.entities.yaml) c. Save to docs/solutions/instincts/{id}.md d. Index via learnings add
3. Mark instinct as promoted: true (don't delete — keep for local quick reference)

Pruning

When running /instincts prune:

1. Remove instincts with confidence < 0.3
2. Decay instincts inactive for 30+ days
3. Show remaining instincts sorted by confidence
4. Allow user to manually remove any

Integration

With /reflect

• /reflect captures HIGH/MEDIUM signals as full learnings
• LOW signals route to instincts instead of being discarded
• This ensures nothing is lost, even weak signals

With Session Start

• Load .agents/instincts.yaml at session start
• Apply as soft context for the session

With .agents/MEMORY.md

• Instincts are complementary to MEMORY.md
• MEMORY.md: free-form project notes (architecture, decisions)
• Instincts: structured rules with confidence tracking
• Instincts that stabilize at high confidence can be "hardened" into MEMORY.md entries