oimiragieo/instinct-learning

Instinct Learning

Overview

Instinct Learning records atomic learned behaviors as structured instinct records. Each instinct has a confidence score (0.3–0.9), a project scope, and a promotion pathway to global scope when confidence reaches 0.8.

This prevents knowledge from evaporating between sessions and stops cross-project contamination by isolating low-confidence instincts in the project that generated them.

When to Use

Invoke when:

• An agent observes a reliable pattern that should influence future behavior
• A debugging session surfaces a non-obvious fix that will recur
• A workflow succeeds repeatedly and should be encoded as a default
• An error pattern is identified that should be avoided project-wide

Skill({ skill: 'instinct-learning' });

Iron Law

NO INSTINCT WITHOUT AN OBSERVED BASIS.
Every instinct record MUST include `source_context` describing the observation
that generated it. Invented instincts are worse than no instincts.

Confidence Scale

| Score | Meaning | Promotion Eligible | | ----- | ----------------------------------- | ------------------ | | 0.3 | Seen once, uncertain | No | | 0.4 | Seen twice, possibly coincidental | No | | 0.5 | Consistent in this project | No | | 0.6 | Reliable in this project | No | | 0.7 | Highly reliable, limited cross-test | No | | 0.8 | Auto-promotes to global scope | YES | | 0.9 | Canonical — applies across projects | YES (immediate) |

Instinct Record Schema

Each record in .claude/context/memory/instincts.jsonl follows this structure:

{
  "id": "inst-<uuid-short>",
  "timestamp": "2026-03-23T10:00:00Z",
  "scope": "project",
  "project": "agent-studio",
  "text": "Atomic description of the learned behavior",
  "confidence": 0.6,
  "source_context": "Brief description of the observation that generated this instinct",
  "tags": ["tag1", "tag2"],
  "promoted_at": null,
  "promoted_confidence": null
}

When scope is global, project is null and promoted_at is set to the ISO timestamp of promotion.

Workflow

Step 1: Determine Scope and Text

Identify the atomic behavior to record:

• text: One sentence, imperative mood. "Always use shell: false when spawning child processes."
• scope: Start as project. Auto-promotes when confidence ≥ 0.8.
• confidence: 0.3–0.9. Be honest. See scale above.
• tags: 2–4 lowercase kebab-case tags for discoverability.
• source_context: Why you believe this. One to two sentences.

Step 2: Check for Duplicates

Command:

grep -i "<keyword from instinct text>" C:/dev/projects/agent-studio/.claude/context/memory/instincts.jsonl 2>/dev/null | head -5

Expected output: Existing records matching the pattern, or empty output if new.

Verify: If a duplicate exists, update its confidence instead of creating a new record (see Step 4).

Step 3: Write the Instinct

Command:

node C:/dev/projects/agent-studio/.claude/skills/instinct-learning/scripts/main.cjs \
  --action record \
  --text "{{instinct_text}}" \
  --confidence {{confidence_score}} \
  --tags "{{comma_separated_tags}}" \
  --source "{{source_context}}"

Expected output: {"ok":true,"id":"inst-<id>","scope":"project","promoted":false}

Verify: Exit code 0 and JSON with ok: true.

Step 4: Update Existing Instinct Confidence

If the same pattern is observed again, increase confidence:

Command:

node C:/dev/projects/agent-studio/.claude/skills/instinct-learning/scripts/main.cjs \
  --action update \
  --id "{{instinct_id}}" \
  --confidence {{new_confidence_score}}

Expected output: {"ok":true,"id":"{{instinct_id}}","confidence":{{new_score}},"promoted":{{true_or_false}}}

Verify: If promoted: true is returned, the instinct is now in global scope.

Step 5: Verify Auto-Promotion

When confidence reaches 0.8, auto-promotion fires automatically during the update step. Verify with:

Command:

node C:/dev/projects/agent-studio/.claude/skills/instinct-learning/scripts/main.cjs \
  --action list \
  --scope global \
  --limit 10

Expected output: JSON array of globally-promoted instincts, newest first.

Verify: The newly promoted instinct appears with scope: "global" and promoted_at set.

Step 6: Query Instincts Before Work

Before starting a task, load relevant instincts to guide behavior:

Command:

node C:/dev/projects/agent-studio/.claude/skills/instinct-learning/scripts/main.cjs \
  --action query \
  --tags "{{relevant_tags}}" \
  --min-confidence 0.6

Expected output: JSON array of relevant instincts ordered by confidence descending.

Verify: Exit code 0 and array (may be empty if no matches).

Anti-Patterns

• Never record instincts with confidence 0.9 on the first observation — earn it
• Never invent source_context — if you cannot remember the basis, set confidence to 0.3
• Never use multi-sentence instinct text — atomic means one behavior only
• Never promote manually by editing the JSON — use the update action and let auto-promotion fire
• Never query only global instincts — project-scoped instincts at 0.6+ are highly relevant

Enforcement Hooks

Input validated against schemas/input.schema.json before execution. Output contract defined in schemas/output.schema.json.

Pre-execution hook (hooks/pre-execute.cjs) validates:

• confidence is in range [0.3, 0.9]
• text is non-empty and under 200 characters
• action is a known enum value

Post-execution hook (hooks/post-execute.cjs) emits observability event to .claude/context/runtime/tool-events.jsonl.

Assigned Agents

• developer — records patterns found during implementation
• qa — records patterns from testing and validation
• architect — records structural patterns
• planner — records planning heuristics
• reflection-agent — records patterns surfaced during reflection

Memory Protocol

Before starting: Read .claude/context/memory/learnings.md and check .claude/context/memory/instincts.jsonl for relevant existing instincts.

After completing: Append summary to .claude/context/memory/learnings.md:

**instinct-learning** — [date] Recorded/updated N instincts. Promoted M to global scope.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Related Skills

• memory-search — semantic search over global agent memory
• context-compressor — compress context before long tasks
• session-handoff — persist instincts across session boundaries